{"openapi":"3.1.0","info":{"title":"Cypress Integrations API","version":"1.11.0","description":"Machine-to-machine API for seller organizations on the Cypress marketplace: push inventory,\nmanage listings and pricing, and receive signed event notifications at your endpoint.\nSince 1.5.0 the same API serves apps and AI agents an organization connects through Connect Cypress (OAuth 2.1),\nwith the same rules, and the work around a sale: offers, the CRM, tasks, closings, marketing and automations.\n\nTwo surfaces over one core: the **Cypress API** (`/api/v1`, canonical — PATCH semantics, bulk up to 500)\nand the **Manheim-compatible dialect** (`/api/compatible/v1` — Units/Offerings/Subscribers with\nManheim's conventions: 201 + Location, update-is-POST → 204, action URLs). A vehicle pushed through\none surface is fully manageable through the other.\n\n**Draft-first**: pushed vehicles land unlisted; review or automation launches them —\nor opt into `listingMode: IMMEDIATE` to go live in the same request.\n\n**Changes in 1.11.0 — paying the commission from Cypress's own app.** Additive, except one fix (below):\n- **start_commission_payment** (POST /api/v1/closings/{id}/commission-invoice/checkout, `closing:write`): for the seller, in an app\n  Cypress made (Grove), the closing's commission invoice as an embedded Stripe payment: `clientSecret` and `publishableKey` for\n  Stripe's own card form, which the person fills in (card details reach Stripe only). Paid, the fee step completes as from Pay Now;\n  `saveCard` keeps the card for the next commissions. Paying stays a person's: agents, API keys and apps Cypress did not make are refused.\n- **Fix: each side sees only its own signing links** on `get_closing_signatures` too (the seller got every party's, the buyer's included);\n  only Cypress staff see them all. A new address for another party's signer (`correct_signer_email`) is Cypress staff's to set.\n\n**Changes in 1.10.0 — what holding a car costs, what a rule may list, and what runs by itself.** Additive, except two fixes (below):\n- **The cost of waiting** on GET /api/v1/planning/vehicles/{id} (`get_plan_vehicle`): `economics` (bi-weekly `points` of the projected\n  value and what you end up with if released that week, the `bestWindow`, the 1/3/6-month `waits`, `monthlyCost` of value and running,\n  `weeklyRunningCost`, and its `basis`), and `verdict.reason`. **Every value carries its year ahead**: `curve` on `estimate_value`.\n- **Fix: a pricing rule lists a car only with the listing checklist** the Launch button checks (location state, mileage, condition; the\n  rule's price is the asking price): otherwise it is refused with what is missing and the car stays (`apply_pricing_rule(s)`). The\n  bulk preview names it in `missing` and carries the offer lines (`computedAutoAcceptAbove`, `computedAutoDenyBelow`).\n- **Condition checked in person**: `conditionChecked` on `edit_vehicle` (people only) and `conditionCheck` (`checkedOn`, `by`) on the\n  vehicle read; listing readiness warns `conditionCheck` when nobody has and there is no inspection.\n- **What runs by itself**: `owner` on every automation, and `owner=cypress|all` on GET /api/v1/automations lists Cypress's own\n  automations that run on your records (read-only, their published steps; a write answers 404), even with the Automations product off.\n- **Stuck drafts** in Mission Control: kind `stuck-draft`, drafts with a floor not sent to review in 7 days (by their status date, else\n  when they were added), one item with the cars in `aggregate.entityIds`.\n- **One floor default**: Black Book wholesale +2% in every suggestion (the appraisal, `insights` pricing `suggestedFloor`, the vehicle\n  form); the pricing guidance said +5%. **Fix**: the Floor vs Valuation condition's editor now reads its number as the floor's share\n  of the valuation (120 is 20% above), as Cypress has always compared it; the editor used to save \"20\" as 0.2.\n\n**Changes in 1.9.0 — apps for every member, and the facts worked out.** Additive, except `quarter.spent` (below):\n- **Every member signs in to a connected app** (Connect Cypress), on the organization's connection, each token capped by it; a\n  Cypress Manager signs in to a Cypress app for one customer (`acting_for` on `userinfo`); `Cypress-Person-Confirmed: true` carries a\n  person's confirmation on screen (a below-floor accept from an app). First-party scopes (`agent-quality:write`) are Cypress's apps' only.\n- **Offers and closings with the facts worked out:** `waitingHours`, `ofListing`, `underFloorBy`, `answerOrder` and a `summary` on offers\n  received; `counterHoursLeft` on offers made; `lateHours`, `daysLate`, `dueInHours`, `urgency` and `sort=urgency` on closings;\n  `buyerRecord` and `conditionAtOffer` on offers.\n- **Vehicles:** comparable sales (`get_vehicle_comps`, `find_comparable_sales`), keys, damage note and damage lines\n  (`list_vehicle_damages`, `add_vehicle_damage`), `arvisInspection` and `engagement`, undo an archive within 24 hours, location `aliases`,\n  staged imports (`import_vehicles` mode stage, `decide_import_row`, `apply_import`), `read_import_file` (a spreadsheet read as the Import\n  screen reads it), `estimate_value` (a value with its confidence), and `apply_pricing_rules` previews a draft and names the rule.\n- **Pricing, buying, the organization:** `update_pricing_rule`, floors from wholesale (`set_floor_prices` wholesale-percent), picks that\n  learn, `get_purchase_profile`, direct links to one buyer, `accountManager`, delegation with an end date, bank transfers held for a\n  person, tasks that belong to a conversation and go to the organization's Cypress Manager.\n- **Accounts:** `account` (kind, features, limits, used) on the organization and every token; refusal `ACCOUNT_RULES`; dealer requests\n  (`request_dealer_account`, `decide_dealer_request`) and account rules for staff.\n- **Huddle** (`huddle:read`, `huddle:write`): rooms, messages, reactions, conversations, direct messages and the Inbox, as the person.\n- **Agent quality** (Cypress's apps only): benchmark runs, flagged answers and verdicts.\n- **Changed:** `quarter.spent` on the buy plan counts only cars already bought (`spentOrInClosing` is the old figure); an expired\n  delegation is off everywhere; staff bulk launch needs delegation; `CLOSING.STEP.COMPLETED` fires on every path.\n\n**Changes in 1.8.0 — your inventory, kept in step.** Additive, except the archiving rules and two fixes to what a re-push does (below):\n- **Inspection reports.** A vehicle push (POST, PUT, PATCH and bulk, `create_vehicle`, `update_vehicle`, `push_vehicles`) takes\n  `inspectionReportUrl`: a Manheim condition report is read after the push (grade, damages, photos), the same link again changes nothing (a\n  failed one is read again at most once a day), a new one replaces the report, any other link is kept as a link. The push answers `inspectionReport` (QUEUED, UNCHANGED, LINK_ONLY); the\n  vehicle's read carries `inspectionReport`; VEHICLES.UPDATED with `changedFields: [\"inspectionReport\"]` says when it landed.\n- **The whole inventory.** `POST /api/v1/vehicles/bulk?removeMissing=true` (MCP `push_vehicles`): every active Sell vehicle the push\n  leaves out is taken off by the archiving rules below (at once, or Cypress's review when a buyer is involved; not a removal Cypress already rejected);\n  `removals` answers each one's status. `inventoryVins` names an inventory\n  larger than one push, `syncId` labels it, `dryRun=true` previews it, and a push that would take off more than a fifth of the active\n  vehicles (and more than five) is refused (409 MASS_REMOVAL) unless `allowMassRemoval=true`.\n- **`mode=merge`** on `POST /api/v1/vehicles` and `/bulk` (`create_vehicle`, `push_vehicles`): a VIN you already hold takes only the\n  fields you send, as PATCH; a new one is created. `mode=upsert` still replaces, clearing what a push leaves out. A daily feed that\n  carries a few columns merges, so the details Cypress or your team filled in stay.\n- **Archive events.** VEHICLES.DISPOSITION.STAGED and RESOLVED also carry `statusBefore`, `statusAfter` (after the filing, or after the\n  decision), `source` (`api`, `api-sync`, `csv`, `app`) and, from a full-inventory push, `syncId`. Cypress dialect only: Manheim-dialect\n  subscriptions get the events exactly as before.\n- **Archiving rules (changes what existing keys see).** A seller's archive, by any door, is applied at once for planning stock and for a\n  vehicle with no open offer and no sale in progress; one with an open offer or a sale in progress still waits for a Cypress Manager. So\n  `DELETE /api/v1/listings/{id}` on such a car answers 204 (was 202), `POST /api/v1/vehicles/{id}/disposition` and `/departure` answer 200\n  with `archived: true` (were 202), and VEHICLES.DISPOSITION.RESOLVED arrives at once with `automatic: true`, with no STAGED before it.\n  A staged answer says why in `reviewReason` (OPEN_OFFERS, SALE_IN_PROGRESS).\n- **`floorPrice` and saved locations on the push.** A top-level `floorPrice` is the seller's floor, as the CSV import's: set at once on a\n  vehicle not yet live, a request Cypress reviews on a live one (the push answers SET, UNCHANGED or STAGED). A `location.name` matching\n  one of your saved locations fills its address, city, state and ZIP, as the Import does; a name matching none is a warning.\n- **Fix: a re-push keeps an inspection's grade.** A replace (PUT, `mode=upsert`) that sends no `condition` keeps a condition an\n  inspection set; before 1.8.0 it cleared it. A replace that sends `condition` sets it, as before.\n- **Fix: the report endpoints said \"CARFAX or AutoCheck\".** `GET` and `POST /api/v1/vehicles/{id}/history-report` are the inspection\n  report; Manheim's is the one Cypress reads, any other link is kept as a link. Paths and tool names are unchanged.\n\n**Changes in 1.7.0 — invoices your accounts payable can book.** Additive only; nothing changed for existing keys:\n- **Locations.** `poNumber`, the purchase order your organization issued to Cypress for that location, is optional: up to 64 characters,\n  trimmed, and an empty string or null clears it. `GET /api/v1/locations` returns it; `POST /api/v1/locations` and\n  `PATCH /api/v1/locations/{locationId}` accept it, as do the Operate MCP tools `create_location` and `update_location`.\n- **Invoice settings.** `GET /api/v1/billing/invoice-settings` (`get_invoice_settings`): the parts each commission invoice line prints,\n  whether Deal Setup needs a PO, how each close splits into invoices (all open commissions, per vehicle, or grouped by a field), and a\n  preview line. Cypress staff read and set them with `GET` and `PATCH /api/v1/staff/organizations/{id}/invoice-settings`\n  (`get_organization_invoice_settings`, `update_organization_invoice_settings`).\n- **Billing addresses.** `PATCH /api/v1/staff/organizations/{id}/billing` (`update_organization_billing_details`) accepts\n  `billingEmailCc`, up to five more addresses every billing email also goes to.\n\n**Changes in 1.6.0 — platform activity for Cypress staff.** Additive only; nothing changed for existing keys:\n- **Platform activity.** Eight reads for a CM token under `/api/v1/staff/platform-activity/`, each with its Operate MCP tool (area `staff`): the\n  overview, the funnels, buyers or sellers, organizations and people (and one organization), the Cypress team (and one manager), and who comes\n  back month after month. `period` is 7, 30 or 90 days or the quarter so far, in whole UTC days ending yesterday, against as many days before.\n\n**Changes in 1.5.0 — apps and agents, the whole desk on the API, your own ids, and the event log.** Everything is additive except what is listed last\n(\"Changed for existing keys\"):\n- **Connect Cypress and agents.** An app signs in with OAuth 2.1 and PKCE (`/api/oauth/authorize`, `/token`, `/revoke`; discovery at\n  `/.well-known/oauth-authorization-server`), registered with Cypress or, for an MCP client, without registration: its `client_id` is the https\n  address of its client ID metadata document (a public client, PKCE only, no agents), or it registers itself at `POST /api/oauth/register` (RFC 7591; never with agents). An organization's admin approves it, and its tokens act for that admin or for the agents the app adds:\n  members with the `AGENT` role, recorded under their own names. A token carries the scopes the admin approved, and every `/api/v1` operation that takes one\n  says so. `GET /api/oauth/userinfo` answers who a token acts for. `GET /api/v1/members` and `GET /api/v1/connections` (`members:read`), and\n  `DELETE /api/v1/connections/{id}` (`connections:write`, API keys only): every token of the app ends and its agents are switched off.\n- **People only.** New code `PEOPLE_ONLY` (403), nothing written: accepting or countering an offer below the floor and a campaign audience of pasted\n  addresses (any caller), emailing a contact one to one (an agent or an API key), and, from an agent, setting the floor, approving a quarter (Sell or Buy),\n  confirming that a closing's money arrived, activating or sending a campaign, switching an automation back on, and notification preferences. With it the\n  command codes `BELOW_FLOOR`, `POLICY_DENIED`, `CONFLICT`, `NOT_FOUND` and `INVALID`.\n- **Offers** (tag Offers; `offers:read` / `offers:write`): the offers on your vehicles and the offers you made, never naming the buyer, and accepting,\n  declining, countering and withdrawing through the app's own offer commands.\n- **Dry runs and idempotency keys.** The writes on offers, listings, the CRM, tasks, Mission Control, closings, marketing and automations take\n  `?dryRun=true` (every rule checked, nothing written) and `Idempotency-Key` (up to 200 characters: a retry gets the first answer with\n  `Idempotent-Replayed: true`; `422 IDEMPOTENCY_KEY_REUSED` for another body, `409 IDEMPOTENCY_IN_PROGRESS` while the first runs).\n- **The CRM** (tag CRM; `crm:read` / `crm:write`): contacts, businesses and deals of your own book, their notes, interactions and tags, the deal\n  stages and moving a deal, and `POST /api/v1/contacts/{id}/outreach`, a person's email to one contact.\n- **Tasks and Mission Control** (`tasks:read` / `tasks:write`, `mission-control:read`): the tasks people, automations and agents share, and the `TASK.*`\n  events; the board of what needs a person now, and delegating an item to one of your agents.\n- **Insights** (`insights:read`): Cedar's and Sequoia's insights on your vehicles and buy targets, each with its basis, and `include=insights` on a single read.\n- **Notifications** (`notifications:read` / `notifications:write`): what Cypress told your members, `NOTIFICATION.CREATED`, and your people's preferences.\n- **Closings** (`closing:read` / `closing:write`): the closings of the cars you sold and bought, step by step, with whose turn it is and its deadline;\n  reminding, asking for a document, re-sending a signing link and the step actions; `CLOSING.STEP.DUE`, `CLOSING.STEP.OVERDUE`, `CLOSING.DOCUMENT.REQUESTED`.\n- **Marketing** (`marketing:read` / `marketing:write`): campaigns, their sends, the people they reached and the cars they brought people to, and your\n  message templates; `CAMPAIGN.SENT`, `CAMPAIGN.PAUSED`, `CAMPAIGN.INTEREST`, `CONTACT.UNSUBSCRIBED`.\n- **Automations** (tag Automation): `GET /api/v1/automation/manifest`, the records, events, lookups and acts an automation can use; your organization's own\n  automations (`automations:read` / `automations:write`, on an organization with the Automations product, else `403 AUTOMATIONS_NOT_ENABLED`): build,\n  validate, dry-run and submit them for Cypress to publish, switch them, and read every run step by step; `AUTOMATION.*` events.\n- **Planning for apps and agents.** Sell planning gains the strategy (`/api/v1/planning/strategy`), goals (`/goals`; a goal keeps its kind,\n  `409 KIND_CHANGE`), the quarter (`GET /quarters/{periodKey}`, `current` accepted) and its approval (`POST .../approve` with the quarter's digest:\n  `PREVIEW_STALE`, `PERIOD_CLOSED`), and Sequoia's schedule (`/schedule/proposals`, `/schedule/apply`). Buy planning gains Sequoia's draft of a quarter\n  (`POST /api/v1/buy-planning/drafts`, which writes nothing) and keeping it (`/drafts/apply`). Approving is a person's.\n- **Your own ids, and bulk.** `externalIds` (`[{ source, id }]`) on vehicles, listings, contacts, businesses, deals and tasks, `?externalId=source:id`\n  on their lists, and `409 EXTERNAL_ID_TAKEN` naming the record that holds one. `POST /api/v1/contacts/bulk`, `/businesses/bulk`, `/tasks/bulk` and\n  `/listings/bulk` upsert up to 100, each matched by your own ids.\n- **Links and the event log.** `links.app` on every record and every CYPRESS-dialect event: where it opens in the app (`/go/…`), never to be built by hand.\n  The CYPRESS envelope gains `cursor`: `GET /api/v1/events` reads the 30-day log after a cursor, `POST /api/v1/webhooks/subscriptions/{id}/replay`\n  delivers it again, and a subscription may list `entityIds` to hear about some records only. `updatedAfter` on the lists of vehicles, listings,\n  offers, closings and tasks (as on contacts, businesses and deals): what changed at or after a time, the newest change first, to backfill a sync.\n- **Sandboxes reset themselves.** `POST /api/v1/sandbox/reset` puts a sandbox's data back as it was made, under the same key, from any\n  credential acting in it (an agent's too); a sandbox now holds cars on the market with offers waiting and one in a closing.\n- **Opt-in events**, on the same terms as `PLAN.*`: delivered only to a CYPRESS-dialect subscription that lists them, each needing its read scope:\n  `TASK.*`, `NOTIFICATION.CREATED`, the closing deadline and request events, the marketing events, `AUTOMATION.*`, the CRM events\n  (`CONTACT.CREATED`, `CONTACT.UPDATED`, `BUSINESS.*`, `DEAL.*`, `OUTREACH.*`, needing crm:read), `INSIGHT.CREATED` (insights:read), and on the\n  Planning terms `PLAN.GOAL.SET`, `PLAN.QUARTER.APPROVED`, `BUY.TARGET.CREATED`, `BUY.TARGET.DUE` and `BUY.QUARTER.APPROVED`.\n- **Every action heard.** The writes the older events did not tell, from every door (the app, the API, MCP, a CSV, an automation, Stripe), each with\n  `change` (what happened) and `source`: `ORGANIZATION.UPDATED`, `MEMBER.UPDATED`, `BANKING.UPDATED` (never a number), `BILLING.UPDATED`,\n  `CLOSING.UPDATED` (to both sides, each with its `side`; the commission step is the seller's alone), `MARKETPLACE.OFFER.UPDATED` (the buyer's side of\n  an offer it made: its own amount, the seller's counter, never the floor), `CONTACT.DELETED`, `BUSINESS.DELETED`, `DEAL.DELETED`, `CRM.IMPORT.COMPLETED`,\n  `VEHICLES.IMPORT.COMPLETED`, `CAMPAIGN.ACTIVATED`, `PROMOTION.UPDATED`, `INSIGHT.ANSWERED`, and on the Planning terms `PLAN.VEHICLE.UPDATED`,\n  `PLAN.STRATEGY.UPDATED`, `BUY.TARGET.UPDATED` and `BUY.QUARTER.SET`. Opt-in, each on the read scope of its area.\n- **Every action of the app.** The app's screens' actions are operations under `/api/v1` (tag per area), each with its Operate MCP tool, `?dryRun=true`\n  and `Idempotency-Key`; an organization's CM token (`cyp_cm_`) reaches Cypress's staff actions under `/api/v1/staff/`.\n- **MCP servers and a sandbox.** Cypress Operate and Cypress Intelligence (`/api/mcp/operate`, `/api/mcp/intelligence`) with a key or a Connect Cypress\n  token, and the public Cypress Manual (`/api/mcp/manual`, no credential). A sandbox organization to build against, with a key holding every scope.\n\n**Changed for existing keys (1.5.0):**\n- A listing price change answers `409 CONFLICT` while the vehicle is Under Offer, Offer Accepted, in Due Diligence, Ready to Deliver or Sold,\n  `403 BELOW_FLOOR` when the buy-now would sit below the floor, and `422 INVALID` for a buy-now on a vehicle with no floor: on\n  `PATCH /api/v1/listings/{id}`, on each item of `PATCH /api/v1/listings/bulk` (the item carries the code and the batch goes on), and on\n  `POST /api/compatible/v1/offerings/id/{offeringId}`. All of these used to be written. A refused change writes nothing.\n- New fields: `links` on records and CYPRESS-dialect events, `cursor` on the CYPRESS envelope, `externalIds` on vehicles and listings. No field was\n  removed or renamed, and the MANHEIM envelope is unchanged.\n- A subscription without an event filter receives none of the new event families, and an existing key holds none of the new scopes until an admin\n  adds them.\n- **The offer bands a price push sets** follow the app's one rule: auto-decline below `floorPrice`, auto-accept at or above `buyNowPrice`, your review\n  between (they were auto-accept at the floor and auto-decline below `startBidPrice`). `startBidPrice` is kept and returned and sets no band. A vehicle\n  priced by a pricing rule keeps its rule. Other bands are a pricing rule's or an automation's to set.\n- **A pause and a cancel are the app's.** `PATCH /api/v1/listings/{id}` status `PAUSED` (and the MANHEIM pause) now also withdraws the open offers\n  and tells their buyers. `DELETE /api/v1/listings/{id}` (and `DELETE /api/compatible/v1/offerings/id/{offeringId}`) on a car on the market is staged\n  for Cypress's review (`202`, `VEHICLES.DISPOSITION.STAGED`, the listing `PAUSED` meanwhile) instead of archiving it at once (`204`); the approval\n  closes the listing `CANCELLED`, a rejection resumes it. While it waits, resuming the listing answers `409`. A sold-elsewhere report\n  (`POST /api/v1/vehicles/{id}/disposition`) on a live car pauses its listing the same way while Cypress reviews it. (Since 1.8.0 only a car with an\n  open offer or a sale in progress is reviewed; see Changes in 1.8.0.)\n- **Every write takes `?dryRun=true` and an `Idempotency-Key`**, the older ones too (vehicles, their costs, odometer readings, ownership,\n  sold-elsewhere and departures; Planning's blockers, moves, parking, tracks, demotions and window hand-offs; Buy planning's targets, purchases\n  and quarters; notification preferences). Additive: a call without either behaves as before.\n\n**Changes in 1.4.0 — Buy planning over the API, the closed quarter in the contract, and `OFFERS.ACCEPTED` for every accepted offer.** Everything is additive except what is listed last\n(\"Changed for existing keys\"):\n- **Buy planning over the API.** A dealer's purchasing system keeps the buy plan in step. New scopes `buy-planning:read` / `buy-planning:write`\n  (write implies read) on an organization with Buy planning switched on — a switch of its own, separate from Planning. Fourteen operations under\n  `/api/v1/buy-planning`, all on the key's own organization: the quarter (`GET` and `PUT /quarters/{periodKey}`, with its goal, budget and mandate, its\n  approval and progress, and the `digest` that `POST .../approve` binds to), the targets (list by quarter and status, add, read, edit, remove), a target's\n  live matches (the listing's public facts only, never a seller or the staff deal fit) and hiding one, and the purchases (list, record one made\n  elsewhere, move to a target, remove a recorded one). The app and the API call the same rules: a target needed in a quarter that is over, and the goal of\n  one, answer `409 QUARTER_CLOSED`; a purchase never does; an approval keeps its own codes (`PERIOD_CLOSED`, `NOTHING_TO_APPROVE`, `PLAN_CHANGED`).\n- **Buy planning webhooks:** `BUY.TARGET.MATCHED` (a live listing fits an open target for the first time: the target and the match, as the matches read returns it),\n  `BUY.TARGET.FILLED` (a target has nothing left to buy: the target, with its bought and in-closing counts) and `BUY.TARGET.ENDED` (a target's quarter closed with\n  units short: the target, its shortfall and its bought count). Opt-in, like `PLAN.*`: delivered only to a CYPRESS-dialect subscription that lists the event (never\n  an unfiltered one, never a MANHEIM one) and only while the organization has Buy planning. Subscribing to one needs `buy-planning:read` (`403 SCOPE_MISSING` /\n  `403 BUY_PLANNING_NOT_ENABLED`; a MANHEIM subscription listing one is `422`). Each is delivered to an endpoint once, however many times its cause is noticed.\n  Envelope resource `buy`; the body is the moment the event happened. They carry the dealer's own target and a listing's public facts, never a seller.\n- New code `BUY_PLANNING_NOT_ENABLED` (403) when the organization has no Buy planning, and `HAS_PURCHASES` and `FROM_CLOSING` (409) on targets and purchases.\n- `GET /api/v1/organization` gains `products.buyPlanning { enabled, requestedAt }` and the capabilities `buy-planning.read` / `buy-planning.write`.\n- The scope labels in the app read by side (\"Sell planning (read)\", \"Buy planning (read and write)\"). The scope strings are unchanged, so existing keys are too.\n- **The closed quarter, in the contract.** A quarter whose last day has passed is history, and the plan of a closed quarter no longer changes, in the app or here:\n  - New code `QUARTER_CLOSED` (409): on `POST /api/v1/planning/moves`, `/moves/track`, `/moves/park` and on `/windows/{windowId}/cohort-preview`\n    and `/cohort-confirm`. A window counts in the quarter that holds its 8th day. The request is refused whole, nothing is written, and it is\n    not retryable. Its body gains `details: { vehicleIds, quarter }` — the vehicles of the request the closed quarter blocks, and their quarter\n    when it is one — so a sync job can send the rest again. `error` and `code` are as for every refusal.\n  - New fields on every window of `GET /api/v1/planning/plan` and on the `window` of every plan vehicle: `quarter` (e.g. `2026-Q4`) and `closed`\n    (true once that quarter is over — the test the server refuses by). A window of a closed quarter that has not been swept yet still reads\n    `PLANNED` or `ACTIVE`: read `closed`, not `state`.\n  - Documented: what `to: BENCH` and `to: OPERATION` skip (`skipped` reasons), what `planVersion` is, and that Planning here is Sell planning (Buy planning has its own API, above).\n  - Still possible on a closed quarter, and not a change: a vehicle already handed to Sell keeps a track that can change (only planned vehicles are frozen),\n    a vehicle that slipped can leave its window, an unsold vehicle can be moved into a window of a quarter in progress, and blockers and demotions are not refused.\n- **`OFFERS.ACCEPTED` for every accepted offer.** The webhook follows the app's \"Offer accepted\": it is sent when the seller (or Cypress for them) accepts an offer,\n  when a pricing rule accepts one as it arrives or a buyer uses Buy Now (`autoProcessed: true`), and, new in 1.4.0, when a buyer accepts the seller's counter and when an\n  approved price change accepts an offer that now qualifies. An accepted offer is announced to an endpoint once. No field was added to any event.\n\n**Changed for existing keys (1.4.0):**\n- A move into a window of a quarter that is over, a move to `OPERATION` or a park of a vehicle scheduled in one, a track change of a planned vehicle in one,\n  and the hand-off of one of its windows now answer `409 QUARTER_CLOSED`; before, they were accepted, except that a move into a window, or a hand-off,\n  answered `409 WINDOW_CLOSED` when the window itself had closed. `cohort-preview` of such a window answers the same, instead of a digest the confirm would\n  refuse. `WINDOW_CLOSED` is now answered only for a window that has closed in a quarter still in progress.\n- The stored plan advice `reasoning` and `plan.note` no longer carry a plan version number (\"Sequoia plan v12: …\" now reads \"Sequoia's live plan: …\").\n  They are free text for people; the shape is unchanged.\n- A subscription that receives `OFFERS.ACCEPTED` (one that lists it, or lists no events) now also receives it for a counter the buyer accepts and for an offer an\n  approved price change accepts; before, those accepted the offer and sent nothing.\n- The scope labels in the app read by side; the scope strings, and what each scope grants, are unchanged.\n\n**Changes in 1.3.0 — Planning over the API.** The planning capabilities sit behind the `planning:read` /\n`planning:write` scopes on an organization with Planning. What an existing key or subscription can notice is\nlisted last (\"Changed for existing keys\"):\n- Push the fleet in: `POST /api/v1/vehicles` (and `/bulk`, `?mode=upsert`) accepts `lifeStage: OPERATION`\n  (in service) or `PLANNING` (benched on the plan as a candidate) with an optional `ownership` block.\n  No valuation is bought; the daily sweep values new planning stock.\n- Keep it current: `PATCH /api/v1/vehicles/{id}` on planning stock, and per vehicle `ownership`,\n  `odometer-readings`, `cost-events` and `departure` (staged for Cypress review).\n- Read the plan: `GET /api/v1/planning/plan`, `/planning/vehicles`, `/planning/vehicles/{id}`.\n- Drive the plan: moves to a window / the bench / operation, tracks, parking, blockers, the cohort\n  hand-off to Sell (preview → confirm) and demotions. Every write is one plan version; a lost race\n  answers `409 PLAN_BUSY` with `Retry-After`.\n- `PLAN.*` webhooks (Cypress dialect, delivered only to subscriptions that list them).\n- New codes: `IN_SELL`, `RETIRED`, `PLAN_BUSY`, `ODOMETER_ROLLBACK`, `NO_PLAN`, and the plan's own `PREVIEW_STALE`,\n  `WINDOW_CLOSED`, `WINDOW_GONE`, `SELLING_BEGUN`, `RESOLVED`, `QUARTER_PASSED`.\n- Changed for existing keys: (1) a `PATCH /api/v1/vehicles/{id}` on planning stock from a key without\n  `planning:write`, at an organization with Planning, answers `403 SCOPE_MISSING` (1.2.0: `409 PLANNING_STOCK`).\n  (2) `GET`/`PUT /api/v1/vehicles/{id}/ownership` needs only `vehicles` for Sell stock — a default key can read\n  and replace its own Sell vehicles' purchase & financing. (3) `VEHICLES.*` events about planning stock reach\n  only a CYPRESS-dialect subscription that lists them (never an unfiltered or MANHEIM one); a cohort hand-off\n  sends a plain `VEHICLES.UPDATED` per vehicle to every matching subscription. (4) Corrected:\n  `POST /api/compatible/v1/units/bulk` refuses an item whose embedded `offering` names an ungranted channel\n  (`422 CHANNEL_NOT_GRANTED`, the unit is not created, the batch continues) — before, it created the unit\n  with no offering and reported `201`. The single `POST /units` already refused it.\n\n**Changes in 1.2.0** — backward compatible for keys with the default scopes, with two deliberate changes:\nplanning stock at an organization without Planning now answers `403 PLANNING_NOT_ENABLED` instead of\n`409 PLANNING_STOCK`, and a vehicles-only key pushing a vehicle/unit with an embedded `listing`/`offering`\nnow answers `403 SCOPE_MISSING` for the `listings` scope instead of creating it. Every other existing\nrequest, response and message is unchanged:\n- `GET /api/v1/organization` — what this organization and key may do: products, channel grants,\n  billing standing, delegation, and one entry per capability, refused with a reason when it is not\n  allowed. Answers any valid key, whatever the organization's status.\n- Refusals gain codes `ORG_NOT_ACTIVE`, `PLANNING_NOT_ENABLED`, `SCOPE_MISSING`, `CHANNEL_NOT_GRANTED`,\n  alongside `PLANNING_STOCK` and `LIFE_STAGE_READ_ONLY`.\n- Keys can hold scopes `planning:read` / `planning:write` (write implies read), chosen at mint and\n  editable later; existing keys keep exactly the scopes they have.\n- `?lifeStage=` on `GET /api/v1/vehicles` reads planning stock (`OPERATION`, `PLANNING`) for a\n  `planning:read` key on an organization with Planning.\n- Planning stock of an organization **without** Planning now answers `403 PLANNING_NOT_ENABLED`\n  instead of `409 PLANNING_STOCK` (a deliberate change, above).\n- An embedded `listing`/`offering` on a vehicle/unit push (single or bulk) now needs the `listings`\n  scope; without it, the push (or that bulk item) answers `403 SCOPE_MISSING` and creates nothing\n  (a deliberate change, above).\n\n**Changes in 1.1.0** (backward compatible for vehicles you push and sell):\n- Every vehicle carries `lifeStage` (`OPERATION`, `PLANNING`, `REMARKETING`, `POST_SALE`, `RETIRED`), on reads and in webhook bodies.\n- The API works on Sell stock: vehicles a fleet keeps in Operation or Planning are hidden from lists and reads (404),\n  and every Sell action on them answers `409` with `code: PLANNING_STOCK`.\n- Refusals carry a stable `code` where one applies (`PLANNING_STOCK`, `LIFE_STAGE_READ_ONLY`); switch on it, not on `error`.\n- A sale recorded off-platform now emits `CLOSING.COMPLETED` (context `offPlatform: true`) instead of `CLOSING.PROCESS.COMPLETED`.\n\nErrors, statuses and codes: https://app.getcypress.ai/docs/developers/errors"},"servers":[{"url":"https://staging.app.getcypress.ai","description":"Staging (integration testing)"},{"url":"https://app.getcypress.ai","description":"Production"}],"security":[{"apiKey":[]},{"bearer":[]}],"tags":[{"name":"Cypress API v1","description":"Canonical surface — vehicles, listings, dispositions"},{"name":"Planning","description":"Sell planning over the API (since 1.3.0) — push the fleet in, keep it current, read and drive the plan. Buy planning has its own tag, below. `planning:read` / `planning:write` on an organization with Planning; the per-vehicle routes need `vehicles` too. Since 1.5.0 also the strategy, the quarter's goals, the quarter and its approval (people only), and Sequoia's schedule; an app's or an agent's token works where a key does."},{"name":"Buy planning","description":"Buy planning over the API (since 1.4.0) — a dealer's purchasing system keeps its buy plan in step: the quarter and its approval, targets, their live matches, and purchases. `buy-planning:read` / `buy-planning:write` on an organization with Buy planning (a switch of its own). Your own organization's data only; a match carries a listing's public facts, never a seller or a limit. Its events (BUY.TARGET.MATCHED, FILLED and ENDED) are webhooks: see Webhooks & deliveries. Since 1.5.0 also Sequoia's draft of a quarter and keeping it."},{"name":"Webhooks & deliveries","description":"Event subscriptions and the delivery log"},{"name":"Members & connected apps","description":"Your organization's members, people and agents, and the apps connected through Connect Cypress. Read with `members:read`; disconnect an app with `connections:write` (API keys only)."},{"name":"CRM","description":"Your organization's own CRM book (since 1.5.0): contacts, businesses and deals, the notes and interactions on them, tags, and emailing a contact (a person's verb). Read with `crm:read` (or `crm:write`), by an API key or a Connect Cypress token. Write with `crm:write` through the app's own rules, with `?dryRun=true` and an `Idempotency-Key`. Never another organization's book (another book's record answers 404 like an unknown one). A record the platform matched to a Cypress account or organization is served without that link: another organization's membership is never your data. Owners are named and marked PERSON or AGENT, never emailed."},{"name":"Tasks","description":"Your organization's tasks (since 1.5.0): the work items people, automations and agents share, on contacts, companies, deals, vehicles, sell goals, windows and lots, and buy targets. Read with `tasks:read`; create, change, complete, reassign and remove with `tasks:write`. The same rules as the app: a task belongs to something of your organization (another organization's record answers 404 like an unknown one), and is given only to an active member, agents included (422 INVALID otherwise). An agent's task is its own (`source` AGENT); an app acting for a person makes the person's; an API key has no person behind it, so its task reads as an automation's and is unassigned unless it names someone. Every write takes `?dryRun=true` (the changes it would make, nothing written) and an `Idempotency-Key`. Tasks Cypress keeps for itself are never listed. Their events (TASK.*) are webhooks: see Webhooks & deliveries."},{"name":"Insights","description":"Cedar's and Sequoia's insights (since 1.5.0): sell or hold, pricing guidance and the campaign brief on your own vehicles, the price guide on your buy targets, and Sequoia's items on either, each with its basis, its confidence and the guardrail that applied. Read with `insights:read` (never a default scope). A model answer is cached for six hours, keyed on what it read; a credential gets 30 insight requests a minute. Privacy: an insight that reads a floor goes only to the vehicle's owner; anyone else gets the Marketplace's listing insight on a car for sale, written from the asking price and public values; a price guide needs sales from at least two seller companies and five sales."},{"name":"Marketing","description":"Marketing (since 1.5.0): your campaigns (your own, and those carrying your promotions), their sends, the people they reached and the cars they brought people to, and your message templates. Read with `marketing:read`; create, edit, activate, pause, send now and delete with `marketing:write` (neither a default). People are counted the way the Marketing screen counts them: REACHED is a distinct address mail was actually handed to the provider for, and test sends never count. An audience is described by its source and your own slice of your own book; an audience Cypress set over the platform's businesses reads `platform`, with no organization ids. No recipient identity is returned."},{"name":"Closings","description":"Closings (since 1.5.0): the closings of the cars you sold (side SELLER) and bought (side BUYER), each step with who carries its deadline, whose turn it is, the deadline and whether it is late, the documents with their signatures, and the requirements. Read with `closing:read`; remind, ask for a document, re-send a signing link and mark your own steps with `closing:write` (neither is a default). Each side sees its own signing links only; the buyer never sees the commission step; no payment, bank, invoice or counterparty detail is returned."},{"name":"Notifications","description":"Notifications (since 1.5.0): what Cypress told your members, people and agents alike, as events with a recipient. Nothing new is added to Cypress's notification catalog: these are the notifications your members already get. Read the last 30 days with `notifications:read`, and subscribe to NOTIFICATION.CREATED for the whole organization or for chosen people. A notification is in the recipient's organization only. A person's preferences are read with `notifications:read` and set with `notifications:write`."},{"name":"Mission Control","description":"Your organization's Mission Control (since 1.5.0): what needs a person now, from every system that owns some of it (offers, closings, onboarding, valuations, billing, campaigns, the CRM), in triage order, as the app's board shows it. Read with `mission-control:read`. An item about one record, or one that is already a task, can be delegated to one of your organization's agents with `tasks:write` as well: the agent gets a task, with the same rules and TASK.* events as any task."},{"name":"Offers","description":"Offers on your vehicles (side SELLER) and the offers you made (side BUYER). Read with `offers:read`; accept, decline, counter and withdraw with `offers:write`. The same rules as the app; accepting or countering below the floor is for a person at the seller (403 PEOPLE_ONLY). Every decision takes `?dryRun=true` and an `Idempotency-Key`. No buyer identity is returned."},{"name":"Automation","description":"Cypress's automation manifest, for a product that runs automations on Cypress (Grove, through Connect Cypress): the records, events and lookups, and the acts your credential's scopes allow, each with the node that runs it. Any credential reads it; acts are filtered by scope. Since 1.5.0, your own automations: build, validate, dry-run and submit them, switch them, and read their runs step by step. Read with `automations:read`; build with `automations:write` (neither a default), on an organization whose Automations product Cypress has switched on (else AUTOMATIONS_NOT_ENABLED). Cypress approves: nothing you write runs until a Cypress manager publishes it (AUTOMATION.PUBLISHED) or sends it back with a note (AUTOMATION.SENT_BACK). You see your own automations only, never Cypress's. An organization's automation may contain what its allow-list holds (a node outside it is refused with its reason) and acts only on your own records, as your organization's account admin would: never what that person could not do in the app. An agent drafts, tries, submits and switches automations off; switching one back on is a person's (PEOPLE_ONLY). At most 50 switched on and 200 in all; your automations start at most 500 runs an hour together."},{"name":"Manheim-compatible v1","description":"Manheim dialect — units, offerings, subscribers"},{"name":"Vehicles: the app's actions","description":"Since 1.5.0: everything the vehicle screens do (Fleet, the vehicle panel, Seller Hub) as one call each, through the screens' own code and rules, as the caller: labels, the status steps from draft to delivery, launch, pause, resume and delist, offer rules, pricing rules, valuations, pictures and videos, history reports, share links, visibility and the storefront. A change reaches webhooks as VEHICLES.UPDATED whichever door made it (`changedFields` says what, `source` where from). The same actions are Cypress Operate's MCP tools."},{"name":"Planning: the app's actions"},{"name":"Buy planning: the app's actions"},{"name":"CRM: the app's actions"},{"name":"Marketing: the app's actions"},{"name":"Promotions: the app's actions"},{"name":"Offers: the app's actions"},{"name":"Marketplace: the app's actions"},{"name":"Closings: the app's actions"},{"name":"Closings: Cypress staff"},{"name":"Document templates: the app's actions"},{"name":"Storefront and share links: the app's actions"},{"name":"Organization and settings: the app's actions"},{"name":"Members: the app's actions"},{"name":"Billing: the app's actions"},{"name":"Analytics: the app's actions"},{"name":"Mission Control: the app's actions"},{"name":"Cypress staff: organizations"},{"name":"Cypress staff: review queues"},{"name":"Cypress staff: labels, pricing rules and channels"},{"name":"Cypress staff: the Automation Hub"},{"name":"Cypress staff: platform activity"},{"name":"Agent quality","description":"Since 1.9.0: how an agent of a first-party app (Grove's Cedar) performs, and the audit of its flagged answers. The app sends its benchmark runs and the answers it flagged with `agent-quality:write` on its own token (first-party apps only); Cypress staff read the runs and give each flagged answer a verdict (a CM token); the app reads its organization's verdicts back and learns from them."},{"name":"Huddle","description":"Since 1.9.0: your organization's conversations, the same rooms people see in Cypress (Huddle) and in Grove: the huddle, channels and their threads, a person's room with Cedar, deal lanes, and the Inbox. Every call is made as the person or agent the credential acts for and sees what they would see (`huddle:read` to read, `huddle:write` to post, react, join and open channels); an API key never reaches conversations. A CM token reads the organization in Cypress-Organization, or every room the manager is in with `view=mine`."}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Org-scoped API key, shown once at issuance. Send as `x-api-key` or `Authorization: Bearer`. `cyp_live_…` acts on a live organization, `cyp_test_…` on a sandbox (since 1.5.0, with a checksum: `cyp_(live|test)_<32>_<6>`); a key used on the other kind answers 403 KEY_ENVIRONMENT."},"bearer":{"type":"http","scheme":"bearer","description":"Org-scoped API key, shown once at issuance. Send as `x-api-key` or `Authorization: Bearer`. `cyp_live_…` acts on a live organization, `cyp_test_…` on a sandbox (since 1.5.0, with a checksum: `cyp_(live|test)_<32>_<6>`); a key used on the other kind answers 403 KEY_ENVIRONMENT."}},"schemas":{"AppLinks":{"type":"object","description":"Where a record opens in the app (since 1.5.0). `app` is a /go/<type>/<id> link on the app's host: it checks the access of whoever follows it and opens the right page for them (Seller Hub for a seller, Buyer Hub for a buyer), so it keeps working when pages move. Never build these yourself.","properties":{"app":{"type":"string","format":"uri"}},"required":["app"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object","description":"On 422: the full validation result — fieldErrors (per field) and formErrors (whole payload). On 409 QUARTER_CLOSED (since 1.4.0): { vehicleIds, quarter } — the vehicles of the request that the closed quarter blocks, and their quarter (e.g. \"2026-Q3\") when they all sit in one."},"code":{"type":"string","enum":["PLANNING_STOCK","LIFE_STAGE_READ_ONLY","ORG_NOT_ACTIVE","PLANNING_NOT_ENABLED","SCOPE_MISSING","CHANNEL_NOT_GRANTED","IN_SELL","RETIRED","PLAN_BUSY","ODOMETER_ROLLBACK","NO_PLAN","PREVIEW_STALE","WINDOW_CLOSED","WINDOW_GONE","SELLING_BEGUN","RESOLVED","QUARTER_PASSED","QUARTER_CLOSED","BUY_PLANNING_NOT_ENABLED","PERIOD_CLOSED","NOTHING_TO_APPROVE","PLAN_CHANGED","HAS_PURCHASES","FROM_CLOSING","EXTERNAL_ID_TAKEN","PEOPLE_ONLY","BELOW_FLOOR","POLICY_DENIED","CONFLICT","NOT_FOUND","INVALID","IDEMPOTENCY_KEY_REUSED","IDEMPOTENCY_IN_PROGRESS","AUTOMATIONS_NOT_ENABLED","KIND_CHANGE","KEY_ENVIRONMENT","MASS_REMOVAL","ACCOUNT_RULES"],"description":"Stable refusal code, present on refusals that have one. Switch on this, not on `error`. PLANNING_STOCK (409): the vehicle is in Operation or Planning and the request needs Sell stock. LIFE_STAGE_READ_ONLY (409): a write sent a lifeStage the vehicle cannot move to by that write (across the Planning/Sell line, or a planning move sent as data). ORG_NOT_ACTIVE (403): the organization is not active. PLANNING_NOT_ENABLED (403): the capability needs Planning, and the organization does not have it. SCOPE_MISSING (403): the key lacks the scope this capability needs. CHANNEL_NOT_GRANTED (422): the organization has no grant for this sales channel. Since 1.3.0 — IN_SELL (409): a planning-stock-only route (odometer readings, departure) hit a vehicle in Sell. RETIRED (409): a planning-stock-only route hit a vehicle that has already left the fleet (archived). PLAN_BUSY (409, with Retry-After): another write took the plan version first; nothing was written, retry. ODOMETER_ROLLBACK (409): the reading runs the odometer series backwards; send force: true for a replaced or corrected odometer. NO_PLAN: a planning push wrote the vehicle but the organization has no live plan to bench it in (on the push result, not a refusal). PREVIEW_STALE (409): a cohort confirm whose preview expired or whose cohort changed. WINDOW_CLOSED (409): the sale window has closed, in a quarter still in progress. WINDOW_GONE (404): the window is not in the latest plan version — an older id is followed by lineage, so this means the window itself is gone (re-read the plan). SELLING_BEGUN (409): a demotion of a vehicle already listed or beyond. RESOLVED (409): the blocker is already resolved. QUARTER_PASSED (422): parking until a quarter that has already started. Since 1.4.0 — QUARTER_CLOSED (409): the request would change a quarter that is over (its last day has passed, UTC): a move into one of its windows, a move to OPERATION or a park of a vehicle scheduled in one, a track change of a planned vehicle that sits in one, or the preview or hand-off of one of its windows. A window counts in the quarter that holds its 8th day. The request is refused whole and nothing was written; details.vehicleIds names the vehicles it blocks, so the rest can be sent again. Not retryable: pick a window of a quarter in progress (GET /api/v1/planning/plan, closed: false). It is asked before WINDOW_CLOSED. Not to be confused with QUARTER_PASSED, which is parking until a quarter that has already started. On the Buy planning API, QUARTER_CLOSED is the same refusal for a target needed in a quarter that is over (adding one, editing, pausing, reopening, closing or removing it, or an edit that moves one into such a quarter) and for the goal, budget and mandate of one; it carries no details, and a purchase is never refused with it. Also since 1.4.0, on the Buy planning API — BUY_PLANNING_NOT_ENABLED (403): the capability needs Buy planning, and the organization does not have it (a switch of its own, separate from Planning). The approval of a quarter (POST /api/v1/buy-planning/quarters/{periodKey}/approve) answers 409 with its own codes: PERIOD_CLOSED (the quarter is over), NOTHING_TO_APPROVE (no goal, no budget and no target) and PLAN_CHANGED (the digest is not the live plan's — read the quarter again, then approve again). HAS_PURCHASES (409): a target with purchases cannot be removed — close it, its history stays. FROM_CLOSING (409): a purchase that came from a Cypress closing follows that closing and cannot be removed here. Since 1.5.0 — EXTERNAL_ID_TAKEN (409): an external id (source and id) already names another record of the same kind in your organization (a vehicle, listing, contact, business, deal or task); `taken` names it; nothing was written. The commands answer the command codes: PEOPLE_ONLY (403): only a person may do this, and nothing is written. From any caller: accepting or countering an offer below the floor, and a campaign audience of pasted addresses (email-list). From an agent or an API key: emailing a contact one to one. From an agent: setting the floor, approving a quarter (below), confirming that a closing's money arrived, activating or sending a campaign, switching an automation back on, and notification preferences. BELOW_FLOOR (403): the request would put a price or a decision below the floor. POLICY_DENIED (403): a rule or a delegation switch refuses this caller. CONFLICT (409): the record is not in a state that allows it (an offer no longer open; a price under a live offer or sale). NOT_FOUND (404): no such record for this key. INVALID (422): the request is not valid for this command. IDEMPOTENCY_KEY_REUSED (422): the Idempotency-Key was already used with a different request. IDEMPOTENCY_IN_PROGRESS (409): the first request with this key is still running; retry shortly. Since 1.5.0 — AUTOMATIONS_NOT_ENABLED (403): the capability needs the Automations product, which Cypress switches on per organization; asked before the scopes. Also since 1.5.0, on Planning: PEOPLE_ONLY (403) is also the answer to an agent's token that approves a quarter (POST /api/v1/planning/quarters/{periodKey}/approve, POST /api/v1/buy-planning/quarters/{periodKey}/approve, or POST /api/v1/buy-planning/drafts/apply with approve: true): an agent prepares a plan, a person approves it; nothing is written. PREVIEW_STALE (409) is also the answer to a schedule apply whose proposal expired or whose plan changed, and to a Sell quarter approval whose digest is not the live plan's (read the quarter again). PERIOD_CLOSED (409) is also the Sell quarter approval's own code for a quarter that is over. KIND_CHANGE (409): a goal keeps its kind (units, cash, shape, renewal); add a new goal instead. Also since 1.5.0 — KEY_ENVIRONMENT (403): a key used outside its environment, a test key (cyp_test_) on a live organization or a live key (cyp_live_) on a sandbox, or a sandbox's own act (POST /api/v1/sandbox/reset) asked of a live organization; nothing is read or written. PEOPLE_ONLY (403) is also the answer to an agent's token that sets a floor on a new listing (POST /api/v1/listings) or cancels a listing (DELETE /api/v1/listings/{id}): an agent pauses the listing instead; `vehicleId` names the car. Since 1.8.0 — MASS_REMOVAL (409): a full-inventory push (POST /api/v1/vehicles/bulk?removeMissing=true) would take off more than a fifth of the organization's active vehicles (and more than five), as a truncated feed would; nothing is written. `activeInventory` and `missing` say how many. Send the whole inventory (inventoryVins on the last page), or allowMassRemoval=true when the removal is meant. Since 1.9.0 — ACCOUNT_RULES (403): the account's rules refuse it (account on GET /api/v1/organization): a feature that is off for this organization (account.features: team, apps, apiKeys, campaigns, pricingRules), one of its caps used (account.limits and account.used: valuations and cars listed in total, team seats, campaign emails this month), or an individual's email not confirmed yet. Cypress sets the rules per kind of account and per organization."}},"required":["error"]},"Location":{"type":"object","properties":{"city":{"type":"string"},"state":{"type":"string","maxLength":2},"zip":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"}}},"Image":{"type":"object","properties":{"href":{"type":"string","format":"uri","description":"Publicly fetchable URL"},"type":{"type":"string","description":"PRIMARY_IMAGE, EXTERIOR, DAMAGE, …"}},"required":["href"]},"VehicleWrite":{"type":"object","description":"Vehicle payload (modern surface). Unknown fields are preserved and echoed back on reads.","properties":{"vin":{"type":"string","minLength":17,"maxLength":17},"modelYear":{"type":"integer","minimum":1900,"maximum":2100},"make":{"type":"string"},"model":{"type":"string"},"trim":{"type":"string"},"bodyClass":{"type":"string"},"driveType":{"type":"string"},"transmission":{"type":"string"},"fuelType":{"type":"string"},"exteriorColor":{"type":"string"},"interiorColor":{"type":"string"},"mileage":{"type":"integer","minimum":0,"description":"Miles"},"condition":{"oneOf":[{"type":"number","minimum":1,"maximum":5,"description":"Preferred: industry 1.0–5.0 grade — stored with precision, tier derived"},{"type":"string","enum":["EXCELLENT","GOOD","FAIR","POOR"],"description":"Fallback tier"}]},"stockNumber":{"type":"string"},"externalIds":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for this vehicle, one per source. Set or replaced per source, never removed by omission. An id another vehicle holds is refused with 409 EXTERNAL_ID_TAKEN."},"location":{"allOf":[{"$ref":"#/components/schemas/Location"}],"description":"Since 1.8.0: a `name` that matches one of your saved locations (Settings › Locations, any case) fills the address, city, state and ZIP you leave out, as the Import does. A name that matches none is a warning; the vehicle keeps what you sent."},"images":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/Image"}},"floorPrice":{"type":["number","null"],"exclusiveMinimum":0,"maximum":5000000,"description":"Since 1.8.0. The seller's floor (the lowest acceptable sale price), as the CSV import's price column: set at once on a vehicle not yet on the market; on one on the market or in a sale, a request Cypress reviews. The push answers `floorPrice`: SET, UNCHANGED or STAGED. Null or absent leaves the floor as it is. Planning stock takes none (a warning). If the push also sends `listing.floorPrice`, the two must agree."},"inspectionReportUrl":{"type":["string","null"],"format":"uri","maxLength":2000,"description":"Since 1.8.0. A third-party inspection report's link (a Manheim condition report, `https://inspectionreport.manheim.com/?disclosureid=…`). Cypress reads it after the push: the grade becomes the vehicle's `condition` (unless a finalized Cypress inspection set it), and its damages and photos are added. A later replace (PUT, `mode=upsert`) without `condition` keeps that grade; one with `condition` sets it; `VEHICLES.UPDATED` (`changedFields: [\"inspectionReport\"]`) says when it landed. The same link again changes nothing, so a daily push can carry it every time (a failed one is read again at most once a day); a new link replaces the report. A link no provider reads is kept as a link only. Null or absent leaves the vehicle's report as it is. The push answers `inspectionReport`: QUEUED, UNCHANGED or LINK_ONLY."},"listing":{"allOf":[{"$ref":"#/components/schemas/ListingWrite"}],"description":"Optional — create the listing in the same push."},"lifeStage":{"type":"string","enum":["OPERATION","PLANNING","REMARKETING"],"description":"Optional, on create. Omitted or REMARKETING: Sell stock, as before. OPERATION (in service) or PLANNING (benched as a candidate on the plan) creates planning stock — needs the planning:write scope and Planning switched on (403 SCOPE_MISSING / PLANNING_NOT_ENABLED). POST_SALE and RETIRED are never a create-time stage (422). An upsert by VIN never moves a vehicle across the Planning/Sell line (409 LIFE_STAGE_READ_ONLY). On PATCH/PUT any stage may be echoed back; a different one answers 409 LIFE_STAGE_READ_ONLY (planning moves go through POST /api/v1/planning/moves)."},"ownership":{"allOf":[{"$ref":"#/components/schemas/Ownership"}],"description":"Optional purchase & financing, applied only to an OPERATION/PLANNING push (validated before anything is created: an invalid block answers 422 and creates nothing). On a Sell push the key is carried as-is, as in 1.2.0 — set a Sell vehicle's ownership with PUT /api/v1/vehicles/{id}/ownership."}},"required":["vin","modelYear","make","model"]},"ExternalId":{"type":"object","required":["source","id"],"properties":{"source":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$","description":"Your name for the system, e.g. dms or erp"},"id":{"type":"string","maxLength":128}}},"VehicleRead":{"type":"object","properties":{"id":{"type":"string"},"vin":{"type":"string"},"listing":{"type":["object","null"],"description":"Since 1.5.0. The open listing (REQUESTED, ACTIVE or PAUSED): the one to pause, resume or cancel. Null when the vehicle has none.","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["REQUESTED","ACTIVE","PAUSED"]},"href":{"type":"string"}}},"externalIds":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"}},"status":{"type":"string","description":"DRAFT … LISTED … SOLD (platform lifecycle)"},"modelYear":{"type":"integer"},"make":{"type":"string"},"model":{"type":"string"},"trim":{"type":"string"},"mileage":{"type":"integer"},"condition":{"type":"string","enum":["EXCELLENT","GOOD","FAIR","POOR"]},"conditionScore":{"type":"number","description":"1.0–5.0 grade when supplied numerically"},"location":{"$ref":"#/components/schemas/Location"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"pricing":{"type":"object","properties":{"buyNowPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"floorPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"startBidPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"}}},"lifeStage":{"type":"string","enum":["OPERATION","PLANNING","REMARKETING","POST_SALE","RETIRED"],"description":"Where the vehicle is in its life. Sell stock (REMARKETING, POST_SALE, RETIRED) is visible to any `vehicles` key, by default. OPERATION and PLANNING (planning stock) are visible only to a `planning:read` key on an organization with Planning switched on — invisible otherwise. A Sell write to planning stock (PUT, a re-push, prices, listings, deletion, sold-elsewhere) answers 409 PLANNING_STOCK when the organization has Planning (it is waiting for its plan's hand-off), or 403 PLANNING_NOT_ENABLED when it does not (it is frozen). Since 1.3.0 a `planning:write` key keeps planning stock current with PATCH and the Planning routes.","readOnly":true},"listedAt":{"type":"string","format":"date-time"},"createdOn":{"type":"string","format":"date-time"},"updatedOn":{"type":"string","format":"date-time"},"inspectionReport":{"type":["object","null"],"description":"Since 1.8.0. The vehicle's third-party inspection report, null when it has none. GET /api/v1/vehicles/{id}/history-report has each damage.","properties":{"url":{"type":"string"},"provider":{"type":"string","enum":["MANHEIM","UNKNOWN"],"description":"UNKNOWN: a link no provider reads, kept as a link only"},"status":{"type":"string","enum":["PENDING","FETCHING","IMPORTING_PHOTOS","COMPLETE","FAILED","LINK_ONLY"],"description":"IMPORTING_PHOTOS: the grade and damages are in, the photos are on their way"},"grade":{"type":["number","null"],"description":"The report's 1.0–5.0 grade, once read"},"gradeLabel":{"type":["string","null"]},"damages":{"type":"integer","description":"Damage items read"},"photos":{"type":"integer","description":"Photos added from the report"},"updatedOn":{"type":"string","format":"date-time"}}},"engagement":{"type":["string","null"],"enum":["HOT","WARM","COLD",null],"description":"Since 1.9.0. How buyers are taking to the car while it is on the market (LISTED, UNDER_OFFER, ON_HOLD): COLD with no views, saves or offers in 14 days; HOT when the last 7 days beat the 7 before by 20% or more (or a new listing's first week has any); else WARM. The Seller Hub's Market column. Null off the market."},"listedDays":{"type":["integer","null"],"description":"Since 1.9.0. Whole days on the market from the listing date, stopped at the sale; null when it was never listed"},"views14d":{"type":"integer","description":"Since 1.9.0. Buyer views in the last 14 days"},"saves14d":{"type":"integer","description":"Since 1.9.0. Saves in the last 14 days"},"offers14d":{"type":"integer","description":"Since 1.9.0. Offers in the last 14 days"},"arvisInspection":{"type":["object","null"],"description":"Since 1.9.0. The vehicle's latest ARVIS inspection (Cypress's own), null when it has none. `url` opens it in ARVIS through the app's sign-on: for a person signed in to Cypress whose role may see ARVIS.","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["PENDING","PREPROCESSING","ANALYZING","REVIEW","FINALIZED","FAILED"]},"grade":{"type":["string","null"],"enum":["EXCELLENT","GOOD","FAIR","POOR",null],"description":"The technician's grade, once given"},"score":{"type":["integer","null"],"description":"The grade as the app shows it: EXCELLENT 5, GOOD 4, FAIR 3, POOR 2"},"inspectedAt":{"type":["string","null"],"format":"date-time","description":"When it was reviewed (else completed)"},"damages":{"type":["integer","null"]},"repairCost":{"type":["number","null"],"description":"Estimated repair cost, in dollars"},"url":{"type":["string","null"]}}},"keyCount":{"type":["integer","null"],"description":"Since 1.9.0. How many keys come with the car, as the seller says; 0 for none, null when not said"},"damageNote":{"type":["string","null"],"description":"Since 1.9.0. The seller's own words on the car's damage"},"conditionCheck":{"type":["object","null"],"description":"Since 1.10.0. A person looked at the car and said its condition (edit_vehicle `conditionChecked`): when, and who. Null when nobody has; an inspection is `arvisInspection` / `inspectionReport`","properties":{"checkedOn":{"type":"string","format":"date-time"},"by":{"type":["string","null"]}}},"damages":{"type":"array","description":"Since 1.9.0. The damage lines the seller declared (POST /api/v1/vehicles/{id}/damages), oldest first. GET /api/v1/vehicles/{id}/damages has each picture's link.","items":{"type":"object","properties":{"id":{"type":"string"},"area":{"type":"string"},"description":{"type":"string"},"severity":{"type":"string","enum":["MINOR","MODERATE","SEVERE","CRITICAL"]},"photoId":{"type":["string","null"],"description":"The picture, one of the car's photos"},"createdOn":{"type":"string","format":"date-time"}}}},"links":{"$ref":"#/components/schemas/AppLinks"}}},"ListingWrite":{"type":"object","properties":{"floorPrice":{"type":"number","exclusiveMinimum":0,"description":"Minimum acceptable sale price"},"buyNowPrice":{"type":"number","exclusiveMinimum":0,"description":"Listing price buyers see; required to go live"},"startBidPrice":{"type":"number","exclusiveMinimum":0,"description":"Kept on the vehicle and returned as pushed. Since 1.5.0 it sets no offer band: offers below floorPrice are auto-declined, offers at or above buyNowPrice auto-accept"},"channels":{"type":"array","minItems":1,"items":{"type":"string","enum":["MARKETPLACE","STOREFRONT","DIRECT_LINK"]},"default":["MARKETPLACE"]},"listingMode":{"type":"string","enum":["REVIEW","IMMEDIATE"],"default":"REVIEW","description":"REVIEW = draft-first; IMMEDIATE = launch in-request when eligible"}}},"ListingRead":{"type":"object","properties":{"externalIds":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for it, one per source (since 1.5.0)"},"id":{"type":"string"},"href":{"type":"string"},"vehicleId":{"type":"string"},"vehicleHref":{"type":"string"},"vin":{"type":"string"},"status":{"type":"string","enum":["REQUESTED","ACTIVE","PAUSED","SOLD","NOT_SOLD","CANCELLED"]},"listingMode":{"type":"string"},"channels":{"type":"array","items":{"type":"string"}},"directLink":{"type":"string","description":"Share-link path when DIRECT_LINK is enabled"},"floorPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"buyNowPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"startBidPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"activatedAt":{"type":"string","format":"date-time"},"closedAt":{"type":"string","format":"date-time"},"links":{"$ref":"#/components/schemas/AppLinks"}}},"ListingPatch":{"type":"object","description":"At least one field. status PAUSED pauses a live listing; ACTIVE resumes.","properties":{"floorPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"buyNowPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"startBidPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"channels":{"type":"array","items":{"type":"string","enum":["MARKETPLACE","STOREFRONT","DIRECT_LINK"]}},"status":{"type":"string","enum":["PAUSED","ACTIVE"]}}},"ListingUpdate":{"type":"object","description":"PATCH /api/v1/listings/{id}: at least one field. status PAUSED pauses a live listing; ACTIVE resumes. `externalIds` alone changes only your ids (since 1.5.0).","properties":{"externalIds":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for the record, one per source. Set or replaced per source, never removed by omission. One another record of the same kind in your organization holds answers 409 EXTERNAL_ID_TAKEN, naming it; nothing is written. Since 1.5.0 (vehicles since 1.5.0 too)."},"floorPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"buyNowPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"startBidPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"channels":{"type":"array","items":{"type":"string","enum":["MARKETPLACE","STOREFRONT","DIRECT_LINK"]}},"status":{"type":"string","enum":["PAUSED","ACTIVE"]}}},"BulkUpsertResult":{"type":"object","description":"One result per row, in order; one bad row never fails the batch (since 1.5.0).","properties":{"dryRun":{"type":"boolean","description":"Present on a dry run: nothing was written"},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"The row's place in `items`"},"status":{"type":"integer","description":"201 created; 200 changed (a row whose ids name a record), or opened (a new row the book already had); 4xx refused"},"id":{"type":"string"},"code":{"type":"string","description":"On a refusal: INVALID, NOT_FOUND, CONFLICT, POLICY_DENIED, EXTERNAL_ID_TAKEN (the ids name two different records)…"},"errors":{"type":"array","items":{"type":"string"}},"changes":{"type":"object","description":"On a dry run: what the row would write"},"warnings":{"type":"array","items":{"type":"string"},"description":"Ids another push claimed at the same moment: the record is written, those ids are not"}}}},"created":{"type":"integer"},"updated":{"type":"integer"},"refused":{"type":"integer"}}},"DispositionRequest":{"type":"object","properties":{"type":{"type":"string","enum":["SOLD_ELSEWHERE"]},"salePrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"saleDate":{"type":"string"},"reason":{"type":"string"}},"required":["type"]},"StagedResult":{"type":"object","description":"The request was staged for Cypress review (the vehicle has an open offer or a sale in progress); the decision arrives as a DISPOSITION.RESOLVED event.","properties":{"staged":{"type":"boolean"},"requestId":{"type":"string"},"alreadyPending":{"type":"boolean"},"message":{"type":"string"},"reviewReason":{"type":"string","enum":["OPEN_OFFERS","SALE_IN_PROGRESS"],"description":"Since 1.8.0: why Cypress reviews it"}}},"ArchivedResult":{"type":"object","description":"Since 1.8.0: archived at once (planning stock, or no open offer and no sale in progress); VEHICLES.DISPOSITION.RESOLVED (`automatic: true`) tells your endpoint.","properties":{"staged":{"type":"boolean","enum":[false]},"archived":{"type":"boolean","enum":[true]},"requestId":{"type":"string","description":"The request, kept as approved for the audit trail"},"status":{"type":"string","enum":["ARCHIVED"]},"message":{"type":"string"}}},"SubscriptionWrite":{"type":"object","properties":{"callback":{"type":"string","format":"uri","description":"HTTPS endpoint Cypress POSTs envelopes to"},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Sent verbatim on every delivery (e.g. your x-api-key). Values are secret after save."},"emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Alerted when deliveries keep failing"},"eventTypes":{"type":"array","items":{"type":"string"},"description":"Filter; empty = all events except Planning, Buy planning and Task ones. Opt-in — list each one you want, on a CYPRESS-dialect subscription: PLAN.* (the key needs planning:read; a MANHEIM subscription listing one is refused with 422), since 1.3.0 VEHICLES.* about planning stock (a vehicle in OPERATION or PLANNING), since 1.4.0 BUY.TARGET.MATCHED / BUY.TARGET.FILLED / BUY.TARGET.ENDED (the key needs buy-planning:read, the organization needs Buy planning, and a MANHEIM subscription listing one is refused with 422), and since 1.5.0 TASK.CREATED / TASK.ASSIGNED / TASK.DUE / TASK.COMPLETED / TASK.CANCELLED (the key needs tasks:read; a MANHEIM subscription listing one is refused with 422) and NOTIFICATION.CREATED (the key needs notifications:read; refused on MANHEIM the same way) and CLOSING.STEP.DUE / CLOSING.STEP.OVERDUE / CLOSING.DOCUMENT.REQUESTED (the key needs closing:read; refused on MANHEIM the same way) and CAMPAIGN.SENT / CAMPAIGN.PAUSED / CAMPAIGN.INTEREST / CONTACT.UNSUBSCRIBED (the key needs marketing:read; refused on MANHEIM the same way) and AUTOMATION.RUN.COMPLETED / AUTOMATION.RUN.FAILED / AUTOMATION.PUBLISHED / AUTOMATION.SENT_BACK (the key needs automations:read, which needs the Automations product; refused on MANHEIM the same way) and the CRM events CONTACT.CREATED / CONTACT.UPDATED / BUSINESS.CREATED / BUSINESS.UPDATED / DEAL.CREATED / DEAL.UPDATED / DEAL.STAGE_CHANGED / OUTREACH.LOGGED / OUTREACH.REPLIED (the key needs crm:read) and INSIGHT.CREATED (the key needs insights:read), each refused on MANHEIM the same way; PLAN.GOAL.SET and PLAN.QUARTER.APPROVED follow the PLAN.* terms, BUY.TARGET.CREATED, BUY.TARGET.DUE and BUY.QUARTER.APPROVED the BUY.* ones; and since 1.5.0 every action heard: ORGANIZATION.UPDATED (organization:read), MEMBER.UPDATED (members:read), BANKING.UPDATED (banking:read), BILLING.UPDATED (billing:read), MARKETPLACE.OFFER.UPDATED (marketplace:read), CLOSING.UPDATED (closing:read), CONTACT.DELETED / BUSINESS.DELETED / DEAL.DELETED / CRM.IMPORT.COMPLETED (crm:read), VEHICLES.IMPORT.COMPLETED (vehicles; since 1.9.0 also VEHICLES.IMPORT.STAGED and VEHICLES.IMPORT.APPLIED, a staged import held and run), CAMPAIGN.ACTIVATED / PROMOTION.UPDATED (marketing:read), INSIGHT.ANSWERED (insights:read), each refused on MANHEIM the same way, and PLAN.VEHICLE.UPDATED, PLAN.STRATEGY.UPDATED, BUY.TARGET.UPDATED and BUY.QUARTER.SET on the PLAN.* and BUY.* terms; since 1.9.0 MARKETPLACE.SHARE.RECEIVED (marketplace:read), refused on MANHEIM the same way"},"dialect":{"type":"string","enum":["CYPRESS","MANHEIM"],"description":"Envelope vocabulary"},"inactive":{"type":"boolean"},"entityIds":{"type":"array","items":{"type":"string"},"maxItems":200,"description":"Record filter: only events about these records (the event's resource id, or a related vehicle, listing, offer or closing id; for a TASK.* event, since 1.5.0, also the contact, business, deal, sell goal or buy target the task is about). Empty = all.; for NOTIFICATION.CREATED, the recipient's user id, so a subscription follows chosen people"}},"required":["callback"]},"SubscriptionRead":{"type":"object","properties":{"id":{"type":"string"},"href":{"type":"string"},"callback":{"type":"string"},"headers":{"type":"object","description":"Names only — values are masked"},"emails":{"type":"array","items":{"type":"string"}},"eventTypes":{"type":"array","items":{"type":"string"}},"entityIds":{"type":"array","items":{"type":"string"}},"dialect":{"type":"string"},"inactive":{"type":"boolean"}}},"OfferRead":{"type":"object","properties":{"id":{"type":"string"},"href":{"type":"string"},"side":{"type":"string","enum":["SELLER","BUYER"],"description":"SELLER: an offer on your vehicle. BUYER: an offer you made."},"vehicleId":{"type":"string"},"vehicleHref":{"type":["string","null"]},"vin":{"type":"string"},"amount":{"type":"number"},"status":{"type":"string","enum":["NEW","REVIEWED","COUNTERED","ACCEPTED","REJECTED","EXPIRED","WITHDRAWN","CANCELLED"]},"counterAmount":{"type":["number","null"]},"counterExpiresAt":{"type":["string","null"],"format":"date-time"},"createdOn":{"type":"string","format":"date-time"},"updatedOn":{"type":"string","format":"date-time"},"links":{"$ref":"#/components/schemas/AppLinks"}}},"Contact":{"type":"object","description":"A person in your organization's CRM book (since 1.5.0).","properties":{"externalIds":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for it, one per source (since 1.5.0)"},"id":{"type":"string"},"href":{"type":"string"},"email":{"type":"string","description":"The primary address, which identifies the contact in your book"},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"phone":{"type":["string","null"],"description":"The primary number"},"phones":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string"},"label":{"type":["string","null"]},"isPrimary":{"type":"boolean"}}},"description":"Every number, the primary first"},"altEmails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"label":{"type":["string","null"]}}}},"companyName":{"type":["string","null"]},"businessId":{"type":["string","null"],"description":"The business of your book this person works at"},"kind":{"type":"string","enum":["ORG_PROSPECT","CONSUMER","ON_PLATFORM"]},"lifecycle":{"type":"string","enum":["PROSPECT","REACHED","ENGAGED","ON_PLATFORM","ACTIVE","DORMANT"]},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":["string","null"],"description":"Where the contact came from: manual, import, offer, an integration…"},"owner":{"oneOf":[{"$ref":"#/components/schemas/TaskPerson"},{"type":"null"}]},"zip":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"address":{"type":["string","null"]},"lastActivityAt":{"type":["string","null"],"format":"date-time"},"lastContactedAt":{"type":["string","null"],"format":"date-time"},"createdOn":{"type":"string","format":"date-time"},"updatedOn":{"type":"string","format":"date-time"},"links":{"$ref":"#/components/schemas/AppLinks"}},"required":["id","email","kind","lifecycle","tags","phones","altEmails","createdOn","updatedOn"]},"Business":{"type":"object","description":"A company in your organization's CRM book (since 1.5.0).","properties":{"externalIds":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for it, one per source (since 1.5.0)"},"id":{"type":"string"},"href":{"type":"string"},"name":{"type":"string"},"domain":{"type":["string","null"]},"phone":{"type":["string","null"]},"website":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":["string","null"]},"owner":{"oneOf":[{"$ref":"#/components/schemas/TaskPerson"},{"type":"null"}]},"fleetSize":{"type":["string","null"]},"brands":{"type":"array","items":{"type":"string"}},"timezone":{"type":["string","null"]},"contactCount":{"type":"integer","description":"The contacts of your book who work there"},"locations":{"type":"array","items":{"type":"object","properties":{"label":{"type":["string","null"]},"zip":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]},"address":{"type":["string","null"]},"isPrimary":{"type":"boolean"}}},"description":"The primary first"},"hours":{"type":"array","items":{"type":"object","properties":{"dayOfWeek":{"type":"integer","minimum":0,"maximum":6,"description":"0 is Sunday"},"opensAt":{"type":["string","null"]},"closesAt":{"type":["string","null"]},"closed":{"type":"boolean"}}},"description":"HH:MM in `timezone`"},"lastActivityAt":{"type":["string","null"],"format":"date-time"},"createdOn":{"type":"string","format":"date-time"},"updatedOn":{"type":"string","format":"date-time"},"links":{"$ref":"#/components/schemas/AppLinks"}},"required":["id","name","tags","brands","contactCount","createdOn","updatedOn"]},"ContactWrite":{"type":"object","description":"A contact to create, or to open when its address is already in your book (blanks are filled, nothing curated is overwritten). Never matched to a Cypress account.","required":["email"],"additionalProperties":false,"properties":{"externalIds":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for the record, one per source. Set or replaced per source, never removed by omission. One another record of the same kind in your organization holds answers 409 EXTERNAL_ID_TAKEN, naming it; nothing is written. Since 1.5.0 (vehicles since 1.5.0 too)."},"email":{"type":"string","maxLength":320},"firstName":{"type":["string","null"],"maxLength":120},"lastName":{"type":["string","null"],"maxLength":120},"phone":{"type":["string","null"],"maxLength":60},"companyName":{"type":["string","null"],"maxLength":200},"zip":{"type":["string","null"],"pattern":"^\\d{5}$"},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"address":{"type":["string","null"]},"kind":{"type":"string","enum":["ORG_PROSPECT","CONSUMER"],"description":"ON_PLATFORM is stamped when the person joins Cypress, never set"},"source":{"type":["string","null"],"maxLength":120,"description":"Default `api`"},"ownerUserId":{"type":["string","null"],"description":"An active member (a person or an agent). Left out: the caller when it is a person or an agent; an API key's contact is nobody's."},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20},"businessId":{"type":["string","null"],"description":"A business of your book this person works at"}}},"ContactPatch":{"type":"object","description":"The fields to change; at least one. `phones` and `altEmails` replace the whole list. A change is recorded in the contact's history.","minProperties":1,"additionalProperties":false,"properties":{"externalIds":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for the record, one per source. Set or replaced per source, never removed by omission. One another record of the same kind in your organization holds answers 409 EXTERNAL_ID_TAKEN, naming it; nothing is written. Since 1.5.0 (vehicles since 1.5.0 too)."},"email":{"type":"string","format":"email","description":"The primary address; one another contact of your book uses is 409 CONFLICT with `conflictContactId`"},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"phone":{"type":["string","null"]},"companyName":{"type":["string","null"]},"zip":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"address":{"type":["string","null"]},"kind":{"type":"string","enum":["ORG_PROSPECT","CONSUMER"]},"lifecycle":{"type":"string","enum":["PROSPECT","REACHED","ENGAGED","ACTIVE","DORMANT"],"description":"ON_PLATFORM is stamped when the person joins Cypress, never set"},"ownerUserId":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"},"maxItems":20},"phones":{"type":"array","maxItems":10,"items":{"type":"object","required":["number"],"properties":{"number":{"type":"string"},"label":{"type":["string","null"]},"isPrimary":{"type":"boolean"}}},"description":"Exactly one ends up primary"},"altEmails":{"type":"array","maxItems":10,"items":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"label":{"type":["string","null"]}}},"description":"Alternates; the primary and repeats are dropped"},"businessId":{"type":["string","null"],"description":"Move to a business of your book, or out of one with null"}}},"BusinessWrite":{"type":"object","description":"A business to create, or to open when your book already has one by that name (legal suffixes ignored: \"Acme Motors Inc.\" is \"Acme Motors\") or that domain.","required":["name"],"additionalProperties":false,"properties":{"externalIds":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for the record, one per source. Set or replaced per source, never removed by omission. One another record of the same kind in your organization holds answers 409 EXTERNAL_ID_TAKEN, naming it; nothing is written. Since 1.5.0 (vehicles since 1.5.0 too)."},"name":{"type":"string","minLength":1,"maxLength":200},"domain":{"type":["string","null"]},"phone":{"type":["string","null"]},"website":{"type":["string","null"]},"ownerUserId":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20}}},"BusinessPatch":{"type":"object","description":"The fields to change; at least one. `hours` and `locations` replace the whole list; empty rows are dropped.","minProperties":1,"additionalProperties":false,"properties":{"externalIds":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for the record, one per source. Set or replaced per source, never removed by omission. One another record of the same kind in your organization holds answers 409 EXTERNAL_ID_TAKEN, naming it; nothing is written. Since 1.5.0 (vehicles since 1.5.0 too)."},"name":{"type":"string","minLength":1,"maxLength":200},"domain":{"type":["string","null"]},"phone":{"type":["string","null"]},"website":{"type":["string","null"]},"ownerUserId":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"},"maxItems":20},"fleetSize":{"type":["string","null"],"enum":["UNDER_10","FROM_10_TO_50","FROM_50_TO_200","FROM_200_TO_1000","OVER_1000",null]},"brands":{"type":"array","items":{"type":"string"},"maxItems":40},"timezone":{"type":["string","null"],"description":"IANA zone, e.g. America/New_York"},"hours":{"type":"array","maxItems":7,"items":{"type":"object","required":["dayOfWeek"],"properties":{"dayOfWeek":{"type":"integer","minimum":0,"maximum":6},"opensAt":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$"},"closesAt":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$"},"closed":{"type":"boolean"}}}},"locations":{"type":"array","maxItems":50,"items":{"type":"object","properties":{"label":{"type":["string","null"]},"zip":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"address":{"type":["string","null"]},"isPrimary":{"type":"boolean"}}},"description":"Exactly one ends up primary"}}},"Deal":{"type":"object","description":"A deal of your organization's CRM book (since 1.5.0): a sale (VEHICLE_SALE) or a company being brought onto Cypress (ONBOARDING).","properties":{"externalIds":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for it, one per source (since 1.5.0)"},"id":{"type":"string"},"href":{"type":"string"},"title":{"type":"string"},"kind":{"type":"string","enum":["VEHICLE_SALE","ONBOARDING"]},"stage":{"type":"string","enum":["PROSPECTING","INTERESTED","QUALIFIED","OFFER_IN","NEGOTIATING","CLOSING","WON","LOST"]},"stageEnteredAt":{"type":"string","format":"date-time"},"businessId":{"type":["string","null"]},"contactId":{"type":["string","null"]},"owner":{"oneOf":[{"$ref":"#/components/schemas/TaskPerson"},{"type":"null"}]},"expectedAmount":{"type":["number","null"]},"vehicles":{"type":"array","items":{"type":"object","properties":{"vehicleId":{"type":"string"},"askAmount":{"type":["number","null"]},"outcome":{"type":"string","enum":["PENDING","SOLD","DROPPED"]},"addedAt":{"type":"string","format":"date-time"}}},"description":"Your own vehicles on the deal"},"promotionId":{"type":["string","null"]},"campaignId":{"type":["string","null"]},"originChannelId":{"type":["string","null"]},"lostReason":{"type":["string","null"],"enum":["PRICE","FINANCING_FELL_THROUGH","BOUGHT_ELSEWHERE","TIMING","VEHICLE_CONDITION","NO_RESPONSE","BUYER_CHANGED_MIND","SELLER_CHANGED_MIND","LOGISTICS","OTHER",null]},"lostNote":{"type":["string","null"]},"closedAt":{"type":["string","null"],"format":"date-time"},"lastActivityAt":{"type":["string","null"],"format":"date-time"},"createdOn":{"type":"string","format":"date-time"},"updatedOn":{"type":"string","format":"date-time"},"links":{"$ref":"#/components/schemas/AppLinks"}},"required":["id","title","kind","stage","vehicles","createdOn","updatedOn"]},"DealWrite":{"type":"object","description":"A deal to open, at PROSPECTING. It is with a business or a contact of your book (or both); an ONBOARDING deal needs a business and carries no vehicles.","required":["title"],"additionalProperties":false,"properties":{"externalIds":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for the record, one per source. Set or replaced per source, never removed by omission. One another record of the same kind in your organization holds answers 409 EXTERNAL_ID_TAKEN, naming it; nothing is written. Since 1.5.0 (vehicles since 1.5.0 too)."},"title":{"type":"string","minLength":1,"maxLength":200},"kind":{"type":"string","enum":["VEHICLE_SALE","ONBOARDING"],"default":"VEHICLE_SALE"},"businessId":{"type":["string","null"]},"contactId":{"type":["string","null"]},"vehicleIds":{"type":"array","items":{"type":"string"},"maxItems":200,"description":"Your own vehicles; another seller's is 403 POLICY_DENIED naming them in `refused`"},"expectedAmount":{"type":["number","null"],"minimum":0},"ownerUserId":{"type":["string","null"],"description":"An active member. Left out: the caller when it is a person or an agent; an API key's deal is nobody's."},"promotionId":{"type":["string","null"]},"campaignId":{"type":["string","null"]},"originChannelId":{"type":["string","null"]}}},"DealPatch":{"type":"object","description":"The fields to change; at least one. Never the stage: that moves through POST /api/v1/deals/{id}/stage.","minProperties":1,"additionalProperties":false,"properties":{"externalIds":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for the record, one per source. Set or replaced per source, never removed by omission. One another record of the same kind in your organization holds answers 409 EXTERNAL_ID_TAKEN, naming it; nothing is written. Since 1.5.0 (vehicles since 1.5.0 too)."},"title":{"type":"string","minLength":1,"maxLength":200},"kind":{"type":"string","enum":["VEHICLE_SALE","ONBOARDING"],"description":"409 CONFLICT when the deal cannot survive it (vehicles on an onboarding deal, a stage the other pipeline lacks)"},"businessId":{"type":["string","null"]},"contactId":{"type":["string","null"]},"expectedAmount":{"type":["number","null"],"minimum":0},"ownerUserId":{"type":["string","null"]},"promotionId":{"type":["string","null"]},"campaignId":{"type":["string","null"]},"originChannelId":{"type":["string","null"]}}},"DealStageMove":{"type":"object","required":["stage"],"additionalProperties":false,"properties":{"stage":{"type":"string","enum":["PROSPECTING","INTERESTED","QUALIFIED","OFFER_IN","NEGOTIATING","CLOSING","WON","LOST"]},"lostReason":{"type":"string","enum":["PRICE","FINANCING_FELL_THROUGH","BOUGHT_ELSEWHERE","TIMING","VEHICLE_CONDITION","NO_RESPONSE","BUYER_CHANGED_MIND","SELLER_CHANGED_MIND","LOGISTICS","OTHER"],"description":"Required for LOST"},"lostNote":{"type":"string","maxLength":2000}}},"DealPipelines":{"type":"object","description":"Each kind's stages in board order, their names, and which may be set by hand (`manual`); the others are set by the offer and closing flow.","properties":{"VEHICLE_SALE":{"type":"array","items":{"type":"object","properties":{"stage":{"type":"string"},"label":{"type":"string"},"manual":{"type":"boolean"}}}},"ONBOARDING":{"type":"array","items":{"type":"object","properties":{"stage":{"type":"string"},"label":{"type":"string"},"manual":{"type":"boolean"}}}},"lostReasons":{"type":"array","items":{"type":"string"}}}},"Note":{"type":"object","description":"A note on a contact, business or deal of your book (since 1.5.0). Its author's name is the one it was written under; an integration key's note has no author id.","properties":{"id":{"type":"string"},"href":{"type":"string"},"body":{"type":"string"},"pinned":{"type":"boolean"},"author":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":"string"},"kind":{"type":"string","enum":["PERSON","AGENT","INTEGRATION"]}}},"createdOn":{"type":"string","format":"date-time"},"updatedOn":{"type":"string","format":"date-time"},"links":{"$ref":"#/components/schemas/AppLinks"}},"required":["id","body","pinned","author","createdOn","updatedOn"]},"NoteWrite":{"type":"object","required":["body"],"additionalProperties":false,"properties":{"body":{"type":"string","minLength":1,"maxLength":10000},"pinned":{"type":"boolean","default":false}}},"NotePatch":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"body":{"type":"string","minLength":1,"maxLength":10000},"pinned":{"type":"boolean"}}},"Interaction":{"type":"object","description":"What happened with a contact, business or deal of your book (since 1.5.0). LOGGED by a person, an agent or an integration; DELIVERED is a campaign email that went out, never changed.","properties":{"id":{"type":"string"},"href":{"type":"string"},"kind":{"type":"string","enum":["LOGGED","DELIVERED"]},"channel":{"type":"string","enum":["EMAIL","PHONE","SMS","WHATSAPP","MEETING","OTHER"]},"direction":{"type":"string","enum":["OUTBOUND","INBOUND"]},"subject":{"type":"string"},"body":{"type":"string"},"outcome":{"type":["string","null"],"enum":["CONNECTED","NO_ANSWER","LEFT_MESSAGE","BOUNCED","RESCHEDULED",null]},"status":{"type":"string","enum":["QUEUED","SENT","FAILED"]},"blockedReason":{"type":["string","null"]},"occurredAt":{"type":["string","null"],"format":"date-time"},"durationMinutes":{"type":["integer","null"]},"contactId":{"type":["string","null"]},"businessId":{"type":["string","null"]},"dealId":{"type":["string","null"]},"createdBy":{"oneOf":[{"$ref":"#/components/schemas/TaskPerson"},{"type":"null"}],"description":"Null for an integration's or a campaign's"},"createdOn":{"type":"string","format":"date-time"},"links":{"$ref":"#/components/schemas/AppLinks"}},"required":["id","kind","channel","direction","subject","status","createdOn"]},"InteractionWrite":{"type":"object","required":["channel","subject"],"additionalProperties":false,"properties":{"channel":{"type":"string","enum":["EMAIL","PHONE","SMS","WHATSAPP","MEETING","OTHER"]},"direction":{"type":"string","enum":["OUTBOUND","INBOUND"],"default":"OUTBOUND"},"subject":{"type":"string","minLength":1,"maxLength":300},"body":{"type":"string","maxLength":20000},"outcome":{"type":["string","null"],"enum":["CONNECTED","NO_ANSWER","LEFT_MESSAGE","BOUNCED","RESCHEDULED",null]},"occurredAt":{"type":"string","format":"date-time","description":"When it happened; default now"},"durationMinutes":{"type":["integer","null"],"minimum":0,"maximum":1440},"contactId":{"type":["string","null"],"description":"On a business: one of its people. On a deal: someone on it (default: the deal's contact)."},"dealId":{"type":["string","null"],"description":"On a contact: a deal of your book this person is on"},"followUp":{"type":"object","required":["title","dueDate"],"properties":{"title":{"type":"string","maxLength":200},"dueDate":{"type":"string","format":"date-time"}},"description":"The next step, created as a task in the same write (TASK.CREATED after it commits)"}}},"InteractionPatch":{"type":"object","minProperties":1,"additionalProperties":false,"properties":{"channel":{"type":"string","enum":["EMAIL","PHONE","SMS","WHATSAPP","MEETING","OTHER"]},"direction":{"type":"string","enum":["OUTBOUND","INBOUND"]},"subject":{"type":"string","minLength":1,"maxLength":300},"body":{"type":"string","maxLength":20000},"outcome":{"type":["string","null"],"enum":["CONNECTED","NO_ANSWER","LEFT_MESSAGE","BOUNCED","RESCHEDULED",null]},"occurredAt":{"type":"string","format":"date-time"},"durationMinutes":{"type":["integer","null"],"minimum":0,"maximum":1440}}},"TagEdit":{"type":"object","required":["ids"],"additionalProperties":false,"description":"Add and remove tags over a selection, never replace. At least one tag to add or remove; tags compare without case; a record keeps at most 20 (its own win).","properties":{"ids":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":1000},"addTags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20},"removeTags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20}}},"TagEditResult":{"type":"object","properties":{"updated":{"type":"integer"},"unchanged":{"type":"integer"},"refused":{"type":"integer"},"refusedIds":{"type":"array","items":{"type":"string"},"description":"Ids that are not of your book (or do not exist): never tagged, never silently dropped"},"dryRun":{"type":"boolean"},"wouldBe":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}},"description":"With ?dryRun=true: each changed record's tags as they would be"}}},"CrmDryRun":{"type":"object","description":"What a write would do, with nothing written: whether it would create or open, and the fields it would set.","properties":{"dryRun":{"type":"boolean","const":true},"created":{"type":"boolean"},"changes":{"type":"object","additionalProperties":true}},"required":["dryRun","created","changes"]},"TaskWrite":{"type":"object","description":"A new task. At least one of the links is required (since 1.9.0, a `conversation` counts); each record must be your organization's.","required":["title"],"additionalProperties":false,"properties":{"externalIds":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for the record, one per source. Set or replaced per source, never removed by omission. One another record of the same kind in your organization holds answers 409 EXTERNAL_ID_TAKEN, naming it; nothing is written. Since 1.5.0 (vehicles since 1.5.0 too)."},"title":{"type":"string","minLength":1,"maxLength":300},"notes":{"type":["string","null"],"maxLength":5000},"dueDate":{"type":["string","null"],"format":"date-time"},"channel":{"type":["string","null"],"enum":["EMAIL","PHONE","SMS","WHATSAPP","MEETING","OTHER",null]},"assigneeUserId":{"type":["string","null"],"description":"An active member (a person or an agent). Left out: the caller, when it is a person or an agent; an API key's task is unassigned."},"playKey":{"type":["string","null"],"maxLength":200,"description":"The play an agent's work belongs to"},"contactId":{"type":["string","null"]},"dealId":{"type":["string","null"]},"businessId":{"type":["string","null"]},"vehicleId":{"type":["string","null"]},"planningGoalId":{"type":["string","null"]},"saleWindowKey":{"type":["string","null"],"maxLength":200},"lotKey":{"type":["string","null"],"maxLength":200},"buyTargetId":{"type":["string","null"]},"plan":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"side":{"type":"string","enum":["SELL","BUY"]},"periodKey":{"type":"string","pattern":"^\\d{4}-Q[1-4]$"}},"required":["side","periodKey"]},{"type":"null"}],"description":"A quarter's plan as a whole: refused for Cypress's own book, which has no plan"},"conversation":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"roomId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"messageId":{"type":["string","null"],"pattern":"^[A-Za-z0-9_-]{1,64}$"}},"required":["roomId"]},{"type":"null"}],"description":"Since 1.9.0. The conversation the task was made from: a Huddle room and, optionally, the message in it (never a message without its room). A task with only this belongs to that conversation. The ids are Huddle's; Cypress keeps them as given."}}},"TaskPatch":{"type":"object","description":"The fields to change; at least one. `status` DONE records who finished it, and any other status clears that.","minProperties":1,"additionalProperties":false,"properties":{"externalIds":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for the record, one per source. Set or replaced per source, never removed by omission. One another record of the same kind in your organization holds answers 409 EXTERNAL_ID_TAKEN, naming it; nothing is written. Since 1.5.0 (vehicles since 1.5.0 too)."},"title":{"type":"string","minLength":1,"maxLength":300},"notes":{"type":["string","null"],"maxLength":5000},"dueDate":{"type":["string","null"],"format":"date-time"},"channel":{"type":["string","null"],"enum":["EMAIL","PHONE","SMS","WHATSAPP","MEETING","OTHER",null]},"status":{"type":"string","enum":["OPEN","DONE","CANCELLED"]},"assigneeUserId":{"type":["string","null"]},"businessId":{"type":["string","null"]},"conversation":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"roomId":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"messageId":{"type":["string","null"],"pattern":"^[A-Za-z0-9_-]{1,64}$"}},"required":["roomId"]},{"type":"null"}],"description":"Since 1.9.0. Link the task to the conversation it came from, or null to unlink it (refused, INVALID, when nothing else would hold the task)"}}},"WriteDryRun":{"type":"object","description":"A write with ?dryRun=true (since 1.5.0): every check met, nothing written, and what would change.","properties":{"dryRun":{"type":"boolean","const":true},"changes":{"type":["object","null"],"additionalProperties":true,"description":"What would change; null when nothing would (see note)"},"note":{"type":"string","description":"Why nothing would change: already recorded, or already waiting for Cypress's review"}},"required":["dryRun","changes"]},"PlanningDryRun":{"type":"object","description":"A planning write with ?dryRun=true: every check met, nothing written, and what would change.","properties":{"dryRun":{"type":"boolean","const":true},"changes":{"type":"object","additionalProperties":true}},"required":["dryRun","changes"]},"TaskDryRun":{"type":"object","description":"What a write would do, with nothing written: the fields it would set.","properties":{"dryRun":{"type":"boolean","const":true},"changes":{"type":"object","additionalProperties":true}},"required":["dryRun","changes"]},"TaskPerson":{"type":"object","description":"A member of your organization, named but never emailed (`tasks:read` is not `members:read`). `kind` AGENT marks an agent user.","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["PERSON","AGENT"]}},"required":["id","name","kind"]},"Task":{"type":"object","description":"A task of your organization (since 1.5.0): the work item people, automations and agents share. The body of every TASK.* envelope (resource `tasks`), read at delivery time.","properties":{"externalIds":{"type":"array","items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for it, one per source (since 1.5.0)"},"id":{"type":"string"},"title":{"type":"string"},"notes":{"type":["string","null"]},"status":{"type":"string","enum":["OPEN","DONE","CANCELLED"]},"dueDate":{"type":["string","null"],"format":"date-time"},"channel":{"type":["string","null"],"enum":["EMAIL","PHONE","SMS","WHATSAPP","MEETING","OTHER",null],"description":"How it is meant to be done"},"source":{"type":"string","enum":["PERSON","AUTOMATION","AGENT"],"description":"Who or what made it"},"playKey":{"type":["string","null"],"description":"The play an agent's task belongs to"},"assignee":{"oneOf":[{"$ref":"#/components/schemas/TaskPerson"},{"type":"null"}]},"createdBy":{"oneOf":[{"$ref":"#/components/schemas/TaskPerson"},{"type":"null"}],"description":"For an automation's task, the person who answers for the automation"},"completedBy":{"oneOf":[{"$ref":"#/components/schemas/TaskPerson"},{"type":"null"}]},"completedAt":{"type":["string","null"],"format":"date-time"},"links":{"type":"object","description":"What the task is about: at least one is set","properties":{"contactId":{"type":["string","null"]},"dealId":{"type":["string","null"]},"businessId":{"type":["string","null"]},"vehicleId":{"type":["string","null"]},"planningGoalId":{"type":["string","null"]},"saleWindowKey":{"type":["string","null"],"description":"A sale window's lineage, e.g. 2026W44-2026W45"},"lotKey":{"type":["string","null"]},"buyTargetId":{"type":["string","null"]},"plan":{"oneOf":[{"type":"object","properties":{"side":{"type":"string","enum":["SELL","BUY"]},"periodKey":{"type":"string","description":"e.g. 2026-Q4"}},"required":["side","periodKey"]},{"type":"null"}],"description":"A task about a quarter's plan as a whole (\"get Q4 approved\"): the plan's side and quarter"},"conversation":{"oneOf":[{"type":"object","properties":{"roomId":{"type":"string"},"messageId":{"type":["string","null"]}},"required":["roomId","messageId"]},{"type":"null"}],"description":"Since 1.9.0. The conversation the task was made from: its Huddle room and, when it came from one message, that message"},"app":{"type":"string","format":"uri","description":"Where the task opens in the app (since 1.5.0): a /go/ link that checks the follower's access"}}},"createdOn":{"type":"string","format":"date-time"},"updatedOn":{"type":"string","format":"date-time"}},"required":["id","title","status","source","links","createdOn","updatedOn"]},"WorkItem":{"type":"object","description":"One thing on your Mission Control board (since 1.5.0): work that needs a person now, from whichever system owns it. Drawn field by field from the board, without its free text (it can name a counterparty), the app's buttons or photos.","properties":{"id":{"type":"string","description":"Stable while the work is open, e.g. offer-<id>, closing-<id>, crm-task-<taskId>"},"source":{"type":"string","enum":["offers","listings","onboarding","valuations","closings","billing","campaigns","crm","platform"]},"kind":{"type":"string","description":"What sort of work, e.g. offer-decision, closing-overdue, follow-up"},"phase":{"type":"string","enum":["onboarding","pre-listing","sale","post-sale","relationship"]},"urgency":{"type":"string","enum":["decision","overdue","due-soon","attention","fyi"],"description":"Triage order, most urgent first"},"badge":{"type":["string","null"]},"title":{"type":"string"},"entity":{"oneOf":[{"type":"object","description":"The one record it is about","properties":{"type":{"type":"string","enum":["vehicle","offer","closing","org","contact","business","deal","campaign"]},"id":{"type":"string"},"label":{"type":["string","null"]},"links":{"oneOf":[{"$ref":"#/components/schemas/AppLinks"},{"type":"null"}]}},"required":["type","id"]},{"type":"null"}]},"aggregate":{"oneOf":[{"type":"object","description":"Many records under one decision (\"4 deals gone quiet\")","properties":{"count":{"type":"integer"},"value":{"type":["number","null"]},"noun":{"type":"string"},"entityIds":{"type":"array","items":{"type":"string"}}}},{"type":"null"}]},"valueKind":{"type":"string","enum":["blocked","opportunity"],"description":"blocked: money that cannot move until someone acts; opportunity: interest nobody works yet"},"responsible":{"type":"object","properties":{"kind":{"type":"string","enum":["user","role","unassigned"]},"id":{"type":["string","null"],"description":"A member's id, for kind user"},"label":{"type":"string"}}},"dueAt":{"type":["string","null"],"format":"date-time"},"enteredAt":{"type":["string","null"],"format":"date-time"},"automation":{"oneOf":[{"type":"object","properties":{"actor":{"type":"string"},"did":{"type":["string","null"],"description":"Set on a receipt of what an automation already did"},"can":{"type":["string","null"]},"at":{"type":["string","null"],"format":"date-time"}}},{"type":"null"}]},"delegable":{"type":"boolean","description":"Whether it can be given to an agent: a task, or an item about one record (not an aggregate, an organization or a receipt)"},"links":{"$ref":"#/components/schemas/AppLinks","description":"Opens what the item is about in the app (an offer in Seller Hub, a closing, a task where it is worked), or the board"}},"required":["id","source","kind","phase","urgency","title","responsible","delegable"]},"WorkSummary":{"type":"object","description":"Counted over the items returned","properties":{"total":{"type":"integer"},"byPhase":{"type":"object","additionalProperties":{"type":"integer"}},"byUrgency":{"type":"object","additionalProperties":{"type":"integer"}},"automated":{"type":"integer","description":"Receipts of what automations did"},"blockedValue":{"type":"number"},"opportunityValue":{"type":"number"}}},"Delegation":{"type":"object","description":"What delegating an item did","properties":{"task":{"$ref":"#/components/schemas/Task"},"created":{"type":"boolean","description":"True when a task was made"},"how":{"type":"string","enum":["handed-over","made","already"],"description":"handed-over: the item was a task and is now the agent's; made: a new task on the record, the agent's; already: the item was delegated before and its task is still open"},"agent":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"item":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}}}}},"CampaignPeople":{"type":"object","properties":{"reached":{"type":"integer","description":"Distinct people mail was actually handed to the provider for"},"dispatched":{"type":"integer","description":"Messages handed to the provider (a daily campaign mails the same person many times)"},"delivered":{"type":"integer"},"opened":{"type":"integer"},"clicked":{"type":"integer"},"viewers":{"type":"integer","description":"People who opened a car or a promotion page from the campaign"}}},"Campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"kind":{"type":"string","enum":["PROMOTION","CRM"]},"content":{"type":"string","enum":["PROMOTION","INVENTORY","MESSAGE"]},"goal":{"type":"string","enum":["VEHICLE_SALE","ONBOARDING"]},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED"]},"pausedReason":{"type":["string","null"],"enum":["MANUAL","NO_AVAILABLE_VEHICLES",null],"description":"NO_AVAILABLE_VEHICLES resumes on its own at the next send once a car is available"},"pausedAt":{"type":["string","null"],"format":"date-time"},"channel":{"type":"string","enum":["EMAIL"]},"subject":{"type":["string","null"]},"promotionId":{"type":["string","null"]},"vehicleIds":{"type":"array","items":{"type":"string"},"description":"INVENTORY content: the cars it carries"},"audience":{"type":"object","properties":{"source":{"type":"string","enum":["subscribers","crm","email-list","platform"]},"crm":{"type":"object","description":"source crm: the slice of your own book","properties":{"contactIds":{"type":"array","items":{"type":"string"}},"businessIds":{"type":"array","items":{"type":"string"}},"lifecycle":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"withoutOpenDeal":{"type":"boolean"},"engagedUnworked":{"type":"boolean"}}},"emailCount":{"type":"integer","description":"source email-list: how many addresses the list holds"}}},"schedule":{"type":"object","properties":{"frequency":{"type":"string","enum":["DAILY","WEEKLY","BIWEEKLY","MONTHLY"]},"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6}},"dayOfMonth":{"type":["integer","null"]},"hour":{"type":"integer"},"timezone":{"type":"string"},"startDate":{"type":["string","null"],"format":"date-time"},"endDate":{"type":["string","null"],"format":"date-time"},"nextSendAt":{"type":["string","null"],"format":"date-time"},"lastSendAt":{"type":["string","null"],"format":"date-time"}}},"people":{"$ref":"#/components/schemas/CampaignPeople"},"createdAt":{"type":"string","format":"date-time"},"links":{"$ref":"#/components/schemas/AppLinks"},"href":{"type":"string"}}},"CampaignWrite":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":200},"goal":{"type":"string","enum":["VEHICLE_SALE","ONBOARDING"]},"content":{"type":"string","enum":["MESSAGE","INVENTORY","PROMOTION"],"description":"Create only"},"promotionId":{"type":"string","description":"Create only, PROMOTION content: one of your promotions"},"subject":{"type":["string","null"],"maxLength":300},"body":{"type":["string","null"],"maxLength":20000},"vehicleIds":{"type":"array","items":{"type":"string"},"maxItems":200,"description":"INVENTORY content: your own cars"},"audience":{"type":"object","required":["source"],"properties":{"source":{"type":"string","enum":["subscribers","crm"],"description":"Your subscribers, or a slice of your own book. `email-list` is a person's choice in the app (PEOPLE_ONLY); the platform directory is Cypress's (POLICY_DENIED)"},"crm":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string"}},"businessIds":{"type":"array","items":{"type":"string"}},"lifecycle":{"type":"array","items":{"type":"string","enum":["PROSPECT","REACHED","ENGAGED","ON_PLATFORM","ACTIVE","DORMANT"]}},"tags":{"type":"array","items":{"type":"string"}},"withoutOpenDeal":{"type":"boolean"},"engagedUnworked":{"type":"boolean"}}}}},"schedule":{"type":"object","required":["frequency"],"properties":{"frequency":{"type":"string","enum":["DAILY","WEEKLY","BIWEEKLY","MONTHLY"]},"daysOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6}},"dayOfMonth":{"type":["integer","null"],"minimum":1,"maximum":28},"hour":{"type":"integer","minimum":0,"maximum":23,"default":9},"timezone":{"type":"string","default":"America/Chicago"}}},"startDate":{"type":["string","null"],"format":"date-time"},"endDate":{"type":["string","null"],"format":"date-time"}}},"CampaignSend":{"type":"object","properties":{"id":{"type":"string"},"trigger":{"type":"string","enum":["SCHEDULED","MANUAL","TEST"]},"status":{"type":"string","enum":["PENDING","SENDING","SENT","FAILED"]},"scheduledFor":{"type":["string","null"],"format":"date-time"},"sentAt":{"type":["string","null"],"format":"date-time"},"asked":{"type":"integer","description":"Recipients the send asked for, after suppression"},"sent":{"type":"integer"},"delivered":{"type":"integer"},"opened":{"type":"integer"},"clicked":{"type":"integer","description":"People who clicked (a link scanner is not one)"},"viewers":{"type":"integer"},"bounced":{"type":"integer"},"failed":{"type":"integer"},"unsubscribed":{"type":"integer"}}},"CampaignInterest":{"type":"object","properties":{"vehicleId":{"type":"string"},"year":{"type":["integer","null"]},"make":{"type":["string","null"]},"model":{"type":["string","null"]},"vin":{"type":"string"},"views":{"type":"integer"},"saves":{"type":"integer"},"offers":{"type":"integer"},"people":{"type":"integer","description":"Distinct people the campaign brought to this car"}}},"MessageTemplate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":"string","enum":["NEW_INVENTORY","PRICE_DROP","FOLLOW_UP","OUTREACH","ANNOUNCEMENT","OTHER"]},"base":{"type":"boolean","description":"Cypress's base library (read-only) rather than your own"},"published":{"type":["object","null"],"properties":{"version":{"type":"integer"},"subject":{"type":["string","null"]},"document":{"type":"object"},"publishedAt":{"type":"string","format":"date-time"}}},"hasDraft":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time"}}},"AutomationGraph":{"type":"object","description":"An automation as the editor stores it: nodes and the edges between them. The node types, their settings and what each needs are in GET /api/v1/automation/manifest.","required":["nodes","edges"],"properties":{"nodes":{"type":"array","maxItems":200,"items":{"type":"object","required":["id","type","position","data"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["trigger","condition","action","control"]},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}}},"data":{"type":"object","required":["nodeType"],"properties":{"nodeType":{"type":"string","description":"e.g. ENTITY_UPDATED, HAS_LABEL, SET_LISTING_PRICE"},"label":{"type":"string"},"config":{"type":"object"}}}}}},"edges":{"type":"array","maxItems":400,"items":{"type":"object","required":["id","source","target"],"properties":{"id":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"},"sourceHandle":{"type":["string","null"],"description":"A named output: true / false of a Branch, a case of a Switch"},"targetHandle":{"type":["string","null"]}}}}}},"AutomationReview":{"type":"object","description":"Where a draft stands with Cypress. A draft Cypress publishes stops being a draft: it is the published version.","properties":{"state":{"type":"string","enum":["NOT_SUBMITTED","SUBMITTED","SENT_BACK"]},"submittedAt":{"type":["string","null"],"format":"date-time"},"submittedBy":{"type":["string","null"],"description":"The key, app or agent that submitted it, as your audit log names it"},"answeredAt":{"type":["string","null"],"format":"date-time","description":"When Cypress sent it back"},"note":{"type":["string","null"],"description":"What Cypress asked to change"}}},"AutomationVersion":{"type":"object","properties":{"version":{"type":"integer"},"status":{"type":"string","enum":["DRAFT","PUBLISHED"]},"publishedAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"review":{"$ref":"#/components/schemas/AutomationReview","description":"A draft only"},"graph":{"$ref":"#/components/schemas/AutomationGraph","description":"In the automation's own read, never in a list"}}},"Automation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"owner":{"type":"string","enum":["ORGANIZATION","CYPRESS"],"description":"Since 1.10.0. ORGANIZATION: yours to change. CYPRESS: one of Cypress's own that runs on your records, readable so you know what moves your cars, never yours to change (a write answers 404); it shows only its published version, with no draft and no runs"},"category":{"type":"string","enum":["ONBOARDING","PRE_LISTING","LISTING","POST_SALE","MAINTENANCE","RELATIONSHIP"]},"stages":{"type":"array","items":{"type":"string","enum":["OPERATION","PLANNING","REMARKETING","POST_SALE"]},"description":"The life stages it works in; a vehicle in any other is skipped"},"active":{"type":"boolean","description":"Switched on: the published version runs on its trigger"},"trigger":{"type":"object","properties":{"type":{"type":["string","null"]},"detail":{"type":["string","null"]}}},"published":{"oneOf":[{"$ref":"#/components/schemas/AutomationVersion"},{"type":"null"}],"description":"What runs; null until Cypress publishes a version"},"draft":{"oneOf":[{"$ref":"#/components/schemas/AutomationVersion"},{"type":"null"}],"description":"Work in progress, with its review; null when nothing changed since the published version"},"lastRun":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":"string"},"startedAt":{"type":"string","format":"date-time"}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"href":{"type":"string"},"runsHref":{"type":"string"}}},"AutomationWrite":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":100},"description":{"type":["string","null"],"maxLength":1000},"category":{"type":"string","enum":["ONBOARDING","PRE_LISTING","LISTING","POST_SALE","MAINTENANCE","RELATIONSHIP"]},"stages":{"type":"array","minItems":1,"items":{"type":"string","enum":["OPERATION","PLANNING","REMARKETING","POST_SALE"]},"description":"Omitted at create: remarketing only. Operation and Planning need the Planning product. Once Cypress has published a version, the stages are Cypress's to change"},"graph":{"$ref":"#/components/schemas/AutomationGraph","description":"Create only: the first draft (empty when omitted). Save later drafts with PUT .../draft"}}},"AutomationFinding":{"type":"object","properties":{"code":{"type":"string","description":"NOT_ALLOWED (outside what an organization's automation may contain), UNKNOWN_NODE, and the editor's codes: NO_TRIGGER, MULTIPLE_TRIGGERS, INVALID_EDGE, ORPHANED_NODE, MISSING_CONFIG, INVALID_VALUE"},"message":{"type":"string"},"nodeId":{"type":"string"}}},"AutomationRun":{"type":"object","properties":{"id":{"type":"string"},"automationId":{"type":"string"},"version":{"type":["integer","null"]},"dryRun":{"type":"boolean"},"status":{"type":"string","enum":["QUEUED","RUNNING","SUCCESS","PARTIAL","FAILED","DRY_RUN"],"description":"QUEUED: a dry run you asked for that the worker has not started. DRY_RUN: a finished dry run (its steps say what WOULD have happened). PARTIAL: it ran, and some steps were refused or failed (see problems)"},"startedBy":{"type":["string","null"],"enum":["VEHICLE_EVENT","CRM_EVENT","SCHEDULED","MANUAL",null]},"subject":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["vehicle","contact","business","deal"]},"id":{"type":"string"}}},"vehiclesEvaluated":{"type":"integer"},"vehiclesActioned":{"type":"integer"},"problems":{"type":["string","null"],"description":"A refused step, a dry run the worker did not go ahead with (\"Not run: ...\"), or the error a failed run stopped on"},"waitingUntil":{"type":["string","null"],"format":"date-time","description":"A run paused on a Wait step resumes then"},"durationMs":{"type":["integer","null"]},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"stepCount":{"type":"integer","description":"In the run's own read"},"href":{"type":"string"},"stepsHref":{"type":"string"}}},"AutomationRunStep":{"type":"object","properties":{"id":{"type":"string"},"nodeId":{"type":"string"},"nodeType":{"type":"string"},"label":{"type":"string"},"status":{"type":"string","enum":["SUCCESS","SKIPPED","FAILED","DRY_RUN"]},"subject":{"type":["object","null"],"properties":{"type":{"type":"string"},"id":{"type":"string"}}},"input":{},"output":{},"conditionTrace":{"description":"A condition's reasoning: which test passed or failed, on which value"},"error":{"type":["string","null"]},"durationMs":{"type":["integer","null"]},"executedAt":{"type":"string","format":"date-time"}}},"ClosingSignature":{"type":"object","properties":{"party":{"type":"string"},"role":{"type":["string","null"]},"signerKind":{"type":["string","null"],"description":"seller, buyer or external"},"name":{"type":["string","null"]},"status":{"type":"string","description":"pending, viewed, completed or declined"},"completedAt":{"type":["string","null"],"format":"date-time"},"signingLink":{"type":["string","null"],"description":"Your own side's signatures only"},"email":{"type":["string","null"],"description":"Your own side's signatures only"}}},"ClosingDocument":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slot":{"type":["string","null"],"description":"The requirement slot it fills; null is the step's own document"},"status":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time"},"signatures":{"type":"array","items":{"$ref":"#/components/schemas/ClosingSignature"}}}},"ClosingStep":{"type":"object","properties":{"key":{"type":"string","description":"FEE, BOS, CONFIRM_FUNDS, GATE_PASS, TITLE, PICKUP (closings opened before v3 also carry BUYER_SIGN, PAYMENT, TITLE_RECEIPT). Key off this, never the number"},"number":{"type":"integer"},"label":{"type":"string"},"status":{"type":"string","enum":["LOCKED","PENDING","IN_PROGRESS","IN_REVIEW","REJECTED","COMPLETED"]},"deadlineOwner":{"type":"string","enum":["CYPRESS","SELLER"],"description":"Who carries the deadline: the seller on a self-serve channel (a direct link or a storefront), else Cypress"},"turn":{"type":["string","null"],"enum":["SELLER","BUYER","CYPRESS",null],"description":"Who must act now, on an open step"},"yourTurn":{"type":"boolean"},"dueDate":{"type":["string","null"],"format":"date-time"},"overdue":{"type":"boolean"},"lateHours":{"type":["integer","null"],"description":"Since 1.9.0. On an open step whose deadline has passed (exactly when `overdue`), however little: whole hours past it, at least 1. Null when it is not late. Worked out: use it as given"},"daysLate":{"type":["integer","null"],"description":"Since 1.9.0. `lateHours` in whole days, 0 in the first day late; null when it is not late"},"late":{"type":["string","null"],"description":"Since 1.9.0. How late, in plain words: \"8 hours late\" under a day, \"2 days late\" from a day on; null when it is not late"},"dueInHours":{"type":["integer","null"],"description":"Since 1.9.0. Whole hours until `dueDate` while it is still ahead; null when late, not open or with no deadline"},"dueInDays":{"type":["integer","null"],"description":"Since 1.9.0. `dueInHours` in whole days, 0 within the day; null when late, not open or with no deadline"},"unlockedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"nonBlocking":{"type":"boolean"},"titleShipment":{"type":["object","null"],"properties":{"carrier":{"type":["string","null"]},"trackingNumber":{"type":"string"}}},"documents":{"type":"array","items":{"$ref":"#/components/schemas/ClosingDocument"}}}},"ClosingRequirement":{"type":"object","properties":{"id":{"type":"string"},"step":{"type":"string"},"slot":{"type":"string"},"name":{"type":"string"},"required":{"type":"boolean"},"waived":{"type":"boolean"},"document":{"type":["object","null"],"properties":{"id":{"type":"string"},"status":{"type":"string"}}},"satisfied":{"type":"boolean","description":"Waived, or its latest document accepted"}}},"Closing":{"type":"object","properties":{"id":{"type":"string"},"side":{"type":"string","enum":["SELLER","BUYER"]},"status":{"type":"string","enum":["IN_PROGRESS","COMPLETED","CANCELLED"]},"vehicle":{"type":"object","properties":{"id":{"type":"string"},"vin":{"type":"string"},"year":{"type":["integer","null"]},"make":{"type":["string","null"]},"model":{"type":["string","null"]},"trim":{"type":["string","null"]}}},"counterparty":{"type":"object","description":"The other party of your trade, by its organization's name only (no person, no contact detail)","properties":{"side":{"type":"string","enum":["SELLER","BUYER"]},"name":{"type":["string","null"]}}},"price":{"type":["number","null"],"description":"The agreed price, USD"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"cancelledAt":{"type":["string","null"],"format":"date-time"},"closedOffPlatform":{"type":"boolean"},"currentStep":{"type":["string","null"],"description":"The first open step that blocks the closing, else the first open one"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/ClosingStep"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/ClosingRequirement"}},"dealSetup":{"type":["object","null"],"description":"Where Deal Setup stands, so a reader sees who it waits on without another call; null for a closing that predates Deal Setup. Since 1.9.0.","properties":{"seller":{"$ref":"#/components/schemas/ClosingDealSetupSide"},"buyer":{"$ref":"#/components/schemas/ClosingDealSetupSide"}}},"urgency":{"type":["object","null"],"description":"Since 1.9.0. The current step, worked out for what needs whom first: whose turn it is, its deadline, and how late it is or how long it has left (as on the step). Null when nothing is open. An MCP list's summary view keeps it, where the steps are left out. `sort=urgency` orders the list by it.","properties":{"step":{"type":"string","description":"The current step's key"},"turn":{"type":["string","null"],"enum":["SELLER","BUYER","CYPRESS",null],"description":"Who must act now"},"yourTurn":{"type":"boolean"},"dueDate":{"type":["string","null"],"format":"date-time"},"lateHours":{"type":["integer","null"]},"daysLate":{"type":["integer","null"]},"late":{"type":["string","null"]},"dueInHours":{"type":["integer","null"]},"dueInDays":{"type":["integer","null"]}}},"links":{"$ref":"#/components/schemas/AppLinks"},"href":{"type":"string"}}},"ClosingDealSetupSide":{"type":"object","properties":{"confirmed":{"type":"boolean"},"confirmedAt":{"type":["string","null"],"format":"date-time"},"blanks":{"type":"array","items":{"type":"string"},"description":"The facts this side still leaves empty, by name, never their values: pickupLocation, bankAccount (when no lender is named either) and poNumber (when the seller needs a PO; the seller's own read only) on the seller's side; titleAddress and transporter on the buyer's; custom.seller.<key> or custom.buyer.<key> for each custom field the organization asks at Deal Setup. Only a required PO stops a side from confirming."}}},"NotificationPreference":{"type":"object","required":["workflow","name","enabled","channels"],"properties":{"workflow":{"type":"string","description":"The workflow's identifier: what a change names"},"name":{"type":"string"},"enabled":{"type":"boolean"},"channels":{"type":"object","properties":{"email":{"type":["boolean","null"]},"inApp":{"type":["boolean","null"]}}}}},"Notification":{"type":"object","required":["id","type","title","message","severity","actionUrl","vehicleId","recipient","createdAt"],"properties":{"id":{"type":"string"},"type":{"type":"string","description":"What happened, in Cypress's own vocabulary (OFFER_DECLINED, REMINDER_TASK_DUE, …): a label, not a closed list"},"title":{"type":"string"},"message":{"type":"string"},"severity":{"type":"string","enum":["CRITICAL","WARNING","INFO","TASK"]},"actionUrl":{"type":["string","null"],"description":"Where it opens in the app, absolute"},"vehicleId":{"type":["string","null"]},"targetId":{"type":"string","description":"Since 1.9.0. The buy target it is about (a buy plan match, type BUY_PLAN_MATCH); absent otherwise"},"recipient":{"type":"object","required":["userId","kind","name"],"properties":{"userId":{"type":"string"},"kind":{"type":"string","enum":["PERSON","AGENT"]},"name":{"type":["string","null"]}}},"createdAt":{"type":"string","format":"date-time"},"cursor":{"type":"string","description":"In a read: the event's cursor in your event log (GET /api/v1/events)"},"href":{"type":"string","description":"In a read: /api/v1/notifications/{id}"}}},"Insight":{"type":"object","description":"One insight (since 1.5.0): what Cedar or Sequoia knows about a vehicle or a buy target, with what it rests on, how sure it is and the guardrail that applied","properties":{"kind":{"type":"string","enum":["sell-hold","pricing","campaign","sequoia","listing","buy-guide"]},"by":{"type":"string","enum":["cedar","sequoia","sakura","rules"],"description":"Who wrote it; `rules` is the Buy plan's own arithmetic, no model"},"summary":{"type":"string"},"confidence":{"type":"object","properties":{"score":{"type":["integer","null"],"minimum":0,"maximum":100},"level":{"type":["string","null"],"enum":["HIGH","MEDIUM","LOW",null]}}},"basis":{"type":"object","properties":{"facts":{"type":"object","additionalProperties":true,"description":"The facts it read (the owner's floor and target appear only in an owner's insights)"},"reasons":{"type":"array","items":{"type":"string"}}}},"guardrail":{"oneOf":[{"type":"object","properties":{"code":{"type":"string","description":"NO_VALUATION, VALUATION_STALE, BELOW_FLOOR, TOO_FEW_SALES, or a Sequoia guardrail (OFFER, PRICE_ABOVE_TARGET, BUDGET_SHARE, GOAL_CHANGE, SCHEDULE_CHANGE)"},"words":{"type":"string"}},"required":["code","words"]},{"type":"null"}]},"data":{"type":"object","additionalProperties":true,"description":"The kind's own fields: sell-hold `decision`; pricing `suggestedFloor`, `suggestedTarget`, `daysToSellEstimate`, `marketPosition`; campaign `readiness`, `estimatedBuyerMatches`, `recommendedChannels`; buy-guide `tier`, `low`, `mid`, `high`, `trend`, `targetVsRange`, `maxVsRange`, `ownBand`; sequoia `id`, `kind`, `status`, `action`, `periodKey`"},"generatedAt":{"type":"string","format":"date-time"},"cached":{"type":"boolean","description":"Served from the cache: a model answer is kept for six hours, keyed on everything it read"}},"required":["kind","by","summary","confidence","basis","guardrail","data","generatedAt","cached"]},"OfferDecision":{"type":"object","properties":{"result":{"type":"object","properties":{"offerId":{"type":"string"},"status":{"type":"string","description":"The new status, or WOULD_ACCEPT / WOULD_REJECT / WOULD_COUNTER / WOULD_WITHDRAW on a dry run"},"message":{"type":"string"},"counterAmount":{"type":"number"},"counterExpiresAt":{"type":"string","format":"date-time"}}},"offer":{"$ref":"#/components/schemas/OfferRead"},"dryRun":{"type":"boolean"}}},"FeedEvent":{"type":"object","description":"One event from your organization's event log. The same events webhooks deliver, kept 30 days.","properties":{"cursor":{"type":"string","description":"Position in the log; increases with every event. Resume from it with `after`."},"eventType":{"type":"string","description":"Canonical (Cypress) name"},"resource":{"type":"string"},"resourceId":{"type":"string"},"eventId":{"type":["string","null"],"description":"A deterministic id when the event can be reported more than once"},"related":{"type":["object","null"]},"context":{"type":["object","null"]},"occurredAt":{"type":"string","format":"date-time"}}},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"href":{"type":"string"},"eventType":{"type":"string"},"resource":{"type":"string"},"resourceId":{"type":"string"},"status":{"type":"string","enum":["PENDING","DELIVERED","FAILED","DEAD"]},"attempts":{"type":"integer"},"responseStatus":{"type":"integer"},"lastAttemptAt":{"type":"string","format":"date-time"},"deliveredAt":{"type":"string","format":"date-time"},"createdOn":{"type":"string","format":"date-time"},"bodyWithheld":{"type":"string","description":"On one delivery (`GET /deliveries/{id}`) only, and only when its body was left out because the key may not read it: the scope that shows it — `buy-planning:read` for a `BUY.*` delivery (the Buy planning read capability), `tasks:read` for a `TASK.*` one (since 1.5.0). `envelope.body` is `null` then."}}},"EventEnvelope":{"type":"object","description":"Delivered with content-type application/json, your registered headers, and x-cypress-signature (HMAC-SHA256 hex of the body, keyed by your signingSecret). Retries: 5 attempts, exponential backoff from 10s; order by createdOn, dedupe on x-cypress-delivery.","properties":{"href":{"type":"string"},"eventType":{"type":"string","description":"In your subscription dialect"},"resource":{"type":"string","description":"vehicles, listings, offers, closing, subscriptions, plan (PLAN.* about a vehicle) or buy (BUY.*) about a target; since 1.5.0 also tasks, notifications, campaigns, contacts, businesses, deals, interactions, automations, automation-runs, planning-goals, planning-quarters, buy-quarters and insights"},"body":{"description":"Resource state at delivery time — for resource `plan` (PLAN.* events), a PlanEventBody. For resource `buy` (BUY.* events) it is not the state at delivery but the moment the event happened (built then, from the same target and match objects the Buy planning reads return): a BuyMatchedEventBody, a BuyFilledEventBody or a BuyEndedEventBody; `href` serves the target as it is now.","anyOf":[{"type":"object"},{"$ref":"#/components/schemas/PlanEventBody"},{"$ref":"#/components/schemas/BuyMatchedEventBody"},{"$ref":"#/components/schemas/BuyFilledEventBody"},{"$ref":"#/components/schemas/BuyEndedEventBody"}]},"createdOn":{"type":"string","format":"date-time"},"relatedResources":{"type":"array","items":{"type":"object","properties":{"href":{"type":"string"}}}},"cursor":{"type":"string","description":"Cypress dialect: the event's position in GET /api/v1/events. Dedupe on it; after downtime, read the feed from your last one."},"links":{"$ref":"#/components/schemas/AppLinks","description":"Cypress dialect: where the event's record opens in the app (since 1.5.0)"}}},"ManheimUnit":{"type":"object","description":"Manheim Units payload. Unmapped fields are preserved and echoed back on reads.","properties":{"type":{"type":"string","example":"PASSENGER_VEHICLE"},"vin":{"type":"string","minLength":17,"maxLength":17},"description":{"type":"object","properties":{"modelYear":{"type":"integer"},"make":{"type":"string"},"model":{"type":"string"},"trim":{"type":"string"},"transmission":{"type":"string"},"engine":{"type":"object","properties":{"type":{"type":"string"},"fuel":{"type":"string"}}},"exteriorColor":{"type":"string"},"interiorColor":{"type":"string"},"driveType":{"type":"string"},"doorCount":{"type":"integer"}},"required":["modelYear","make","model"]},"odometer":{"type":"object","properties":{"reading":{"type":"integer"},"units":{"type":"string","enum":["MILES","KILOMETERS","MI","KM","M","K"]}}},"physicalLocation":{"$ref":"#/components/schemas/Location"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"offering":{"allOf":[{"$ref":"#/components/schemas/ListingWrite"}],"description":"Cypress extension — create the offering in the same push."},"lifeStage":{"type":"string","enum":["OPERATION","PLANNING","REMARKETING","POST_SALE","RETIRED"],"description":"Cypress extension. Where the vehicle is in its life. Sell stock (REMARKETING, POST_SALE, RETIRED) is visible to any `vehicles` key, by default. OPERATION and PLANNING (planning stock) are visible only to a `planning:read` key on an organization with Planning switched on — invisible otherwise. A Sell write to planning stock (PUT, a re-push, prices, listings, deletion, sold-elsewhere) answers 409 PLANNING_STOCK when the organization has Planning (it is waiting for its plan's hand-off), or 403 PLANNING_NOT_ENABLED when it does not (it is frozen). Since 1.3.0 a `planning:write` key keeps planning stock current with PATCH and the Planning routes. Read-only here — ManheimUnit is also the request body, and compat writes ignore this field.","readOnly":true}},"required":["vin","description"]},"ManheimOffering":{"type":"object","description":"Reference the unit via unitId, unitHref, or Manheim-style unit.href.","properties":{"unitId":{"type":"string"},"unitHref":{"type":"string"},"unit":{"type":"object","properties":{"href":{"type":"string"}}},"floorPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"buyNowPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"startBidPrice":{"type":"number","exclusiveMinimum":0,"description":"USD, dollars"},"channels":{"type":"array","items":{"type":"string","enum":["MARKETPLACE","STOREFRONT","DIRECT_LINK"]}},"listingMode":{"type":"string","enum":["REVIEW","IMMEDIATE"]}}},"Capability":{"type":"object","description":"One thing this key could do — allowed, or refused with the same reason code the refusing route would return.","properties":{"capability":{"type":"string","description":"e.g. vehicles.read, listings.channel.STOREFRONT, planning.read, buy-planning.write"},"allowed":{"type":"boolean"},"reason":{"type":"string","enum":["ORG_NOT_ACTIVE","ACCOUNT_RULES","PLANNING_NOT_ENABLED","BUY_PLANNING_NOT_ENABLED","AUTOMATIONS_NOT_ENABLED","SCOPE_MISSING","CHANNEL_NOT_GRANTED"],"description":"Present only when allowed is false."}},"required":["capability","allowed"]},"OrganizationProfile":{"type":"object","description":"What this organization and key may do. Answers any valid key, whatever the organization's status.","properties":{"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string"},"profiles":{"type":"array","items":{"type":"string"}}}},"account":{"type":"object","description":"Since 1.9.0 — the account's rules as they hold for this organization: its kind (an INDIVIDUAL is a private person, a BUSINESS a dealer or fleet), which features are on, its caps and what it used of them. Cypress sets them per kind and per organization; what they refuse says ACCOUNT_RULES.","properties":{"kind":{"type":"string","enum":["INDIVIDUAL","BUSINESS"]},"features":{"type":"object","description":"true when on: team, apps, apiKeys, pricingRules, campaigns, valuations, listings, and the rest of the account rules.","additionalProperties":{"type":"boolean"}},"limits":{"type":"object","description":"null: no cap.","properties":{"valuations":{"type":["integer","null"],"description":"Black Book valuations, in total."},"listings":{"type":["integer","null"],"description":"Cars listed, in total (a car counts the first time it is listed)."},"teamMembers":{"type":["integer","null"],"description":"People in the account, owner included."},"campaignEmailsPerMonth":{"type":["integer","null"],"description":"Campaign emails a month (UTC)."},"cedarAnswersPerDay":{"type":["integer","null"],"description":"Cedar's answers a day, in Grove."}}},"used":{"type":"object","description":"What the organization used of its counted caps.","properties":{"valuations":{"type":"integer"},"listings":{"type":"integer"},"teamMembers":{"type":"integer"},"campaignEmailsPerMonth":{"type":"integer"}}}}},"apiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["vehicles","listings","webhooks","planning:read","planning:write","buy-planning:read","buy-planning:write","offers:read","offers:write","members:read","connections:write","tasks:read","tasks:write","crm:read","crm:write","mission-control:read","insights:read","notifications:read","notifications:write","closing:read","closing:write","marketing:read","marketing:write","automations:read","automations:write"]}},"createdAt":{"type":"string","format":"date-time"}}},"products":{"type":"object","properties":{"remarketing":{"type":"object","properties":{"enabled":{"type":"boolean"}}},"planning":{"type":"object","description":"Sell planning (the `planning:*` scopes).","properties":{"enabled":{"type":"boolean"},"requestedAt":{"type":["string","null"],"format":"date-time"}}},"buyPlanning":{"type":"object","description":"Buy planning (the `buy-planning:*` scopes) — a switch of its own, separate from Planning. Since 1.4.0.","properties":{"enabled":{"type":"boolean"},"requestedAt":{"type":["string","null"],"format":"date-time"}}},"automations":{"type":"object","description":"Your own automations (the `automations:*` scopes): a product Cypress switches on per organization. Since 1.5.0.","properties":{"enabled":{"type":"boolean"}}}}},"channels":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["MARKETPLACE","STOREFRONT","DIRECT_LINK"]},"enabled":{"type":"boolean"},"published":{"type":"boolean","description":"STOREFRONT only — the storefront is live for buyers"}}}},"billing":{"type":"object","description":"No card brand/last4 or credit figures — standing and payment method type only.","properties":{"standing":{"type":"string","description":"The organization's billingStatus"},"autoPay":{"type":"string","enum":["ACH","CARD","NONE"]}}},"delegation":{"type":"object","description":"What the organization lets Cypress do, as it stands now: a grant past its end date reads as off.","properties":{"cypressMayActOnBehalf":{"type":"boolean"},"cypressDecidesReviewOffers":{"type":"boolean"},"cypressMayMakeBuyerOffers":{"type":"boolean"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the switches end; null for no end date. Since 1.9.0"},"expired":{"type":"boolean","description":"The end date passed: every switch reads as off. Since 1.9.0"}}},"accountManager":{"type":["object","null"],"description":"Since 1.9.0. The organization's Cypress Manager, the person at Cypress who looks after it; null when none is assigned. Only who they are and how to reach them.","additionalProperties":false,"properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["id","name","email"]},"capabilities":{"type":"array","items":{"$ref":"#/components/schemas/Capability"}},"rateLimit":{"type":"object","properties":{"requestsPerMinute":{"type":"integer"}}}}},"Ownership":{"type":"object","additionalProperties":false,"description":"Purchase & financing — the app's field rules. null clears a field. Cross-field checks (a purchase date in the future or before the model could be bought, a payoff before the purchase, a balloon as large as the loan) refuse with 422; softer findings come back as `warnings` and are saved.","properties":{"purchasePrice":{"type":["number","null"],"exclusiveMinimum":0,"maximum":5000000},"purchaseDate":{"type":["string","null"],"format":"date","description":"YYYY-MM-DD"},"acquisitionMethod":{"type":["string","null"],"enum":["CASH","FINANCING","BALLOON","LEASE_BUYOUT","ESCROW",null]},"downPayment":{"type":["number","null"],"minimum":0,"maximum":5000000},"loanAmount":{"type":["number","null"],"minimum":0,"maximum":5000000},"loanTermMonths":{"type":["integer","null"],"minimum":1,"maximum":120},"interestRate":{"type":["number","null"],"minimum":0,"maximum":40,"description":"APR, percent"},"monthlyPayment":{"type":["number","null"],"minimum":0,"maximum":5000000},"balloonAmount":{"type":["number","null"],"minimum":0,"maximum":5000000},"payoffDate":{"type":["string","null"],"format":"date","description":"YYYY-MM-DD"},"remainingBalance":{"type":["number","null"],"minimum":0,"maximum":5000000}}},"FinancingFigure":{"type":["object","null"],"properties":{"value":{"description":"A number (money, percent) or a YYYY-MM-DD date"},"source":{"type":"string","enum":["ENTERED","CALCULATED"]},"how":{"type":"string","description":"How a calculated figure was reached, in words"}}},"OwnershipRead":{"type":"object","description":"The record as stored, and what Cypress works out from it. No market value.","properties":{"ownership":{"$ref":"#/components/schemas/Ownership"},"effective":{"type":"object","properties":{"scheduled":{"type":"boolean","description":"A payment schedule applies (a financed purchase, a balloon credit, a financed buyout)"},"principal":{"$ref":"#/components/schemas/FinancingFigure"},"interestRate":{"$ref":"#/components/schemas/FinancingFigure"},"monthlyPayment":{"$ref":"#/components/schemas/FinancingFigure"},"payoffDate":{"$ref":"#/components/schemas/FinancingFigure"},"balance":{"$ref":"#/components/schemas/FinancingFigure"},"paymentsMade":{"type":["integer","null"]},"notes":{"type":"array","items":{"type":"string"},"description":"What could not be worked out, and what to add"}}}}},"OdometerWrite":{"type":"object","additionalProperties":false,"description":"Exactly one of miles or km (km is converted to miles).","properties":{"readAt":{"type":"string","format":"date","description":"YYYY-MM-DD; not in the future"},"miles":{"type":"integer","minimum":0},"km":{"type":"integer","minimum":0},"force":{"type":"boolean","description":"Accept a reading that runs the series backwards (a replaced or corrected odometer)"}},"required":["readAt"]},"OdometerReading":{"type":"object","properties":{"id":{"type":"string"},"readAt":{"type":"string","format":"date","description":"YYYY-MM-DD"},"miles":{"type":"integer"},"source":{"type":"string","description":"api, manual, import, …"},"verified":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"CostEventWrite":{"type":"object","additionalProperties":false,"properties":{"category":{"type":"string","enum":["MAINTENANCE","REPAIR","FUEL","INSURANCE","REGISTRATION","OTHER"]},"amount":{"type":"number","exclusiveMinimum":0,"maximum":1000000,"description":"USD, dollars"},"eventDate":{"type":"string","format":"date","description":"YYYY-MM-DD"},"note":{"type":"string","maxLength":300},"externalRef":{"type":"string","minLength":1,"maxLength":100,"description":"Your id for this cost. A POST with a ref already stored for the vehicle returns the stored row (200) and writes nothing — even if the body differs."}},"required":["category","amount","eventDate"]},"CostEvent":{"type":"object","properties":{"id":{"type":"string"},"category":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"eventDate":{"type":"string","format":"date","description":"YYYY-MM-DD"},"note":{"type":["string","null"]},"externalRef":{"type":["string","null"]},"sourceTier":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"DepartureRequest":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["LEFT_FLEET","SOLD_OFF_PLATFORM"]},"reason":{"type":"string","maxLength":300},"soldPrice":{"type":"number","exclusiveMinimum":0,"description":"SOLD_OFF_PLATFORM only"},"soldAt":{"type":"string","format":"date","description":"YYYY-MM-DD, SOLD_OFF_PLATFORM only; not in the future"}},"required":["kind"]},"PlanWindowRef":{"type":["object","null"],"properties":{"id":{"type":"string","description":"This plan version's window id — changes with every version; use it for writes"},"lineage":{"type":"string","description":"The window across versions, e.g. 2026W44-2026W45 — stable"},"label":{"type":"string","description":"e.g. W44–45"},"quarter":{"type":"string","description":"Since 1.4.0. The quarter the window counts in — the one that holds its 8th day, e.g. 2026-Q4"},"closed":{"type":"boolean","description":"Since 1.4.0. True once that quarter is over (its last day has passed, UTC): the same test the server refuses by with 409 QUARTER_CLOSED. Read this, not `state`, to know whether a window takes writes"}}},"PlanSummary":{"type":"object","properties":{"strategy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"objective":{"type":"string"},"constraints":{"type":"object"}}},"plan":{"type":"object","properties":{"version":{"type":"integer","description":"A revision counter: correlate your writes and reads with it. The Planning page no longer shows version numbers"},"createdAt":{"type":"string","format":"date-time"},"note":{"type":"string","description":"Free text for people — don't parse it"}}},"windows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"lineage":{"type":"string"},"label":{"type":"string"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["PLANNED","ACTIVE","CLOSED"],"description":"The window's own state. A window of a closed quarter that has not been swept yet still reads PLANNED or ACTIVE — see `closed`"},"quarter":{"type":"string","description":"Since 1.4.0. The quarter the window counts in — the one that holds its 8th day, e.g. 2026-Q4"},"closed":{"type":"boolean","description":"Since 1.4.0. True once that quarter is over (its last day has passed, UTC): the same test the server refuses by with 409 QUARTER_CLOSED"},"links":{"$ref":"#/components/schemas/AppLinks","description":"Since 1.5.0. Opens the window's panel on the Sell plan: the live window of this lineage, even after the plan moves to a new version"}}}},"tracks":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Stable — name a track by its key in POST /planning/moves/track"},"name":{"type":"string"},"objective":{"type":"string"},"posture":{"type":"object","properties":{"listAt":{"type":"string","enum":["MARKET","ABOVE","BELOW"]},"acceptPct":{"type":"number","description":"Accept an offer from this share of the plan value"},"urgency":{"type":"string","enum":["FAST","NORMAL","PATIENT"]}}},"isDefault":{"type":"boolean","description":"Vehicles not on a track ride the default track"}}}}}},"PlanVehicleRow":{"type":"object","properties":{"vehicleId":{"type":"string"},"vin":{"type":"string"},"lifeStage":{"type":"string","enum":["OPERATION","PLANNING","REMARKETING","POST_SALE","RETIRED"],"description":"Where the vehicle is in its life. Sell stock (REMARKETING, POST_SALE, RETIRED) is visible to any `vehicles` key, by default. OPERATION and PLANNING (planning stock) are visible only to a `planning:read` key on an organization with Planning switched on — invisible otherwise. A Sell write to planning stock (PUT, a re-push, prices, listings, deletion, sold-elsewhere) answers 409 PLANNING_STOCK when the organization has Planning (it is waiting for its plan's hand-off), or 403 PLANNING_NOT_ENABLED when it does not (it is frozen). Since 1.3.0 a `planning:write` key keeps planning stock current with PATCH and the Planning routes.","readOnly":true},"membershipState":{"type":["string","null"],"enum":["CANDIDATE","STAGED","CONDITIONAL","PROMOTED","SLIPPED","HELD","IN_OPERATION","PARKED",null]},"window":{"$ref":"#/components/schemas/PlanWindowRef"},"track":{"type":["object","null"],"description":"The effective track — the default track for a vehicle not on one","properties":{"key":{"type":"string"},"name":{"type":"string"}}},"plannedValue":{"type":["number","null"]},"rank":{"type":["integer","null"]},"carriedOver":{"type":"integer","description":"Windows this vehicle failed to sell in (carried into the next one)"},"blockers":{"type":"array","description":"Open blockers only","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"note":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}},"market":{"type":["object","null"],"description":"The latest valuation (wholesale) and its band. null until the vehicle has been valued.","properties":{"value":{"type":"number"},"band":{"type":["object","null"],"properties":{"low":{"type":"number"},"high":{"type":"number"}}},"asOf":{"type":"string","format":"date-time"}}},"advice":{"type":["object","null"],"description":"The latest stored plan advice","properties":{"action":{"type":"string"},"confidence":{"type":"number"},"reasoning":{"type":"string","description":"Free text for people — don't parse it. Since 1.4.0 it no longer carries a plan version number"},"asOf":{"type":"string","format":"date-time"}}},"links":{"$ref":"#/components/schemas/AppLinks"}}},"PlanVehicleDetail":{"allOf":[{"$ref":"#/components/schemas/PlanVehicleRow"},{"type":"object","properties":{"market":{"type":"object","description":"The app's own market position for this vehicle — may be up to 60 s stale.","properties":{"value":{"type":["number","null"]},"band":{"type":["object","null"],"properties":{"low":{"type":"number"},"high":{"type":"number"}}},"expectedRealized":{"type":["object","null"],"properties":{"amount":{"type":"number"},"low":{"type":"number"},"high":{"type":"number"}}},"realizationBasis":{"type":"string","enum":["MODEL_YEAR","MODEL","CLASS","NONE"]},"trendPctPerMonth":{"type":["number","null"]}}},"verdict":{"type":"object","properties":{"kind":{"type":"string","enum":["SELL_NOW","HOLD","IN_SELL","DONE","NO_BASIS"]},"title":{"type":"string"},"reason":{"type":["string","null"],"description":"Why, in words for people — don't parse it. Since 1.10.0"}}},"economics":{"type":["object","null"],"description":"What holding the vehicle costs and when it sells best: Sequoia's own figures, the ones its verdict stands on. Null when its value is unavailable. Since 1.10.0.","properties":{"points":{"type":"array","description":"Bi-weekly: the projected value (gross), and what you end up with if it is released that week (net of selling cost and of what it earned or cost while held)","items":{"type":"object","properties":{"label":{"type":"string"},"gross":{"type":"number"},"net":{"type":"number"},"inWindow":{"type":"boolean"}}}},"bestWindow":{"type":["object","null"],"description":"The weeks it sells best (by net), the best one, and whether now is in them","properties":{"label":{"type":"string"},"bestWeek":{"type":"string"},"nowInWindow":{"type":"boolean"},"dates":{"type":"string"}}},"basis":{"type":"string","enum":["CONTRIBUTION","DECAY_ONLY"],"description":"CONTRIBUTION: the hold is modeled from your operating data. DECAY_ONLY: nothing it earns is modeled, so earlier is always better"},"waits":{"type":["object","null"],"description":"The value's change against now after 1, 3 and 6 months (negative: it loses)","properties":{"m1":{"type":"number"},"m3":{"type":"number"},"m6":{"type":"number"}}},"monthlyCost":{"type":"object","description":"What one more month of waiting costs: the value it loses (null when unknown) and what it costs to run","properties":{"valueLoss":{"type":["number","null"]},"running":{"type":"number"}}},"weeklyRunningCost":{"type":"object","properties":{"amount":{"type":"number"},"tier":{"type":"string"},"source":{"type":"string"}}}}},"suggestion":{"type":"string"},"plan":{"type":"object","properties":{"version":{"type":"integer"},"at":{"type":"string","format":"date-time"},"strategy":{"type":"string"}}},"links":{"$ref":"#/components/schemas/AppLinks"}}}]},"Skipped":{"type":"array","description":"Vehicles this call left as they were, each with its reason (\"not in the plan\" — also an unknown id or another organization's; \"already a candidate\"; \"in Sell — remarketing owns it\"; \"disputed evidence blocks scheduling\"; …). The rest of the call still applies.","items":{"type":"object","properties":{"vehicleId":{"type":"string"},"reason":{"type":"string"}}}},"PlanningMove":{"type":"object","additionalProperties":false,"properties":{"vehicleIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}},"to":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"windowId":{"type":"string"}},"required":["windowId"]},{"type":"string","enum":["BENCH","OPERATION"]}],"description":"{ windowId } schedules into that window of the latest plan — an id read from an earlier plan version is accepted and followed by its lineage to the latest version's window; BENCH benches as candidates; OPERATION takes them off the plan's table, back to running the fleet."},"reason":{"type":"string","maxLength":300}},"required":["vehicleIds","to"]},"PlanningTrackMove":{"type":"object","additionalProperties":false,"properties":{"vehicleIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}},"trackKey":{"type":"string","minLength":1,"maxLength":60},"reason":{"type":"string","maxLength":300}},"required":["vehicleIds","trackKey"]},"PlanningPark":{"type":"object","additionalProperties":false,"properties":{"vehicleIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}},"untilQuarter":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","example":"2027-Q1","description":"A quarter that has not started yet"},"reason":{"type":"string","maxLength":300}},"required":["vehicleIds","untilQuarter"]},"PlanningUnpark":{"type":"object","additionalProperties":false,"properties":{"vehicleIds":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string"}}},"required":["vehicleIds"]},"BlockerCreate":{"type":"object","additionalProperties":false,"properties":{"vehicleId":{"type":"string"},"kind":{"type":"string","enum":["PAYOFF","EVIDENCE","ARRIVALS","AUTHORITY","OTHER"]},"note":{"type":"string","minLength":3,"maxLength":300}},"required":["vehicleId","kind","note"]},"BlockerPatch":{"oneOf":[{"type":"object","additionalProperties":false,"title":"Resolve","properties":{"resolvingRef":{"type":"string","minLength":5,"maxLength":200,"description":"The evidence that cleared it — a document, an order id, an inspection"}},"required":["resolvingRef"]},{"type":"object","additionalProperties":false,"title":"Edit","minProperties":1,"properties":{"kind":{"type":"string","enum":["PAYOFF","EVIDENCE","ARRIVALS","AUTHORITY","OTHER"]},"note":{"type":"string","minLength":3,"maxLength":300}}}]},"Blocker":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"note":{"type":"string"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"resolvingRef":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"CohortPreview":{"type":"object","properties":{"windowId":{"type":"string","description":"The window in the LATEST plan version (may differ from the id you sent)"},"planId":{"type":"string"},"planVersion":{"type":"integer"},"digest":{"type":"string","description":"Binds the confirm to exactly this cohort — echo it"},"expiresAt":{"type":"string","format":"date-time","description":"24 hours from the preview — echo it"},"declaredEffects":{"type":"array","items":{"type":"string"},"example":["INTERNAL_INTAKE"]},"doesNot":{"type":"array","items":{"type":"string"},"description":"What confirming does NOT do: list, disclose to buyers, accept offers, …"},"members":{"type":"array","items":{"type":"object","properties":{"vehicleId":{"type":"string"},"vin":{"type":"string"},"label":{"type":"string"},"state":{"type":"string"},"disposition":{"type":"string","enum":["PROMOTE","HOLD_CONDITIONAL","BLOCKED"],"description":"PROMOTE: no open blocker. HOLD_CONDITIONAL: an open blocker (payoff, arrivals, …). BLOCKED: an open EVIDENCE blocker."},"blockers":{"type":"array","items":{"type":"string"},"description":"Open blockers as \"KIND: note\""}}}}}},"CohortConfirm":{"type":"object","additionalProperties":false,"properties":{"digest":{"type":"string","minLength":8},"expiresAt":{"type":"string","minLength":8}},"required":["digest","expiresAt"]},"PlanEventBody":{"type":"object","description":"The `body` of a PLAN.* envelope (resource `plan`; `href` = /api/v1/planning/vehicles/{vehicleId}). `{ vehicleId, deleted: true }` when the vehicle no longer exists.","properties":{"vehicleId":{"type":"string"},"vin":{"type":"string"},"membershipState":{"type":["string","null"]},"window":{"type":["object","null"],"properties":{"id":{"type":"string"},"lineage":{"type":"string"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"}}},"track":{"type":["object","null"],"description":"The effective track — the default track for a vehicle not on one (as GET /api/v1/planning/vehicles reports it); null only when the vehicle is not in the plan or the strategy has no tracks","properties":{"key":{"type":"string"},"name":{"type":"string"}}},"plannedValue":{"type":["number","null"]},"openBlockers":{"type":"integer","description":"A count — read the blockers with GET /api/v1/planning/blockers?vehicleId="}}},"PlanningGoalParams":{"description":"What a goal asks of the quarter, by `kind`. UNITS: sell `units` vehicles (of one lot with `lotKey`, e.g. \"2021|NISSAN|SENTRA\"). CASH: release `amount` USD by `byDate`. SHAPE: leave the fleet within these limits (at least one). RENEWAL: release vehicles ahead of the arrivals planned per month.","oneOf":[{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["UNITS"]},"units":{"type":"integer","minimum":1,"maximum":10000},"lotKey":{"type":"string","maxLength":200}},"required":["kind","units"]},{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["CASH"]},"amount":{"type":"number","exclusiveMinimum":0,"maximum":1000000000,"description":"USD"},"byDate":{"type":"string","format":"date","description":"YYYY-MM-DD"}},"required":["kind","amount","byDate"]},{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["SHAPE"]},"avgAgeMaxYears":{"type":"number","exclusiveMinimum":0,"maximum":40},"mileageMax":{"type":"integer","minimum":1},"classMixMax":{"type":"object","additionalProperties":{"type":"number","minimum":0,"maximum":1},"description":"Largest share per class, e.g. { \"TRUCK\": 0.3 }"}},"required":["kind"]},{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["RENEWAL"]},"arrivals":{"type":"array","minItems":1,"maxItems":36,"items":{"type":"object","properties":{"monthKey":{"type":"string","example":"2026-11"},"count":{"type":"integer","minimum":0,"maximum":10000},"planningClass":{"type":"string","enum":["CAR","SUV","TRUCK","VAN"]}},"required":["monthKey","count"]}},"releasesPerArrival":{"type":"number","exclusiveMinimum":0,"maximum":10,"default":1}},"required":["kind","arrivals"]}]},"PlanningMonthlyTargets":{"type":"array","minItems":1,"maxItems":3,"description":"The goal's pacing, month by month. Left out, Cypress splits the goal over the quarter's months.","items":{"type":"object","properties":{"monthKey":{"type":"string","example":"2026-11"},"value":{"type":"number","minimum":0}},"required":["monthKey","value"]}},"PlanningGoalWrite":{"type":"object","additionalProperties":false,"properties":{"label":{"type":"string","maxLength":120,"description":"Left out: made from the goal (\"Sell 12 vehicles\")"},"params":{"$ref":"#/components/schemas/PlanningGoalParams"},"monthlyTargets":{"$ref":"#/components/schemas/PlanningMonthlyTargets"},"trackId":{"type":["string","null"],"description":"Scope the goal to one track of the quarter's strategy (GET /api/v1/planning/plan lists them); null or left out: the whole quarter"}},"required":["params"]},"PlanningGoalCreate":{"type":"object","additionalProperties":false,"properties":{"periodId":{"type":"string","description":"The quarter (`period.id` of GET /api/v1/planning/quarters/{periodKey}); left out: the quarter holding most of the open windows"},"label":{"type":"string","maxLength":120},"params":{"$ref":"#/components/schemas/PlanningGoalParams"},"monthlyTargets":{"$ref":"#/components/schemas/PlanningMonthlyTargets"},"trackId":{"type":["string","null"]}},"required":["params"]},"PlanningGoalPatch":{"type":"object","additionalProperties":false,"description":"Send at least one field. A goal keeps its kind (409 KIND_CHANGE). New `params` without `monthlyTargets` go back to the derived pacing; `monthlyTargets: null` clears a hand-typed pacing; `trackId: null` scopes the goal to the whole quarter again.","properties":{"label":{"type":"string","maxLength":120},"params":{"$ref":"#/components/schemas/PlanningGoalParams"},"monthlyTargets":{"type":["array","null"],"minItems":1,"maxItems":3,"items":{"type":"object","properties":{"monthKey":{"type":"string"},"value":{"type":"number","minimum":0}},"required":["monthKey","value"]}},"trackId":{"type":["string","null"]}}},"PlanningGoal":{"type":"object","description":"One goal of the quarter, as the app's goal cards read it.","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["UNITS","CASH","SHAPE","RENEWAL"]},"label":{"type":"string"},"params":{"$ref":"#/components/schemas/PlanningGoalParams"},"monthlyTargets":{"type":"array","items":{"type":"object","properties":{"monthKey":{"type":"string"},"value":{"type":"number"}}}},"monthlyTargetsOverridden":{"type":"boolean","description":"The pacing was typed by hand rather than derived"},"quarterTarget":{"type":["number","null"],"description":"The months added up; null for a SHAPE goal"},"sortOrder":{"type":"integer"},"trackId":{"type":["string","null"]},"planVersion":{"type":"integer","description":"On a write: the plan version it made"}}},"PlanningStrategy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"objective":{"type":"string","enum":["PRESERVE_VALUE","BALANCED_RENEWAL","EV_MIGRATION","CASH_RELEASE"]},"constraints":{"type":"object","description":"The mandate's limits, as set"},"createdAt":{"type":"string","format":"date-time"}}},"PlanningStrategyCreate":{"type":"object","additionalProperties":false,"description":"The sell side's draft in one call: the mandate, and with `goals` the quarter's goals, as the app's \"Plan my quarter with Sequoia\" sets them one by one.","properties":{"name":{"type":"string","minLength":2,"maxLength":80},"objective":{"type":"string","enum":["PRESERVE_VALUE","BALANCED_RENEWAL","EV_MIGRATION","CASH_RELEASE"]},"constraints":{"type":"object","additionalProperties":false,"properties":{"cashReserve":{"type":"number","minimum":0,"default":0,"description":"USD"},"maxConcurrentListings":{"type":"integer","minimum":1,"maximum":50,"default":8},"sellingCostPct":{"type":"number","minimum":0,"maximum":0.2,"default":0.03},"minActiveFleet":{"type":"integer","minimum":0,"description":"The fleet keeps at least this many operating vehicles"},"prepLeadDays":{"type":"integer","minimum":0,"maximum":90,"description":"Days a vehicle needs in Sell before its window opens"},"mileageBandMiles":{"type":"integer","minimum":1000,"maximum":100000,"description":"Width of the mileage bands that sub-lot a lot"},"lotIncludesTrim":{"type":"boolean","description":"Trim splits a lot"}}},"benchAll":{"type":"boolean","default":false,"description":"Start every planning-owned vehicle on the bench instead of in operation"},"goals":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/PlanningGoalWrite"}}},"required":["name","objective"]},"PlanningStrategyCreated":{"type":"object","properties":{"strategyId":{"type":"string"},"planId":{"type":"string"},"poolSize":{"type":"integer","description":"Vehicles in the new plan"},"adopted":{"type":"integer","description":"Already in Sell: adopted as PROMOTED"},"benched":{"type":"integer"},"inOperation":{"type":"integer"},"goals":{"type":"array","description":"With `goals`: each goal as written (a PlanningGoal), or `{ error, code }` for one refused; the strategy stands either way","items":{"type":"object"}}}},"PlanningQuarter":{"type":"object","description":"A quarter of the sell plan, as the app's Plan tab reads it. Read `approvalDigest` to approve it.","properties":{"period":{"type":"object","properties":{"id":{"type":"string"},"periodKey":{"type":"string","example":"2026-Q4"},"label":{"type":"string","example":"Q4 2026"},"status":{"type":"string","enum":["DRAFT","APPROVED","CLOSED"]},"approvedPlanVersion":{"type":["integer","null"]},"approvedAt":{"type":["string","null"],"format":"date-time"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"}}},"monthKeys":{"type":"array","items":{"type":"string"}},"goals":{"type":"array","items":{"$ref":"#/components/schemas/PlanningGoal"}},"attainment":{"type":"array","items":{"type":"object"},"description":"One per goal, in the same order: target against scheduled, handed to Sell, listed, under offer and sold, per month"},"shape":{"type":"object","description":"The fleet's shape today (`now`) and at the quarter's end if everything scheduled sells (`projectedEnd`)"},"ladder":{"type":"array","items":{"type":"object"},"description":"What 50, 75, 80 and 100% sell-through of what is moving does to cash, carry, decay, shape and spillover"},"remedies":{"type":"array","items":{"type":"object"},"description":"Sequoia's proposals for the goals a 75% sell-through misses; never actions"},"lots":{"type":"array","items":{"type":"object"},"description":"Every lot with its per-month cells: target, scheduled, handed off, listed, sold"},"windows":{"type":"array","items":{"type":"object"},"description":"The sale windows with their month and the date to hand vehicles to Sell by (`handOffBy`, `rush` when past)"},"tracks":{"type":"array","items":{"type":"object"}},"prepLeadDays":{"type":"integer"},"sellingCostPct":{"type":"number"},"approvalDigest":{"type":["string","null"],"description":"Send it to POST .../approve: it binds the approval to this plan"},"deltaVsBaseline":{"type":["object","null"],"description":"How the live plan differs from the approved baseline; null before the first approval"},"truncated":{"type":"boolean"}}},"PlanningQuarterApprove":{"type":"object","additionalProperties":false,"properties":{"digest":{"type":"string","minLength":8,"description":"The quarter's `approvalDigest`"}},"required":["digest"]},"ScheduleProposalRequest":{"type":"object","additionalProperties":false,"description":"Name the quarter by `periodId` or `periodKey` (not both); neither: the quarter holding most of the open windows.","properties":{"periodId":{"type":"string"},"periodKey":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","example":"2026-Q4"}}},"ScheduleProposal":{"type":"object","description":"Sequoia's schedule for the quarter. Writes nothing. Send `periodId`, `digest` and `expiresAt` back to POST /api/v1/planning/schedule/apply.","properties":{"periodId":{"type":"string"},"periodKey":{"type":"string"},"planVersion":{"type":"integer"},"digest":{"type":"string","description":"Binds the apply to exactly this set"},"expiresAt":{"type":"string","format":"date-time","description":"24 hours from the proposal"},"lines":{"type":"array","items":{"type":"object","properties":{"vehicleId":{"type":"string"},"vin":{"type":"string"},"label":{"type":"string"},"lotKey":{"type":"string"},"lotLabel":{"type":"string"},"subLotKey":{"type":"string"},"windowId":{"type":"string"},"windowLabel":{"type":"string"},"monthKey":{"type":"string"},"rank":{"type":"integer"},"reasons":{"type":"array","items":{"type":"string"}},"source":{"type":"string","enum":["FM","SEQUOIA"],"description":"Whose lot target the line fills"},"state":{"type":"string","enum":["STAGED","CONDITIONAL"],"description":"CONDITIONAL: scheduled as waiting on an open payoff or arrivals blocker"},"netCash":{"type":["number","null"]},"plannedValue":{"type":["number","null"]},"handOffBy":{"type":"string","format":"date-time"},"rush":{"type":"boolean"}}}},"unscheduled":{"type":"array","items":{"type":"object","properties":{"lotKey":{"type":"string"},"subLotKey":{"type":"string"},"monthKey":{"type":"string"},"count":{"type":"integer"},"reason":{"type":"string"}}},"description":"What could not be placed, and why"},"proposedTargets":{"type":"array","items":{"type":"object","properties":{"lotKey":{"type":"string"},"subLotKey":{"type":"string"},"monthKey":{"type":"string"},"targetUnits":{"type":"integer"},"source":{"type":"string"}}},"description":"The lot targets Sequoia derived from the goals; written on apply, never over the planner's own"},"goalProjection":{"type":"array","items":{"type":"object"},"description":"Per goal and month: target, scheduled, projected cash"},"warnings":{"type":"array","items":{"type":"string"}},"summary":{"type":"object","properties":{"units":{"type":"integer"},"netCash":{"type":["number","null"]},"unvalued":{"type":"integer"},"rush":{"type":"integer"},"windows":{"type":"array","items":{"type":"object"}}}}}},"ScheduleApply":{"type":"object","additionalProperties":false,"properties":{"periodId":{"type":"string","description":"From the proposal"},"digest":{"type":"string","minLength":8,"description":"From the proposal"},"expiresAt":{"type":"string","minLength":8,"description":"From the proposal"},"vehicleIds":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string"},"description":"Apply only these lines; the rest stay proposed"},"reason":{"type":"string","maxLength":300}},"required":["periodId","digest","expiresAt"]},"BuyQuarter":{"type":"object","description":"A quarter of the dealer's buy plan, as the app's quarter bar reads it. A quarter nobody has set reads as an empty one (no goal, no budget, no approval) — never a 404. `unitsGoal` and `budget` are null when unset, and when stored as 0 (a goal of zero is no goal).","properties":{"periodKey":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","example":"2026-Q4"},"label":{"type":"string","example":"Q4 2026"},"start":{"type":"string","format":"date","description":"First day of the quarter"},"end":{"type":"string","format":"date","description":"Last day of the quarter"},"closed":{"type":"boolean","description":"The quarter's last day has passed (UTC): its plan no longer changes. A target needed in it, and its goal, answer 409 QUARTER_CLOSED; a purchase is still recorded."},"unitsGoal":{"type":["integer","null"],"minimum":0},"budget":{"type":["number","null"],"description":"USD, dollars"},"mandate":{"type":["string","null"],"enum":["RESTOCK_FAST","USUAL_MIX","MOST_UNITS","AHEAD_OF_SUPPLY",null],"description":"What Sequoia favors for the quarter. The API reads and sets it; Sequoia and Plan my quarter stay in the app."},"approval":{"type":["object","null"],"description":"null until the quarter is approved. The approved plan is the baseline the app's Review compares against; the plan stays live after it.","properties":{"approvedAt":{"type":"string","format":"date-time"},"changesSince":{"type":"array","items":{"type":"string"},"description":"What differs from the approved plan, one plain-words line per difference (\"Budget $600,000 → $650,000\", \"Added Chevy Malibu\"). Free text for people: don't parse it."}}},"progress":{"type":"object","description":"The purchases made in the quarter (by purchase date), counted as the app's header and Budget card count them.","properties":{"bought":{"type":"integer","description":"Purchases that are done: the closing completed, or the purchase was recorded by hand"},"inClosing":{"type":"integer","description":"Purchases whose closing is in progress"},"spent":{"type":"number","description":"USD on the purchases that are done, in the plan and outside it: the Buy plan page's \"spent\""},"inClosingAmount":{"type":"number","description":"USD on the closings in progress (not spent yet)"},"spentInPlan":{"type":"number","description":"The part of `spent` a target claimed. Since 1.9.0"},"spentOutsidePlan":{"type":"number","description":"The part of `spent` no target claimed. Since 1.9.0"}},"required":["bought","inClosing","spent","inClosingAmount","spentInPlan","spentOutsidePlan"]},"digest":{"type":"string","pattern":"^[0-9a-f]{16}$","description":"Binds an approval to the plan you read: send it to `POST .../approve`. It changes when the goal, the budget, the mandate or a target of the quarter changes."}},"required":["periodKey","label","start","end","closed","unitsGoal","budget","mandate","approval","progress","digest"]},"BuyQuarterWrite":{"type":"object","description":"Set a quarter's goal, budget and mandate. Send `unitsGoal` and `budget` every time (null clears one) — a forgotten one is a 422, never a silently cleared goal. Leave `mandate` out to keep the quarter's mandate; null clears it. The API carries no note: the dealer's note on the quarter is never touched.","properties":{"unitsGoal":{"type":["integer","null"],"minimum":0,"maximum":100000},"budget":{"type":["number","null"],"minimum":0,"maximum":1000000000,"description":"USD, dollars"},"mandate":{"type":["string","null"],"enum":["RESTOCK_FAST","USUAL_MIX","MOST_UNITS","AHEAD_OF_SUPPLY",null]}},"required":["unitsGoal","budget"]},"BuyApprove":{"type":"object","properties":{"digest":{"type":"string","pattern":"^[0-9a-f]{16}$","description":"The `digest` of the quarter you read"}},"required":["digest"]},"BuyDraftRequest":{"type":"object","additionalProperties":false,"properties":{"mandate":{"type":"string","enum":["RESTOCK_FAST","USUAL_MIX","MOST_UNITS","AHEAD_OF_SUPPLY"]},"periodKey":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","example":"2026-Q4"}},"required":["mandate","periodKey"]},"BuyDraftSpec":{"type":"object","description":"What a drafted target buys: one make and model, or a vehicle class.","properties":{"make":{"type":["string","null"]},"model":{"type":["string","null"]},"trims":{"type":"array","items":{"type":"string"}},"planningClass":{"type":["string","null"],"enum":["CAR","SUV","TRUCK","VAN",null]},"bodyClasses":{"type":"array","items":{"type":"string"}},"fuelTypes":{"type":"array","items":{"type":"string"}},"conditions":{"type":"array","items":{"type":"string","enum":["EXCELLENT","GOOD","FAIR","POOR"]}},"yearMin":{"type":["integer","null"]},"yearMax":{"type":["integer","null"]},"mileageMin":{"type":["integer","null"]},"mileageMax":{"type":["integer","null"]},"states":{"type":"array","items":{"type":"string"}}}},"BuyDraftTarget":{"type":"object","properties":{"key":{"type":"string","description":"The draft's own key for the target (e.g. \"TOYOTA|RAV4\"); send it back"},"label":{"type":"string","maxLength":120},"spec":{"$ref":"#/components/schemas/BuyDraftSpec"},"quantity":{"type":"integer","minimum":1,"maximum":10000},"needBy":{"type":"string","format":"date","description":"YYYY-MM-DD"},"targetUnitPrice":{"type":["number","null"],"description":"USD"},"maxUnitPrice":{"type":["number","null"],"description":"USD"},"track":{"type":"string","enum":["AGGRESSIVE","BALANCED","CONSERVATIVE"]},"why":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"Sequoia's reasons, in plain words"},"origin":{"type":"string","enum":["SEQUOIA","DEALER"],"default":"SEQUOIA","description":"On apply: who made the target. DEALER: the dealer's own, created as a manual target"},"priority":{"type":"integer","enum":[0,1]},"needFrom":{"type":["string","null"],"format":"date","description":"YYYY-MM-DD"},"note":{"type":["string","null"],"maxLength":2000}},"required":["key","spec","quantity","needBy"]},"BuyDraft":{"type":"object","description":"Sequoia's starting plan for the quarter, as the app's \"Plan my quarter\" wizard shows it. Writes nothing.","properties":{"unitsGoal":{"type":"integer"},"budget":{"type":"number","description":"USD"},"basis":{"type":"string","enum":["HISTORY_AND_MARKET","MARKET_ONLY"],"description":"MARKET_ONLY: the dealer has no purchase history yet"},"words":{"type":"string","description":"What the draft rests on, in plain words"},"targets":{"type":"array","items":{"$ref":"#/components/schemas/BuyDraftTarget"}}}},"BuyDraftApply":{"type":"object","description":"Keep a draft (all of it, or the targets you choose, changed or not) and, with `approve: true`, approve the quarter in the same step.","properties":{"periodKey":{"type":"string","pattern":"^\\d{4}-Q[1-4]$"},"mandate":{"type":"string","enum":["RESTOCK_FAST","USUAL_MIX","MOST_UNITS","AHEAD_OF_SUPPLY"]},"unitsGoal":{"type":["integer","null"],"minimum":0,"maximum":100000},"budget":{"type":["number","null"],"minimum":0,"maximum":1000000000,"description":"USD"},"states":{"type":"array","maxItems":60,"items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"description":"The plan's buying markets; left out: the plan keeps its own"},"notifyMatches":{"type":"boolean"},"digest":{"type":"boolean"},"approve":{"type":"boolean","description":"Also approve the quarter. A person's: an agent's token is refused (403 PEOPLE_ONLY)"},"targets":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/BuyDraftTarget"}}},"required":["periodKey","mandate","unitsGoal","budget","targets"]},"BuyDraftKept":{"type":"object","properties":{"periodKey":{"type":"string"},"approved":{"type":"boolean"},"decisions":{"type":"integer","description":"Sequoia's targets kept (each leaves an accepted decision); the dealer's own leave none"},"targets":{"type":"array","items":{"$ref":"#/components/schemas/BuyTarget"},"description":"The targets made, as GET /api/v1/buy-planning/targets reads them"}}},"BuyTargetWrite":{"type":"object","description":"A target: one make and model (`make` and `model`), or a vehicle class (`planningClass` alone), with the quantity and the week it is needed by. The app's own body — a target read can be edited and sent back (the read-only fields are ignored). `needBy` and `needFrom` snap to the plan's weeks. A target that names no `track` takes the plan's default track. `label` left out is made from the spec.","properties":{"label":{"type":"string","maxLength":120},"make":{"type":["string","null"],"maxLength":40},"model":{"type":["string","null"],"maxLength":60},"trims":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":20},"planningClass":{"type":["string","null"],"enum":["CAR","SUV","TRUCK","VAN",null]},"bodyClasses":{"type":"array","items":{"type":"string"},"maxItems":20},"fuelTypes":{"type":"array","items":{"type":"string"},"maxItems":20},"conditions":{"type":"array","items":{"type":"string","enum":["EXCELLENT","GOOD","FAIR","POOR"]},"maxItems":4},"yearMin":{"type":["integer","null"],"minimum":1980,"maximum":2100},"yearMax":{"type":["integer","null"],"minimum":1980,"maximum":2100},"mileageMin":{"type":["integer","null"],"minimum":0},"mileageMax":{"type":["integer","null"],"minimum":0},"states":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"maxItems":60,"description":"The markets this target buys in (two-letter states). Empty: the plan's markets."},"quantity":{"type":"integer","minimum":1,"maximum":10000},"needFrom":{"type":["string","null"],"format":"date","description":"YYYY-MM-DD"},"needBy":{"type":"string","format":"date","description":"YYYY-MM-DD. The target counts in the quarter of this week's Thursday. A target needed in a quarter that is over answers 409 QUARTER_CLOSED."},"targetUnitPrice":{"type":["number","null"],"minimum":0,"maximum":10000000,"description":"USD"},"maxUnitPrice":{"type":["number","null"],"minimum":0,"maximum":10000000,"description":"USD; at or above the target price"},"priority":{"type":"integer","enum":[0,1],"description":"0 normal, 1 high (immediate match notices)"},"note":{"type":["string","null"],"maxLength":2000},"track":{"type":"string","enum":["AGGRESSIVE","BALANCED","CONSERVATIVE"],"description":"How hard the target hunts: matches from 80% / 90% / exact only."}},"required":["quantity","needBy"]},"BuyTargetStatus":{"type":"object","additionalProperties":false,"description":"Pause, reopen or close a target. The dealer's decision, stored as given; what a person reads (Filled, Ended) is `displayStatus`.","properties":{"status":{"type":"string","enum":["OPEN","PAUSED","CLOSED"]}},"required":["status"]},"BuyTarget":{"type":"object","description":"A target. The spec and plan fields carry the names the write body uses. `status` is the dealer's stored decision; `displayStatus` is what a person reads, derived once for every surface: FILLED when nothing remains to buy (whatever the stored status), ENDED when its quarter is over with units still short, CLOSED for a target the dealer closed, otherwise the stored status.","properties":{"id":{"type":"string"},"label":{"type":"string"},"status":{"type":"string","enum":["OPEN","PAUSED","CLOSED"]},"displayStatus":{"type":"string","enum":["OPEN","FILLED","PAUSED","CLOSED","ENDED"]},"source":{"type":"string","description":"How the target was made: MANUAL for one added by hand or through the API"},"track":{"type":"string","enum":["AGGRESSIVE","BALANCED","CONSERVATIVE"]},"priority":{"type":"integer","enum":[0,1]},"make":{"type":["string","null"]},"model":{"type":["string","null"]},"trims":{"type":"array","items":{"type":"string"}},"planningClass":{"type":["string","null"]},"bodyClasses":{"type":"array","items":{"type":"string"}},"fuelTypes":{"type":"array","items":{"type":"string"}},"conditions":{"type":"array","items":{"type":"string"}},"yearMin":{"type":["integer","null"]},"yearMax":{"type":["integer","null"]},"mileageMin":{"type":["integer","null"]},"mileageMax":{"type":["integer","null"]},"states":{"type":"array","items":{"type":"string"}},"quantity":{"type":"integer"},"needFrom":{"type":["string","null"],"format":"date","description":"YYYY-MM-DD"},"needBy":{"type":"string","format":"date","description":"YYYY-MM-DD"},"needByWeek":{"type":"string","example":"W48","description":"The needed-by week"},"periodKey":{"type":["string","null"],"description":"The quarter the target counts in — the quarter of its needed-by week's Thursday (the plan's own rule)","example":"2026-Q4"},"targetUnitPrice":{"type":["number","null"]},"maxUnitPrice":{"type":["number","null"]},"bought":{"type":"integer","description":"Purchases counting toward it that are done"},"inClosing":{"type":"integer","description":"Purchases counting toward it with a closing in progress"},"remaining":{"type":"integer","description":"Units still to buy; never below zero"},"note":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"links":{"$ref":"#/components/schemas/AppLinks"}},"required":["id","label","status","displayStatus","track","quantity","needBy","needByWeek","periodKey","bought","inClosing","remaining"]},"BuyTargetList":{"type":"object","properties":{"periodKey":{"type":"string","description":"The quarter asked for, or `all`"},"items":{"type":"array","items":{"$ref":"#/components/schemas/BuyTarget"}},"totalCount":{"type":"integer"}},"required":["periodKey","items","totalCount"]},"BuyMatch":{"type":"object","description":"A live listing that fits the target at its track's floor, with the listing's PUBLIC facts only. Never a seller's name, id, floor, thresholds or limits, never the staff deal fit, and no VIN.","properties":{"vehicleId":{"type":"string"},"url":{"type":"string","format":"uri","description":"The listing's public page on the Marketplace"},"year":{"type":["integer","null"]},"make":{"type":["string","null"]},"model":{"type":["string","null"]},"trim":{"type":["string","null"]},"mileage":{"type":["integer","null"]},"state":{"type":["string","null"],"description":"Where the vehicle is"},"ask":{"type":["number","null"],"description":"The public asking price, USD; null when the listing shows none"},"isNew":{"type":"boolean","description":"First seen in the last three days"},"score":{"type":"integer","minimum":0,"maximum":100},"kind":{"type":"string","enum":["EXACT","NEAR"],"description":"EXACT is a score of 100"},"misses":{"type":"array","items":{"type":"string"},"description":"What a near match is not, in plain words (\"Trim LE, not XLE\"). Free text for people: don't parse it."}},"required":["vehicleId","url","score","kind","misses"]},"BuyMatchList":{"type":"object","description":"The target's live matches in the app's order: exact first, then by score; within a score new first, then by public ask (an unpriced listing last).","properties":{"targetId":{"type":"string"},"track":{"type":"string","enum":["AGGRESSIVE","BALANCED","CONSERVATIVE"]},"totalCount":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/BuyMatch"}}},"required":["targetId","track","totalCount","items"]},"BuyMatchedEventBody":{"type":"object","description":"The `body` of a BUY.TARGET.MATCHED envelope (resource `buy`; `href` = /api/v1/buy-planning/targets/{id}/matches): a listing fits an open target for the first time. `match` is exactly the BuyMatch that `GET /api/v1/buy-planning/targets/{id}/matches` returns for it (so `isNew` is true), with the listing's public facts only — never a seller, a floor, a limit, a VIN or the staff deal fit. One event per target and vehicle.","properties":{"target":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"periodKey":{"type":["string","null"],"description":"The quarter the target counts in","example":"2026-Q4"}},"required":["id","label","periodKey"]},"match":{"$ref":"#/components/schemas/BuyMatch"}},"required":["target","match"]},"BuyFilledEventBody":{"type":"object","description":"The `body` of a BUY.TARGET.FILLED envelope (resource `buy`; `href` = /api/v1/buy-planning/targets/{id}): the target has nothing left to buy (`remaining` went from above zero to zero; `displayStatus` is FILLED). The target is the BuyTarget that `GET /api/v1/buy-planning/targets/{id}` returns, with its `bought` and `inClosing` counts.","properties":{"target":{"$ref":"#/components/schemas/BuyTarget"}},"required":["target"]},"BuyEndedEventBody":{"type":"object","description":"The `body` of a BUY.TARGET.ENDED envelope (resource `buy`; `href` = /api/v1/buy-planning/targets/{id}): the target's quarter closed with units still short (`displayStatus` is ENDED). `shortfall` is the units never bought (the target's `remaining`) and `bought` the units that were.","properties":{"target":{"$ref":"#/components/schemas/BuyTarget"},"shortfall":{"type":"integer","minimum":1},"bought":{"type":"integer","minimum":0}},"required":["target","shortfall","bought"]},"BuyDismiss":{"type":"object","properties":{"undo":{"type":"boolean","default":false,"description":"true brings a hidden match back"}}},"BuyPurchaseWrite":{"type":"object","description":"A purchase made outside Cypress, so the plan's progress is complete. Its price stays with the dealer. Never refused for a closed quarter.","properties":{"targetId":{"type":["string","null"],"description":"The target it counts toward, or null for a purchase outside the plan"},"purchasedAt":{"type":"string","format":"date","description":"YYYY-MM-DD, up to tomorrow (UTC); not in the future"},"unitPrice":{"type":["number","null"],"minimum":0,"maximum":10000000,"description":"USD"},"description":{"type":"object","description":"What was bought","properties":{"year":{"type":"integer","minimum":1980,"maximum":2100},"make":{"type":"string","maxLength":40},"model":{"type":"string","maxLength":60},"vin":{"type":"string","maxLength":17},"mileage":{"type":"integer","minimum":0,"maximum":1000000}}},"note":{"type":["string","null"],"maxLength":1000}},"required":["targetId","purchasedAt","unitPrice","description"]},"BuyPurchaseReassign":{"type":"object","properties":{"targetId":{"type":["string","null"],"description":"The target to count it toward, or null for none. The attribution rule never moves it back."}},"required":["targetId"]},"BuyPurchase":{"type":"object","description":"A purchase, as the app's Progress tab lists it.","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["COMMITTED","FILLED","CANCELLED"],"description":"Derived from the closing every time, never stored. COMMITTED: a closing in progress (in closing). FILLED: bought — the closing completed, or the purchase was recorded by hand. CANCELLED: the closing did not complete; it counts for nothing."},"source":{"type":"string","enum":["CYPRESS","RECORDED"],"description":"CYPRESS: it came from a closing on Cypress. RECORDED: the dealer recorded it (through the app or this API)."},"targetId":{"type":["string","null"],"description":"null for a purchase outside the plan"},"targetLabel":{"type":["string","null"]},"unitPrice":{"type":["number","null"],"description":"USD"},"purchasedAt":{"type":"string","format":"date-time"},"periodKey":{"type":"string","description":"The quarter it counts in, by its date","example":"2026-Q4"},"vehicle":{"type":"object","description":"The vehicle as the app shows it","properties":{"id":{"type":["string","null"],"description":"Its Cypress id when it was bought on Cypress; null for one bought elsewhere"},"label":{"type":"string","example":"2022 Toyota RAV4 XLE"}},"required":["id","label"]},"note":{"type":["string","null"],"description":"The dealer's own note on a recorded purchase"}},"required":["id","state","source","targetId","unitPrice","purchasedAt","periodKey","vehicle"]},"BuyPurchaseList":{"type":"object","properties":{"periodKey":{"type":"string","description":"The quarter asked for, or `all`"},"items":{"type":"array","items":{"$ref":"#/components/schemas/BuyPurchase"}},"totalCount":{"type":"integer"}},"required":["periodKey","items","totalCount"]}}},"webhooks":{"event":{"post":{"tags":["Webhooks & deliveries"],"summary":"Event delivery to your registered callback","description":"Cypress POSTs one envelope per event to every matching subscription. Events: VEHICLES.CREATED/UPDATED, VEHICLES.DISPOSITION.STAGED/RESOLVED, LISTINGS.CREATED/UPDATED/ACTIVATED/PAUSED/RESUMED/CANCELLED/NOSALE/PURCHASED, OFFERS.CREATED/ACCEPTED/DECLINED/COUNTERED/EXPIRED, CLOSING.STARTED, CLOSING.STEP.COMPLETED (every closing step, funds/gate-pass/title included), CLOSING.DOCUMENT.GENERATED and CLOSING.DOCUMENT.SIGNED (template documents carry the full data-sheet JSON they were rendered from), CLOSING.PAYMENT.RECEIVED, CLOSING.CANCELLED, CLOSING.COMPLETED, PING.TEST (MANHEIM dialect: VEHICLES→UNITS, LISTINGS→OFFERINGS). OFFERS.ACCEPTED is sent once for every accepted offer: the seller (or Cypress for them) accepting, a pricing rule or Buy Now (with `autoProcessed: true`), and, since 1.4.0, a buyer accepting the seller's counter and an approved price change accepting an offer that now qualifies. Planning (1.3.0) — PLAN.VEHICLE.ENTERED (benched as a candidate), PLAN.VEHICLE.SCHEDULED (into a sale window), PLAN.WINDOW.DUE (its window's hand-off date arrived), PLAN.WINDOW.MISSED, PLAN.BLOCKER.ADDED, PLAN.BLOCKER.RESOLVED, PLAN.HANDED_TO_SELL (the cohort confirm): opt-in — delivered only to a CYPRESS-dialect subscription that lists the event in eventTypes (never to an unfiltered \"all events\" subscription, never to a MANHEIM one); no new PLAN.* event is sent once the organization's Planning is switched off (deliveries already fanned out still deliver and retry). Subscribing to one needs planning:read. VEHICLES.* about planning stock (a vehicle in OPERATION or PLANNING — a planning push, a PATCH, a departure staged and resolved) follow the same rules: only a CYPRESS-dialect subscription that lists the event, only while the organization has Planning. When a cohort confirm hands vehicles to Sell, each also sends a plain VEHICLES.UPDATED, delivered like any Sell event. Envelope resource `plan`, body = PlanEventBody, href = /api/v1/planning/vehicles/{vehicleId}. Buy planning (1.4.0) — BUY.TARGET.MATCHED (a live listing fits an open target for the first time), BUY.TARGET.FILLED (a target has nothing left to buy), BUY.TARGET.ENDED (a target's quarter closed with units short): opt-in on the same terms as PLAN.* — only to a CYPRESS-dialect subscription that lists the event, never to an unfiltered or MANHEIM one, and only while the organization's Buy planning is on; subscribing needs buy-planning:read. Each is delivered to an endpoint once, however many times its cause is noticed. Envelope resource `buy`, body = BuyMatchedEventBody, BuyFilledEventBody or BuyEndedEventBody (the dealer's own target and a listing's public facts, built when the event happened), href = /api/v1/buy-planning/targets/{id} (…/matches for BUY.TARGET.MATCHED). Tasks (1.5.0) — TASK.CREATED (a task was added to your organization's book), TASK.ASSIGNED (a task was handed to someone other than whoever acted: a person giving one to themselves is not a hand-off, an automation's assignment always is; at creation or on a change of assignee), TASK.DUE (its due time arrived; delivered to an endpoint once per task and due time), TASK.COMPLETED, TASK.CANCELLED: opt-in — only to a CYPRESS-dialect subscription that lists the event, never to an unfiltered or MANHEIM one; subscribing needs tasks:read. No product switch: every organization has tasks. Envelope resource `tasks`, body = Task as it is at delivery time, plus `assigneeUserId` on TASK.ASSIGNED (who it was given to then) and `dueDate` on TASK.DUE, href = /api/v1/tasks/{id}; a task that is gone answers `{ id, deleted: true }`. A subscription filtered by `entityIds` gets the events of the tasks about those records (a contact, business, deal, vehicle, sell goal or buy target id) and, since 1.9.0, of the tasks made from a conversation (its Huddle room id; the body's `links.conversation` names the room and the message). Notifications (1.5.0) — NOTIFICATION.CREATED: a notification was sent to one of your members, a person or an agent (an agent gets notifications only this way: nothing is emailed to it or put in an inbox). Opt-in on the TASK.* terms; subscribing needs notifications:read. It is sent in the recipient's organization only: a notification to your buyer about another company's car is yours, and that company never hears of it. Envelope resource `notifications`, body = Notification as it was sent, href = /api/v1/notifications/{id}; the vehicle it is about, if any, rides in relatedResources. A subscription whose `entityIds` lists user ids gets those people's notifications only. Closing deadlines (1.5.0) — CLOSING.STEP.DUE (an open step's deadline is less than 12 hours away) and CLOSING.STEP.OVERDUE (it has passed): opt-in on the TASK.* terms; subscribing needs closing:read. Unlike the other CLOSING.* events (the seller's, to every subscriber), these go to BOTH sides of the trade, each in its own organization; the commission step is the seller's alone. Each is told once per step, side and deadline (a moved deadline is told again). Envelope resource `closing`, href = /api/v1/closings/{id}, body = { closingId, side, vehicleId, step: { key, number, label, deadlineOwner, turn, yourTurn, dueDate } }; the buyer's copy carries no vehicle resource (the vehicle API is the seller's). CLOSING.DOCUMENT.REQUESTED (1.5.0): someone asked for a document a requirement still lacks (POST /api/v1/closings/{id}/document-requests); on the same terms, to both sides, body = { closingId, side, vehicleId, requirement: { id, step, slot, name }, askedOf, requestedBy, yourDocument }. Marketing (1.5.0) — CAMPAIGN.SENT (a real send went out; body { campaignId, sendId, trigger, asked, scheduledFor }; the results are read from GET /api/v1/campaigns/{id}/sends), CAMPAIGN.PAUSED (body { campaignId, reason MANUAL or NO_AVAILABLE_VEHICLES, pausedAt }), CAMPAIGN.INTEREST (a person the campaign mailed viewed, saved or made an offer on one of YOUR cars, once per person, car and kind; body { campaignId, sendId, vehicleId, interest, contactId }, contactId only when the person is in your own CRM book), CONTACT.UNSUBSCRIBED (a contact of your own book asked to stop your mail; body { contactId, email, campaignId, unsubscribedAt }; someone outside your book is never named). Opt-in on the TASK.* terms; subscribing needs marketing:read. Sent to the campaign's owner only; a test send never counts. Envelope resource `campaigns` (href /api/v1/campaigns/{id}) or `contacts` (href /api/v1/contacts/{id}). Automations (1.5.0) — AUTOMATION.RUN.COMPLETED (a run of one of YOUR automations finished: status SUCCESS, PARTIAL — some steps refused or failed, see problems — or DRY_RUN, a dry run you asked the API for) and AUTOMATION.RUN.FAILED (it stopped on an error); body { runId, automationId, automationName, version, status, dryRun, startedBy, subject, vehiclesEvaluated, vehiclesActioned, problems, durationMs, startedAt, completedAt }, envelope resource `automation-runs`, href /api/v1/automations/runs/{id} (its steps at /steps), once per run. AUTOMATION.PUBLISHED (Cypress published a draft you submitted; body { automationId, automationName, version, publishedAt }) and AUTOMATION.SENT_BACK (Cypress sent it back; body { automationId, automationName, version, note, sentBackAt }), envelope resource `automations`, href /api/v1/automations/{id}. Opt-in on the TASK.* terms; subscribing needs automations:read, and nothing is sent while your Automations product is off. Cypress's own automations never send these. CRM (1.5.0) — CONTACT.CREATED / BUSINESS.CREATED / DEAL.CREATED (a record entered your own book: typed, pushed, imported or opened from an offer), CONTACT.UPDATED / BUSINESS.UPDATED / DEAL.UPDATED (with `changedFields`), DEAL.STAGE_CHANGED (with fromStage, toStage and `automatic`, true when its offers moved it; a stage move alone sends only this), envelope resources `contacts`, `businesses`, `deals`, body = the record as GET /api/v1/{contacts|businesses|deals}/{id} returns it, read at delivery. OUTREACH.LOGGED (an interaction going out: an email sent through Cypress, a call logged) and OUTREACH.REPLIED (one coming in, logged by someone: Cypress does not receive replies to its emails), envelope resource `interactions`, body = the interaction as the record's interactions read returns it. Opt-in on the TASK.* terms; subscribing needs crm:read. Cypress's own book tells no one. Plans (1.5.0) — PLAN.GOAL.SET (a Sell goal added or changed; body { change, goal }, envelope resource `planning-goals`) and PLAN.QUARTER.APPROVED (body { quarter: { periodKey, approvedAt, approvedBy, approvedPlanVersion, goals, lotTargets, scheduled } }, resource `planning-quarters`, once per approved version), on the PLAN.* terms; BUY.TARGET.CREATED (body { target }), BUY.TARGET.DUE (an open target's needed-by day came with units still to buy; body { target, remaining }, once per target and day) and BUY.QUARTER.APPROVED (body { quarter: { periodKey, approvedAt, approvedBy, unitsGoal, budget, targets } }, resource `buy-quarters`), on the BUY.* terms. A goal and a quarter have no page of their own: no links.app. Insights (1.5.0) — INSIGHT.CREATED: Sequoia put a recommendation in front of you, new or back after its answer ran out; body { side, about, insight } (insight as GET /api/v1/insights shows it), envelope resource `insights`. Opt-in on the TASK.* terms; subscribing needs insights:read. Every action heard (1.5.0) — each body carries `change` and `source` (app, api, csv, automation, stripe), and names what changed, never a secret: ORGANIZATION.UPDATED (change PROFILE, DELEGATION, STATUS, PRODUCTS, PROFILES, CHANNELS, SETTINGS, DOCUMENT_UPLOADED, DOCUMENT_REMOVED, DOCUMENT_REVIEWED, SELLER_TERMS, STOREFRONT, ACCOUNT_RULES (1.9.0: the account's features and limits, set by Cypress), DEALER_REQUEST (1.9.0: an individual's request to become a dealer, with its status); resource `organization`), MEMBER.UPDATED (ADDED, ROLE_CHANGED, REMOVED, RESTORED, UPDATED; body { userId, role, previousRole, email }), BANKING.UPDATED (ADDED, CHANGED, ARCHIVED; body { resource BANK_ACCOUNT or LENDER, id, changedFields }, never a number), BILLING.UPDATED (INVOICE_PAID, PAYMENT_RECEIVED, CREDIT_NOTE_ISSUED, CREDIT_APPLIED, CREDIT_GRANTED, CREDIT_WITHDRAWN; body { invoiceId or creditNoteId, amountCents, currency, method, balanceAfterCents }), CLOSING.UPDATED (to both sides with `side`, the commission step and incidents that are not the buyer's to the seller alone; change STARTED, STEP_COMPLETED, DEAL_SETUP_UPDATED, DEAL_SETUP_CONFIRMED, DOCUMENT_UPLOADED, DOCUMENT_REMOVED, DOCUMENT_ACCEPTED, DOCUMENT_REJECTED, DOCUMENT_GENERATED, DOCUMENT_SIGNED, SENT_FOR_SIGNATURE, PAYMENT_RECEIVED, INCIDENT_REPORTED, INCIDENT_UPDATED, ROLLED_BACK, CANCELLED, COMPLETED; since 1.9.0 every path that completes a step tells STEP_COMPLETED (the last signature, the commission paid, the title accepted, an off-platform attestation, with `offPlatform`), a document signed in ink tells DOCUMENT_SIGNED, a new incident message tells INCIDENT_UPDATED with `messageId`, ROLLED_BACK names `rolledBackTo`, and DEAL_SETUP_UPDATED names `reopenSuggestedTo` when issued paper went wrong), MARKETPLACE.OFFER.UPDATED (to the buyer: ACCEPTED, DECLINED, COUNTERED, EXPIRED; body { offerId, vehicleId, amount, counterAmount, reason } with a reason only when the app shows it to a buyer; resource `offers-made`), CONTACT.DELETED / BUSINESS.DELETED / DEAL.DELETED (body { deleted: true }), CRM.IMPORT.COMPLETED and VEHICLES.IMPORT.COMPLETED (body { batchId, status, counts }), CAMPAIGN.ACTIVATED, PROMOTION.UPDATED (CREATED, EDITED, PUBLISHED, PAUSED, ARCHIVED, DELETED), PLAN.VEHICLE.UPDATED (UNSCHEDULED, PARKED, UNPARKED, TO_OPERATION, TRACK_CHANGED, DEMOTED), PLAN.STRATEGY.UPDATED (SET, ENDED), BUY.TARGET.UPDATED (PAUSED, REOPENED, CLOSED, EDITED, REMOVED; body { change, changedFields, target }), BUY.QUARTER.SET (body { quarter: { periodKey, unitsGoal, budget } }) and INSIGHT.ANSWERED (body { answer, answeredBy, side, about, insight }). Opt-in, CYPRESS dialect only, each on the read scope of its area (PLAN.* and BUY.* on their product switches). Share links (1.9.0) — MARKETPLACE.SHARE.RECEIVED: a seller addressed a share link to your organization (POST /api/v1/vehicles/{id}/share-links with `recipientOrgId`); body { shareLink: { id, token, label, url, expiresAt }, vehicle: { id, year, make, model, trim, mileage, askingPrice, state }, seller: { name }, source }, resource `share-links`, href = /api/v1/marketplace/share-links/{token}. Once per link; opt-in on the TASK.* terms, subscribing needs marketplace:read.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventEnvelope"}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else is retried"}}}}},"paths":{"/api/v1/sandbox/reset":{"post":{"tags":["Cypress API v1"],"summary":"Reset your sandbox: its data as it was made, under the same key","responses":{"200":{"description":"Reset; or, with ?dryRun=true, what a reset would put back","content":{"application/json":{"schema":{"type":"object","properties":{"reset":{"type":"boolean"},"dryRun":{"type":"boolean"},"now":{"type":"object","description":"With ?dryRun=true: what the sandbox holds now","additionalProperties":{"type":"integer"}},"counts":{"type":"object","description":"What the sandbox holds after the reset (or would)","additionalProperties":{"type":"integer"}},"keeps":{"type":"array","items":{"type":"string"},"description":"What a reset leaves as it is"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"KEY_ENVIRONMENT: a live organization is never reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"CONFLICT: a demo organization that is not a sandbox (ask your Cypress contact)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"One reset a minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Since 1.5.0. Any credential acting in a sandbox, an agent's included: the sandbox's vehicles, offers, closings, CRM book, plans and their changes go back to the world it was made with. The credential keeps working: a reset keeps the sandbox's keys, its connected apps and its members. A Cypress Manager's reset in Settings issues a new key instead, for a key that leaked. Nothing is sent to anyone. MCP: reset_sandbox (Cypress Operate, on a sandbox only).","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}]}},"/api/v1/organization":{"get":{"tags":["Cypress API v1"],"summary":"What this organization and key may do — with a reason for every refusal","responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationProfile"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Answers whatever the organization's status, and needs no scope — a key for an organization still onboarding can call this to learn why everything else is refused."}},"/api/v1/vehicles":{"post":{"tags":["Cypress API v1"],"summary":"Create a vehicle (draft-first; ?mode=upsert replaces by VIN)","responses":{"200":{"description":"Updated (?mode=upsert or ?mode=merge on an existing VIN) — same shape as 201, including `warnings`, `code` and `planningStep` on a planning push; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"vehicle":{"$ref":"#/components/schemas/VehicleRead"},"warnings":{"type":"array","items":{"type":"string"}},"code":{"type":"string","enum":["PLAN_BUSY","NO_PLAN"]},"planningStep":{"type":"object","properties":{"error":{"type":"string"}}}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"201":{"description":"Created (Location header set). A planning push whose plan step did not land still answers 201 (200 on an upsert): the vehicle is in OPERATION, `planningStep.error` says why, `code` is PLAN_BUSY (with Retry-After) or NO_PLAN when one applies — finish with POST /api/v1/planning/moves (to: BENCH) or re-push with ?mode=upsert.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Planning push only, when the plan was busy"}},"content":{"application/json":{"schema":{"type":"object","properties":{"vehicle":{"$ref":"#/components/schemas/VehicleRead"},"listing":{"$ref":"#/components/schemas/ListingRead"},"launched":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"},"description":"Planning push: ownership warnings (saved), and what the push did not change"},"code":{"type":"string","enum":["PLAN_BUSY","NO_PLAN"],"description":"Planning push: why the plan step did not land"},"planningStep":{"type":"object","properties":{"error":{"type":"string"}},"description":"Planning push: present only when the plan step did not land"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code EXTERNAL_ID_TAKEN when an external id already names another vehicle — or VIN already exists in your inventory — or code PLANNING_STOCK when a Sell push names a vehicle in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning) — or code LIFE_STAGE_READ_ONLY when an upsert would move a vehicle across the Planning/Sell line","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed (field named in error) — also an invalid `ownership` block on a planning push (details.errors lists each), or an embedded `listing` on a planning push (a listing needs Sell stock)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"An embedded `listing` needs the `listings` scope too — 403 SCOPE_MISSING (naming `listings`) when the key holds only `vehicles`, and nothing is created.\n\n**Planning push (1.3.0)** — `lifeStage: OPERATION` or `PLANNING` needs `planning:write` (and `vehicles`) on an organization with Planning. The vehicle lands as planning stock (in service, or benched as a candidate); the optional `ownership` block is validated before anything is created. No valuation is bought — the daily sweep values new planning stock. An upsert with `PLANNING` benches a vehicle that is in OPERATION; an upsert with `OPERATION` never takes a vehicle off the bench (a warning says to use POST /api/v1/planning/moves with `to: OPERATION`). Planning pushes follow this API's field rules.","parameters":[{"name":"mode","in":"query","schema":{"type":"string","enum":["upsert","merge"]},"description":"`upsert` replaces a VIN you already hold with what you send: every field left out is cleared. `merge` (since 1.8.0) changes only the fields you send, as PATCH: photos stay unless you send `images`, external ids and the inspection report stay unless sent; the mode for a feed that carries a few columns. A new VIN is created either way. Omitted: an existing VIN answers 409."},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleWrite"}}}}},"get":{"tags":["Cypress API v1"],"summary":"List your vehicles (paginated)","responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/VehicleRead"}},"totalCount":{"type":"integer"},"nextHref":{"type":"string"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"lifeStage","in":"query","schema":{"type":"string"},"description":"Comma list of OPERATION, PLANNING, REMARKETING, POST_SALE, RETIRED. Default: REMARKETING,POST_SALE,RETIRED. OPERATION/PLANNING need the planning:read scope and Planning on (403 SCOPE_MISSING / PLANNING_NOT_ENABLED)."},{"name":"externalId","in":"query","schema":{"type":"string"},"description":"<source>:<id> — the vehicle your system calls by that id (zero or one item). A vehicle in Planning needs planning:read to be found."},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time"},"description":"Changed at or after this time; the list then answers the newest change first. A sync reads the event feed (GET /api/v1/events) for changes as they happen, and this to backfill or reconcile. Since 1.5.0."},{"name":"status","in":"query","schema":{"type":"string"},"description":"Since 1.5.0. Comma list of vehicle statuses (DRAFT, APPROVED, LISTED, ON_HOLD, UNDER_OFFER, SOLD, …)"},{"name":"vin","in":"query","schema":{"type":"string","minLength":4,"maxLength":17},"description":"Since 1.5.0. The whole VIN or its last characters (the last 6 a person reads off the car)"},{"name":"make","in":"query","schema":{"type":"string"},"description":"Since 1.5.0. Exact, any case"},{"name":"model","in":"query","schema":{"type":"string"},"description":"Since 1.5.0. Exact, any case"},{"name":"engagement","in":"query","schema":{"type":"string"},"description":"Since 1.9.0. Comma list of HOT, WARM, COLD: only cars on the market (LISTED, UNDER_OFFER, ON_HOLD) with that engagement, newest first. `?engagement=COLD` is the cars nobody looks at"}],"description":"Needs `vehicles`. Newest first. Takes an API key or, since 1.5.0, a Connect Cypress token. Each vehicle names its open listing (`listing`), the one to pause, resume or cancel. Filters combine."}},"/api/v1/vehicles/bulk":{"post":{"tags":["Cypress API v1"],"summary":"Bulk push (≤500, per-item results; one bad row never fails the batch)","responses":{"200":{"description":"Per-item results","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"vin":{"type":"string"},"status":{"type":"integer"},"id":{"type":"string"},"href":{"type":"string"},"code":{"type":"string","enum":["PLANNING_STOCK","LIFE_STAGE_READ_ONLY","PLANNING_NOT_ENABLED","CHANNEL_NOT_GRANTED","SCOPE_MISSING","PLAN_BUSY","NO_PLAN"]},"errors":{"type":"array","items":{"type":"string"},"description":"On a 201/200 planning item: why its plan step did not land (the vehicle is written, in OPERATION)"},"lifeStage":{"type":"string","description":"Planning items: the stage the vehicle is in after the push"},"warnings":{"type":"array","items":{"type":"string"}},"inspectionReport":{"type":"string","enum":["QUEUED","UNCHANGED","LINK_ONLY"],"description":"Since 1.8.0, when the item carried inspectionReportUrl: queued to be read, already the vehicle's, or kept as a link only. A link that names no report is a warning; the vehicle is written anyway"},"fields":{"type":"array","items":{"type":"string"},"description":"A dry run's update (1.8.0): the fields whose value would change"},"floorPrice":{"type":"string","enum":["SET","UNCHANGED","STAGED"],"description":"Since 1.8.0, when the item carried floorPrice: set, already the floor, or a request Cypress reviews (a live vehicle)"}}}},"created":{"type":"integer"},"updated":{"type":"integer"},"conflicts":{"type":"integer"},"invalid":{"type":"integer"},"refused":{"type":"integer","description":"Items answered 403 — planning stock on an organization without Planning, an embedded listing without the listings scope, or a planning item without planning:write"},"planningStep":{"type":"object","properties":{"error":{"type":"string"}},"description":"Present only when the plan step failed outright after the planning items were written — retry them with ?mode=upsert"},"dryRun":{"type":"boolean","description":"Since 1.8.0: true on a dry run — each item and the removals say what would happen; nothing was written"},"syncId":{"type":"string","description":"Since 1.8.0: the push's label, as sent"},"removals":{"type":"object","description":"Since 1.8.0, with removeMissing=true: the active Sell vehicles the push left out. Each is archived at once, or, with an open offer or a sale in progress, staged for Cypress's review (VEHICLES.DISPOSITION.RESOLVED tells the decision).","properties":{"activeInventory":{"type":"integer","description":"Your active Sell vehicles before the push (not sold, not archived, not planning stock)"},"missing":{"type":"integer","description":"How many active vehicles the push left out, filed and kept (the guard counts these)"},"archived":{"type":"integer","description":"Archived at once (no open offer, no sale in progress)"},"staged":{"type":"integer","description":"Requests this push filed for Cypress's review"},"alreadyPending":{"type":"integer","description":"Left-out vehicles that already had a request waiting: none added"},"items":{"type":"array","items":{"type":"object","properties":{"vin":{"type":"string"},"id":{"type":"string"},"requestId":{"type":"string","description":"The archive request: approved at once when `archived`, else waiting for review (absent on a dry run)"},"archived":{"type":"boolean","description":"Archived at once (no open offer, no sale in progress)"},"statusBefore":{"type":"string","description":"The vehicle's status when the push filed it"},"statusAfter":{"type":"string","description":"Its status after the filing: ARCHIVED when archived at once, ON_HOLD when its live listing was paused for the review, else unchanged until the decision"},"paused":{"type":"boolean"},"alreadyPending":{"type":"boolean"},"liveDeal":{"type":["object","null"],"description":"Open offers (`kind: OFFERS`, `openOffers`, `topOffer`) or a sale in progress (`kind: POST_SALE`, `status`): why Cypress reviews it"}}}},"kept":{"type":"array","description":"Left out but not filed: REVIEW_REJECTED (Cypress rejected its removal by an earlier push and it has not been pushed since; push it, then leave it out, to ask again), NO_LONGER_ACTIVE (sold or archived while the push was written)","items":{"type":"object","properties":{"vin":{"type":"string"},"id":{"type":"string"},"status":{"type":"string"},"reason":{"type":"string","enum":["REVIEW_REJECTED","NO_LONGER_ACTIVE"]}}}}}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Since 1.8.0, code MASS_REMOVAL: removeMissing=true would take off more than a fifth of your active vehicles (and more than five); nothing was written (`activeInventory`, `missing`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Envelope invalid (missing vehicles[], or over 500 items; inventoryVins without removeMissing=true; a malformed syncId)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"An item's embedded `listing` needs the `listings` scope too; missing it answers that item 403 SCOPE_MISSING (the batch continues).\n\n**Planning items (1.3.0)** — items with `lifeStage: OPERATION` / `PLANNING` follow the single push's rules, per item (no planning:write → that item 403). They are written after the Sell items, and every PLANNING item of the batch is benched in ONE plan version. When the plan was busy, the affected items carry `code: PLAN_BUSY` and the response a `Retry-After` header.\n\n**The whole inventory (1.8.0)** — with `removeMissing=true` the push is everything you hold: every active Sell vehicle it leaves out (not sold, not archived, not planning stock) is taken off, as the app's Import does with the vehicles a file leaves out and by the same archiving rules: archived at once without an open offer or a sale in progress (VEHICLES.DISPOSITION.RESOLVED, automatic); with one, staged for Cypress's review, a listed vehicle paused meanwhile (STAGED now, RESOLVED with the decision). `removals` answers each one's status. An item refused for another field still counts as in the inventory. Not filed, and answered in `removals.kept`: one whose removal by an earlier push Cypress rejected (until it is pushed again), and one sold or archived while the push was written. A vehicle the push names that still has an archive request waiting gets a warning on its item; the push does not withdraw it. An inventory larger than 500 sends its pages without the flag and names every VIN it holds in `inventoryVins` on the last page. A push that would take off more than a fifth of the active vehicles (and more than five) is refused whole (409 MASS_REMOVAL) unless `allowMassRemoval=true`. A daily feed sends `mode=merge`, so the fields it doesn't carry are never cleared.","parameters":[{"name":"mode","in":"query","schema":{"type":"string","enum":["upsert","merge"]},"description":"`upsert` replaces a VIN you already hold with what you send: every field left out is cleared. `merge` (since 1.8.0) changes only the fields you send, as PATCH: photos stay unless you send `images`, external ids and the inspection report stay unless sent; the mode for a feed that carries a few columns. A new VIN is created either way. Omitted: an existing VIN answers 409."},{"name":"removeMissing","in":"query","schema":{"type":"boolean"},"description":"Since 1.8.0: the push is your whole inventory; the vehicles it leaves out are taken off by the archiving rules"},{"name":"allowMassRemoval","in":"query","schema":{"type":"boolean"},"description":"Since 1.8.0: with removeMissing, allow taking off more than a fifth of the active vehicles (when more than five)"},{"name":"syncId","in":"query","schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$"},"description":"Since 1.8.0: your label for this push, told again in its DISPOSITION events"},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.8.0: every check, and what each item and the removals would do; nothing written"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicles":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/VehicleWrite"}},"inventoryVins":{"type":"array","maxItems":20000,"items":{"type":"string"},"description":"Since 1.8.0, with removeMissing=true: every VIN your inventory holds, when it is larger than this push"}},"required":["vehicles"]}}}}}},"/api/v1/vehicles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Cypress API v1"],"summary":"Read a vehicle","responses":{"200":{"description":"The vehicle","content":{"application/json":{"schema":{"type":"object","properties":{"vehicle":{"$ref":"#/components/schemas/VehicleRead"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (cross-org ids are 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `vehicles`; takes an API key or, since 1.5.0, a Connect Cypress token. The whole vehicle: its identity, status and lifeStage, mileage, condition, location, prices, photos, your ids, and its open listing (`listing`). A `planning:read` key on an organization with Planning also sees planning stock (`lifeStage` OPERATION/PLANNING) by id; any other key gets 404 for one.","parameters":[{"name":"include","in":"query","schema":{"type":"string","enum":["insights"]},"description":"Since 1.5.0. `insights` adds the record's insights inline (needs `insights:read`; counts against the insights limit)"}]},"patch":{"tags":["Cypress API v1"],"summary":"Partial update (only provided keys change)","responses":{"200":{"description":"Updated; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"vehicle":{"$ref":"#/components/schemas/VehicleRead"},"warnings":{"type":"array","items":{"type":"string"},"description":"Planning stock only — e.g. a tier-only condition left the 1.0–5.0 grade unchanged"}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Planning stock: code PLANNING_STOCK when the body names prices, `listing` or `images` (Sell only; 403 PLANNING_NOT_ENABLED if the organization does not have Planning), or LIFE_STAGE_READ_ONLY for a different lifeStage (move it with POST /api/v1/planning/moves). Sell stock: LIFE_STAGE_READ_ONLY when lifeStage crosses the Planning/Sell line","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — or `ownership` on planning stock (send it with PUT /api/v1/vehicles/{id}/ownership)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"**Planning stock (1.3.0)** — with `planning:write`, a PATCH on a vehicle in OPERATION or PLANNING updates its details through the app's planning details save: each field audited, a mileage change recorded as an odometer reading, no valuation bought. Echoing the current lifeStage is fine. Without `planning:write` it answers 403 (SCOPE_MISSING — 1.2.0 answered 409 PLANNING_STOCK; PLANNING_NOT_ENABLED when the organization has no Planning), checked before an `ownership` key's 422.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]},"put":{"tags":["Cypress API v1"],"summary":"Full re-push (mapper-owned fields replaced; absent optionals cleared, except a condition an inspection set (1.8.0); VIN immutable)","responses":{"200":{"description":"Updated; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"vehicle":{"$ref":"#/components/schemas/VehicleRead"}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"VIN change attempted — or code PLANNING_STOCK when the vehicle is in Planning, with any key (a full replace has no planning meaning: use PATCH) — 403 PLANNING_NOT_ENABLED if the organization does not have Planning","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VehicleWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]},"delete":{"tags":["Cypress API v1"],"summary":"Delete an unlisted vehicle","responses":{"200":{"description":"With ?dryRun=true (since 1.5.0): what would change, nothing written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WriteDryRun"}}}},"204":{"description":"Deleted"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Vehicle is listed/mid-deal/sold — cancel the listing or use disposition — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `vehicles`; API keys. Deletes a vehicle that was never listed (a draft or one in review), with its pictures and your ids; a listed, sold or archived vehicle is never deleted: cancel its listing or report a disposition instead.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/vehicles/{id}/disposition":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Cypress API v1"],"summary":"Report sold-elsewhere (at once without an open offer or a sale in progress; otherwise staged for Cypress review)","responses":{"200":{"description":"Since 1.8.0: archived at once; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ArchivedResult"},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"202":{"description":"Staged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedResult"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already sold or archived — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DispositionRequest"}}}},"description":"Needs `vehicles`. As the app's sold-elsewhere, by the archiving rules of 1.8.0: a vehicle with no open offer and no sale in progress is archived at once (200, VEHICLES.DISPOSITION.RESOLVED with `automatic: true`); one with an open offer or a sale in progress is staged for Cypress's review (202): one request per vehicle (a second answers the first, `alreadyPending`), a live listing paused while it waits (LISTINGS.PAUSED), the decision as VEHICLES.DISPOSITION.RESOLVED, a rejection resuming the listing. Before 1.8.0 every report was staged.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/vehicles/{id}/ownership":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Planning"],"summary":"A vehicle's purchase & financing, and what Cypress works out from it","responses":{"200":{"description":"The record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OwnershipRead"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's id is 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Any vehicle of the organization. Sell stock needs `vehicles`; planning stock needs `planning:read` too. No market value is returned."},"put":{"tags":["Planning"],"summary":"Replace a vehicle's purchase & financing (a field left out is cleared)","responses":{"200":{"description":"Saved; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/OwnershipRead"},{"type":"object","properties":{"warnings":{"type":"array","items":{"type":"string"}}}}]},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed (unknown fields refused), or a cross-field check — details.errors lists each, e.g. \"payoffDate: is before the purchase date\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"A full replace: every field you do not send is cleared. Sell stock needs `vehicles`; planning stock needs `planning:write` too. Same field rules, checks and audit as the app's purchase & financing save; buys no valuation, writes no plan version.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ownership"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/vehicles/{id}/odometer-readings":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Planning"],"summary":"A planning vehicle's odometer readings, newest first (up to 100)","responses":{"200":{"description":"Readings","content":{"application/json":{"schema":{"type":"object","properties":{"readings":{"type":"array","items":{"$ref":"#/components/schemas/OdometerReading"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IN_SELL — the vehicle is in Sell (its mileage is a PATCH); or code RETIRED — the vehicle has left the fleet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Planning stock only. Needs `vehicles` and `planning:read`."},"post":{"tags":["Planning"],"summary":"Record an odometer reading","responses":{"200":{"description":"With ?dryRun=true (since 1.5.0): what would change, nothing written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WriteDryRun"}}}},"201":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object","properties":{"reading":{"$ref":"#/components/schemas/OdometerReading"},"mileage":{"type":["integer","null"],"description":"The vehicle's current mileage after this reading"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IN_SELL — the vehicle is in Sell; or code RETIRED — the vehicle has left the fleet; or code ODOMETER_ROLLBACK — the reading runs the series backwards (details.recorded = { miles, readAt } it conflicts with); send force: true for a replaced or corrected odometer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — exactly one of miles/km; readAt a real date, not in the future","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Planning stock only; needs `vehicles` and `planning:write`. km is converted to miles. A reading dated on or after the latest one (the vehicle's current mileage counts as a reading dated today when it has none) becomes the vehicle's mileage; an older one is stored as history and never changes the current mileage, even with force. A reading lower than the latest at or before its date, or higher than the next one after it, is a rollback.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OdometerWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/vehicles/{id}/cost-events":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Planning"],"summary":"A vehicle's cost events, newest first (up to 100)","responses":{"200":{"description":"Cost events","content":{"application/json":{"schema":{"type":"object","properties":{"costEvents":{"type":"array","items":{"$ref":"#/components/schemas/CostEvent"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Any vehicle of the organization, Sell stock included. Needs `vehicles` and `planning:read`."},"post":{"tags":["Planning"],"summary":"Record a cost (maintenance, repair, fuel, insurance, registration)","responses":{"200":{"description":"Already recorded — the stored row for this externalRef, unchanged; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"costEvent":{"$ref":"#/components/schemas/CostEvent"}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"201":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object","properties":{"costEvent":{"$ref":"#/components/schemas/CostEvent"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — eventDate must be a real date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Any vehicle of the organization, Sell stock included; needs `vehicles` and `planning:write`. Send `externalRef` to make a retry safe. Recorded for your history: the plan's carry cost does not read cost events yet — it uses the cost assumptions set in the app.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostEventWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/vehicles/{id}/departure":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Planning"],"summary":"A planning vehicle left the fleet (at once since 1.8.0)","responses":{"200":{"description":"Since 1.8.0: the vehicle left the fleet at once; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ArchivedResult"},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"202":{"description":"A request filed before 1.8.0 still waits — the decision arrives as VEHICLES.DISPOSITION.RESOLVED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedResult"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IN_SELL — the vehicle is in Sell (use POST /api/v1/vehicles/{id}/disposition); or code RETIRED — the vehicle has already left the fleet; or the organization has no admin or fleet manager to file the request under","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — soldPrice/soldAt only with SOLD_OFF_PLATFORM; soldAt a real date, not in the future","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Planning stock only; needs `vehicles` and `planning:write`. Since 1.8.0 the vehicle leaves the fleet at once (200; VEHICLES.DISPOSITION.RESOLVED with `automatic: true`): planning stock was never on the market, so there is nothing for Cypress to weigh. Before 1.8.0 a Cypress Manager reviewed every departure; a request filed then still waits, and a second departure answers it (202, alreadyPending: true). The sale figures travel in the request's note.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartureRequest"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/plan":{"get":{"tags":["Planning"],"summary":"The live plan — strategy, version, the sale windows and tracks","responses":{"200":{"description":"The plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanSummary"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The organization has no plannable vehicles yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:read`. Opens the base plan on the first read when none exists, as the app does. Window ids change with every plan version — follow a window across versions by its `lineage`. Each window carries `quarter` and `closed` (since 1.4.0): a window of a quarter that is over (`closed: true`) takes no plan change and answers `409 QUARTER_CLOSED`, whatever its `state` reads. `plan.version` is a revision counter for correlating writes and reads; `plan.note` is free text — don't parse it."}},"/api/v1/planning/vehicles":{"get":{"tags":["Planning"],"summary":"The plan's vehicles, paginated (?windowId=&windowLineage=&state=&trackKey=&lifeStage=)","responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PlanVehicleRow"}},"totalCount":{"type":"integer"},"href":{"type":"string"},"nextHref":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unknown query parameter, or an invalid filter value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:read`. Every vehicle in the latest plan, ordered by rank — Sell stock adopted by the plan included. Rows carry the latest valuation and the stored plan advice; the expected realized value and the market trend are on GET /api/v1/planning/vehicles/{id} only. `track` is the effective track (the default track for a vehicle not on one), and `?trackKey=<the default key>` includes those vehicles. A read may enroll vehicles new to the plan, as the app does.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"windowId","in":"query","schema":{"type":"string"}},{"name":"windowLineage","in":"query","schema":{"type":"string"},"description":"e.g. 2026W44-2026W45 — stable across plan versions"},{"name":"state","in":"query","schema":{"type":"string","enum":["CANDIDATE","STAGED","CONDITIONAL","PROMOTED","SLIPPED","HELD","IN_OPERATION","PARKED"]}},{"name":"trackKey","in":"query","schema":{"type":"string"}},{"name":"lifeStage","in":"query","schema":{"type":"string"},"description":"Comma list of OPERATION, PLANNING, REMARKETING, POST_SALE, RETIRED"}]}},"/api/v1/planning/vehicles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Planning"],"summary":"One vehicle's plan view — with the expected realized value, trend and verdict","responses":{"200":{"description":"The vehicle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanVehicleDetail"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in this organization's plan (another organization's id is 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:read`. The app's own recommendation for the vehicle — computed per organization and cached, so it can be up to 60 seconds stale after a write."}},"/api/v1/planning/moves":{"post":{"tags":["Planning"],"summary":"Move vehicles into a sale window, to the bench, or back to operation (≤50, one plan version)","responses":{"200":{"description":"Moved — one new plan version; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"planVersion":{"type":"integer"},"moved":{"type":"integer","description":"to.windowId"},"changed":{"type":"integer","description":"BENCH / OPERATION"},"skipped":{"$ref":"#/components/schemas/Skipped"},"findings":{"type":"array","items":{"type":"string"},"description":"to.windowId — advice, never a wall: vehicles scheduled as waiting on a payoff/arrivals blocker, market crowding in the window"}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No active planning strategy, or no plan — or code WINDOW_GONE: no window of the latest plan version has that window's lineage (an unknown or another organization's id, or a window the plan no longer has — re-read GET /api/v1/planning/plan)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code QUARTER_CLOSED — `to.windowId` is a window of a quarter that is over, or `to: OPERATION` would take a vehicle scheduled in one out of it (the whole request is refused, nothing is written, not retryable; `details.vehicleIds` names the vehicles it blocks); code WINDOW_CLOSED — the window has closed, in a quarter still in progress; or no code, when every vehicle was skipped (\"Nothing here can be moved…\", with `skipped`); or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed (1–50 vehicleIds; one target)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. One target per call — one call is one plan version. A vehicle that cannot go is listed in `skipped` with its reason and the rest move: an unknown or another organization's id (\"not in the plan\"); into a window — an open EVIDENCE blocker (\"disputed evidence blocks scheduling\"), or a vehicle in market; to BENCH — a vehicle in Sell (\"in Sell — remarketing owns it\"), one already on the bench (\"already a candidate\"), or one already scheduled in a window (\"already scheduled\": the API cannot take a scheduled vehicle back to the bench, the app does); to OPERATION — a vehicle in Sell, or one already there (\"already in operation\"). A state that cannot be benched or returned reads \"cannot bench from <state>\" or \"cannot return from <state>\". When every vehicle is skipped the call answers 409 without a code. A vehicle handed to Sell can change window (the window it is expected to sell in) but never return to the bench from here — see POST /api/v1/planning/demotions. A quarter whose last day has passed takes no move into its windows, and no move to OPERATION out of them, for a scheduled vehicle (409 QUARTER_CLOSED): a vehicle that slipped (its window closed unsold) can still leave, and an unsold vehicle can be moved from a closed window into a window of a quarter in progress.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningMove"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/moves/track":{"post":{"tags":["Planning"],"summary":"Move vehicles onto a track (≤50, one plan version)","responses":{"200":{"description":"Moved; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"planVersion":{"type":"integer"},"changed":{"type":"integer"},"skipped":{"$ref":"#/components/schemas/Skipped"},"track":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"name":{"type":"string"}}}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Track not found (no live plan, or no track with that key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code QUARTER_CLOSED — a planned vehicle (not yet handed to Sell) sits in a window of a quarter that is over: the whole request is refused, nothing is written, not retryable, and `details.vehicleIds` names those vehicles; or no code, when every vehicle was skipped (\"Nothing here changes track\", with `skipped`); or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Name the track by its `key` (GET /api/v1/planning/plan lists them). A vehicle already in Sell keeps selling; its track label changes so pricing rules read the new posture — also after its window's quarter is over (only planned vehicles are frozen with a closed quarter, and a vehicle that slipped can change too).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningTrackMove"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/moves/park":{"post":{"tags":["Planning"],"summary":"Park vehicles until a coming quarter (≤50, one plan version)","responses":{"200":{"description":"Parked; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"planVersion":{"type":"integer"},"changed":{"type":"integer"},"skipped":{"$ref":"#/components/schemas/Skipped"},"parkedUntil":{"type":"string","format":"date-time"}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No active planning strategy, or no plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code QUARTER_CLOSED — a scheduled vehicle sits in a window of a quarter that is over: the whole request is refused, nothing is written, not retryable, and `details.vehicleIds` names those vehicles; or no code, when every vehicle was skipped (\"Nothing here can be parked\", with `skipped`); or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — or code QUARTER_PASSED: that quarter has already started (parking until a quarter that has started; not to be confused with QUARTER_CLOSED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. A parked vehicle leaves its window and every proposal; the daily sweep brings it back to the bench when the quarter starts. A vehicle handed to Sell cannot be parked. A scheduled vehicle in a window of a quarter that is over is not parked (409 QUARTER_CLOSED); one that slipped is.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningPark"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/moves/unpark":{"post":{"tags":["Planning"],"summary":"Bring parked vehicles back to the bench (≤50, one plan version)","responses":{"200":{"description":"Back on the bench; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"planVersion":{"type":"integer"},"changed":{"type":"integer"},"skipped":{"$ref":"#/components/schemas/Skipped"},"parkedUntil":{"type":"null"}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No active planning strategy, or no plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Nothing here is parked (all skipped); or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningUnpark"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/blockers":{"get":{"tags":["Planning"],"summary":"A vehicle's blockers — open first, then resolved (?vehicleId=)","responses":{"200":{"description":"Blockers","content":{"application/json":{"schema":{"type":"object","properties":{"blockers":{"type":"array","items":{"$ref":"#/components/schemas/Blocker"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Vehicle not found (another organization's id is 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"vehicleId missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:read`.","parameters":[{"name":"vehicleId","in":"query","required":true,"schema":{"type":"string"}}]},"post":{"tags":["Planning"],"summary":"Add a blocker to a vehicle","responses":{"200":{"description":"With ?dryRun=true (since 1.5.0): what would change, nothing written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WriteDryRun"}}}},"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"planVersion":{"type":["integer","null"],"description":"null when the organization has no live plan"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. A closed quarter does not refuse a blocker: it is a fact about the vehicle. A blocker gates the sale, not the planning: an EVIDENCE blocker stops the vehicle being scheduled; a PAYOFF or ARRIVALS blocker schedules it as waiting (CONDITIONAL); at the hand-off any open blocker holds the vehicle (HELD_BLOCKER_OPEN) and an EVIDENCE one blocks it. One plan version when the organization has a live plan.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockerCreate"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/blockers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"tags":["Planning"],"summary":"Resolve a blocker (resolvingRef) or edit its kind/note","responses":{"200":{"description":"Resolved → { resolved: true, planVersion }; edited → { blocker: { id, kind, note }, planVersion }; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"resolved":{"type":"boolean"},"blocker":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"note":{"type":"string"}}},"planVersion":{"type":["integer","null"]}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code RESOLVED — a resolved blocker is history; or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — resolvingRef needs 5+ characters; never both shapes at once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Resolving the last open blocker of a waiting (CONDITIONAL) vehicle returns it to STAGED in the same plan version. Deleting a blocker is not available on the API.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlockerPatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/windows/{windowId}/cohort-preview":{"parameters":[{"name":"windowId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Planning"],"summary":"Preview the cohort a confirm would hand to Sell — with the digest that binds it (24 h)","responses":{"200":{"description":"The cohort","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CohortPreview"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's window is 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code QUARTER_CLOSED — the window is in a quarter that is over, so there is no cohort to confirm (since 1.4.0; `details.quarter` names it); code WINDOW_CLOSED — the window has closed, in a quarter still in progress: promote from an open window","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Writes nothing. The members are the window's STAGED and CONDITIONAL vehicles. Answers as the confirm does for a window of a quarter that is over."}},"/api/v1/planning/windows/{windowId}/cohort-confirm":{"parameters":[{"name":"windowId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Planning"],"summary":"Confirm the cohort — hand the window's ready vehicles to Sell intake (one plan version)","responses":{"200":{"description":"Per-vehicle results; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"planVersion":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"vehicleId":{"type":"string"},"result":{"type":"string","enum":["INTAKE_CONFIRMED","HELD_BLOCKER_OPEN","BLOCKED_EVIDENCE"],"description":"INTAKE_CONFIRMED: handed to Sell (REMARKETING, still DRAFT — nothing is listed). HELD_BLOCKER_OPEN: waits on an open blocker. BLOCKED_EVIDENCE: an open EVIDENCE blocker — untouched."}}}}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code QUARTER_CLOSED — the window is in a quarter that is over (nothing is written, not retryable; `details.quarter` names it); code PREVIEW_STALE — the preview expired or the cohort changed since (preview again); WINDOW_CLOSED — the window has closed, in a quarter still in progress; or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — echo both digest and expiresAt from the preview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. The one effect: eligible vehicles leave planning for the Sell intake (status stays DRAFT; nothing is listed, priced, disclosed or billed). Sends PLAN.HANDED_TO_SELL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CohortConfirm"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/demotions":{"post":{"tags":["Planning"],"summary":"Return a vehicle from the Sell intake to the plan's bench (one vehicle, one plan version)","responses":{"200":{"description":"Back on the bench; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"planVersion":{"type":["integer","null"],"description":"null when the organization has no live plan (the vehicle joins the bench when one opens)"},"state":{"type":"string","enum":["CANDIDATE"]}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already in planning; or code SELLING_BEGUN — the vehicle is listed or beyond (delist, or archive review, are the paths back); or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Only a vehicle whose selling has not begun (DRAFT through PRE_LISTED) comes back; it is reset to DRAFT, on the bench. A closed quarter does not refuse it: it is the vehicle's future, not the quarter's plan.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"vehicleId":{"type":"string"},"reason":{"type":"string","maxLength":300}},"required":["vehicleId"]}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/strategy":{"get":{"tags":["Planning"],"summary":"The active strategy (the mandate), or null for the base plan","responses":{"200":{"description":"The strategy","content":{"application/json":{"schema":{"type":"object","properties":{"strategy":{"oneOf":[{"$ref":"#/components/schemas/PlanningStrategy"},{"type":"null"}]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:read`. Since 1.5.0."},"post":{"tags":["Planning"],"summary":"Set the mandate: a new strategy, plan v1 and the whole fleet enrolled; with goals, the quarter's goals too (the sell draft in one call)","responses":{"200":{"description":"With ?dryRun=true: what would change, nothing written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningDryRun"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningStrategyCreated"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Since 1.5.0. Retires the active strategy (its history stays), makes plan v1 (six two-week sale windows from today) and enrolls every vehicle: planning-owned ones in operation (or on the bench with `benchAll`), anything already in Sell adopted as PROMOTED. Each goal in `goals` is added as its own plan version, as the app does; one that is refused is reported in `goals` and the strategy stands. A proposal: nothing executes from it until a person approves the quarter. An agent may set it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningStrategyCreate"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}]},"delete":{"tags":["Planning"],"summary":"End the active strategy: the base plan reopens on the next read","responses":{"200":{"description":"Ended; or, with ?dryRun=true, what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"ended":{"type":"string","description":"The strategy's name"}}},{"$ref":"#/components/schemas/PlanningDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No active strategy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Since 1.5.0. Soft: every plan version, window and review stays readable.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/goals":{"get":{"tags":["Planning"],"summary":"The quarter's goals with their monthly pacing (?periodId=)","responses":{"200":{"description":"Goals","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":["object","null"],"properties":{"id":{"type":"string"},"periodKey":{"type":"string"},"status":{"type":"string"}}},"goals":{"type":"array","items":{"$ref":"#/components/schemas/PlanningGoal"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:read`. Since 1.5.0. Left out, `periodId` is the quarter holding most of the open windows; with no strategy, `period` is null and the list empty.","parameters":[{"name":"periodId","in":"query","schema":{"type":"string"}}]},"post":{"tags":["Planning"],"summary":"Add a goal to the quarter (one plan version)","responses":{"200":{"description":"With ?dryRun=true: what would change, nothing written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningDryRun"}}}},"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningGoal"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No quarter to plan (no strategy: POST /api/v1/planning/strategy first), or the track is not the quarter's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code QUARTER_CLOSED — the quarter is over; or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Since 1.5.0. An agent may add goals.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningGoalCreate"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/goals/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"tags":["Planning"],"summary":"Change a goal's number, date, label, pacing or track (one plan version)","responses":{"200":{"description":"Changed; or, with ?dryRun=true, what would change","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PlanningGoal"},{"$ref":"#/components/schemas/PlanningDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's goal is 404), or the track is not the quarter's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code KIND_CHANGE — a goal keeps its kind; QUARTER_CLOSED — the quarter is over; or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed (send at least one field)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Since 1.5.0.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningGoalPatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}]},"delete":{"tags":["Planning"],"summary":"Remove a goal (one plan version)","responses":{"200":{"description":"Removed; or, with ?dryRun=true, what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"removed":{"type":"string","description":"The goal's label"},"planVersion":{"type":"integer"}}},{"$ref":"#/components/schemas/PlanningDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code QUARTER_CLOSED — the quarter is over; or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Since 1.5.0.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/quarters/{periodKey}":{"parameters":[{"name":"periodKey","in":"path","required":true,"schema":{"type":"string","example":"2026-Q4"},"description":"A quarter like `2026-Q4`, or `current` for the quarter in progress (UTC, read when the request arrives)"}],"get":{"tags":["Planning"],"summary":"Read a quarter of the sell plan — goals, attainment, lots, windows, shape, and the digest to approve it","responses":{"200":{"description":"The quarter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningQuarter"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The organization has no plan yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"periodKey is not a quarter like 2026-Q4 or `current`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:read`. Since 1.5.0. `current` is the quarter holding most of the open windows. The quarter is created on first read, as the app does."}},"/api/v1/planning/quarters/{periodKey}/approve":{"parameters":[{"name":"periodKey","in":"path","required":true,"schema":{"type":"string","example":"2026-Q4"},"description":"A quarter like `2026-Q4`, or `current` for the quarter in progress (UTC, read when the request arrives)"}],"post":{"tags":["Planning"],"summary":"Approve the quarter — the approved plan becomes the baseline every later comparison reads against","responses":{"200":{"description":"Approved; or, with ?dryRun=true, what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"planVersion":{"type":"integer"},"status":{"type":"string","enum":["APPROVED"]},"approvedPlanVersion":{"type":"integer"},"approvedAt":{"type":"string","format":"date-time"}}},{"$ref":"#/components/schemas/PlanningDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY — an agent's token: approving is a person's, nothing is written; or PLANNING_NOT_ENABLED, SCOPE_MISSING, ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such quarter in the active strategy (read it first: GET /api/v1/planning/quarters/{periodKey})","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code PREVIEW_STALE — the plan changed since the digest was cut (read the quarter again, then approve); PERIOD_CLOSED — the quarter is over; or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — periodKey is a quarter like 2026-Q4; `digest` is the quarter's approvalDigest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Since 1.5.0. **People only**: an agent prepares the plan, a person approves it; an app acting for a person and an API key may. Approving again moves the baseline. No market effect. A dry run meets the same checks (an agent's is refused PEOPLE_ONLY too).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningQuarterApprove"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}]}},"/api/v1/planning/schedule/proposals":{"post":{"tags":["Planning"],"summary":"Ask Sequoia for the quarter's schedule — which vehicles into which windows, and why (writes nothing)","responses":{"200":{"description":"The proposal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleProposal"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No active planning strategy, or the quarter is not this organization's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed (periodId or periodKey, not both)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Since 1.5.0. Writes nothing; the digest binds a later apply to exactly this set for 24 hours.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleProposalRequest"}}}}}},"/api/v1/planning/schedule/apply":{"post":{"tags":["Planning"],"summary":"Apply Sequoia's schedule (all of it, or the lines you choose): one plan version","responses":{"200":{"description":"Applied; or, with ?dryRun=true, what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"planVersion":{"type":"integer"},"applied":{"type":"integer"},"windows":{"type":"array","items":{"type":"string"}},"targetsWritten":{"type":"integer"},"warnings":{"type":"array","items":{"type":"string"}}}},{"$ref":"#/components/schemas/PlanningDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or no active planning strategy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code PREVIEW_STALE — the proposal expired or the plan changed since (ask for a new one); QUARTER_CLOSED — the quarter is over; no code when nothing selected is in the proposal; or code PLAN_BUSY — another write took the plan version first; nothing was written. Retry after `Retry-After` seconds.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds to wait before retrying (2)"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — send the proposal's periodId, digest and expiresAt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `planning:write`. Since 1.5.0. The proposal is computed again and compared. The lines are staged with their lot, rank and reasons, and the lot targets Sequoia derived from the goals are written where the planner set none. No market effect: nothing executes until a person approves the quarter. An agent may apply it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleApply"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}]}},"/api/v1/buy-planning/quarters/{periodKey}":{"parameters":[{"name":"periodKey","in":"path","required":true,"schema":{"type":"string","example":"2026-Q4"},"description":"A quarter like `2026-Q4`, or `current` for the quarter in progress (UTC, read when the request arrives)"}],"get":{"tags":["Buy planning"],"summary":"Read a quarter of the buy plan — goal, budget, mandate, approval, progress and the digest","responses":{"200":{"description":"The quarter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyQuarter"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"periodKey is not a quarter like 2026-Q4 or `current`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:read`. A quarter nobody has set yet reads as an empty one, not a 404. `progress` counts the purchases made in the quarter by the one rule the app's header, Budget card and Review use; new Cypress closings are counted first. Send the `digest` to approve."},"put":{"tags":["Buy planning"],"summary":"Set the quarter's units goal, budget and mandate (null clears one) — answers the quarter again","responses":{"200":{"description":"The quarter, as written; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BuyQuarter"},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code QUARTER_CLOSED — the quarter's last day has passed, so its goal no longer changes (a closed quarter's goal is what Review compares it against); nothing is written. Not retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — `unitsGoal` and `budget` are always sent (null clears), a mandate is one of the four, a goal is a whole number of units","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:write`. One write for the three; `mandate` left out keeps the quarter's mandate. The dealer's note on the quarter is never touched. Sequoia reads the market again after it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyQuarterWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/buy-planning/quarters/{periodKey}/approve":{"parameters":[{"name":"periodKey","in":"path","required":true,"schema":{"type":"string","example":"2026-Q4"},"description":"A quarter like `2026-Q4`, or `current` for the quarter in progress (UTC, read when the request arrives)"}],"post":{"tags":["Buy planning"],"summary":"Approve the quarter — the plan as it stands becomes the baseline Review compares against","responses":{"200":{"description":"The quarter, approved: `approval` now holds the date and no changes, and the `digest` is the approved plan's; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BuyQuarter"},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code PLAN_CHANGED — the digest is not the live plan's (\"The plan changed. Refresh and approve again.\"): read the quarter, then approve again; PERIOD_CLOSED — the quarter is over (\"This quarter is over.\"); NOTHING_TO_APPROVE — no goal, no budget and no target (\"Set a goal or add a target first.\"). Nothing is written. These are the approval's own codes, as in the app.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — `digest` is the 16 hex characters of the quarter read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:write`. The approval is bound to `digest`: the live plan is read again inside the write, and a plan that moved since your read is refused. Approving again moves the baseline. The plan stays live and editable; an approval does not close it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyApprove"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/buy-planning/targets":{"get":{"tags":["Buy planning"],"summary":"The dealer's targets of a quarter (?periodKey=&status=)","responses":{"200":{"description":"Targets, soonest needed first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyTargetList"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"periodKey is not a quarter, `current` or `all`; status is not one of OPEN, FILLED, PAUSED, CLOSED, ENDED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:read`. The quarter's targets by the app's own rule: a needed-by week counts in the quarter of its Thursday. `status` keeps the targets that READ as that status (`displayStatus`), not the stored one. New Cypress closings are counted first, so `bought` is current.","parameters":[{"name":"periodKey","in":"query","schema":{"type":"string","default":"current"},"description":"A quarter like `2026-Q4`, `current` (the quarter in progress, the default) or `all` (every target)"},{"name":"status","in":"query","schema":{"type":"string","enum":["OPEN","FILLED","PAUSED","CLOSED","ENDED"]},"description":"The display status"}]},"post":{"tags":["Buy planning"],"summary":"Add a target","responses":{"200":{"description":"With ?dryRun=true (since 1.5.0): what would change, nothing written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WriteDryRun"}}}},"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyTarget"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code QUARTER_CLOSED — the target is needed in a quarter that is over; nothing is written. Not retryable: send a needed-by week of a quarter in progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — one make and model, or a vehicle class; a real date; years and mileage in order; a target price at or below the maximum","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:write`. The app's own rules and body. Match badges are dropped and Sequoia reads the market again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyTargetWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/buy-planning/targets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Buy planning"],"summary":"One target","responses":{"200":{"description":"The target","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyTarget"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Target not found (another organization's id is 404, as one that does not exist)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:read`. With `include=insights` (and `insights:read`) the body also carries `insights`: the price guide and Sequoia's items.","parameters":[{"name":"include","in":"query","schema":{"type":"string","enum":["insights"]},"description":"Since 1.5.0. `insights` adds the record's insights inline (needs `insights:read`; counts against the insights limit)"}]},"patch":{"tags":["Buy planning"],"summary":"Edit a target — `{ status }` alone pauses, reopens or closes it; the whole target body edits its fields","responses":{"200":{"description":"The target, as saved; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BuyTarget"},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Target not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code QUARTER_CLOSED — the target is needed in a quarter that is over (pause, reopen, close and edit alike), or the edit would move it into one; nothing is written. Not retryable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — for a body that is not `{ status }`, the whole target body is validated as for POST","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:write`. Exactly the app's edit: a body of `{ status }` (nothing else) changes the dealer's decision; any other body is the whole target, validated as for POST, and replaces its editable fields — send the target as GET returned it, with your changes (the read-only fields are ignored). The answers come in this order: 404, then 409, then 422.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BuyTargetStatus"},{"$ref":"#/components/schemas/BuyTargetWrite"}]}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]},"delete":{"tags":["Buy planning"],"summary":"Remove a target that has no purchases","responses":{"200":{"description":"Removed; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"deleted":{"type":"boolean"}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Target not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code HAS_PURCHASES — the target has purchases: close it instead, its history stays; code QUARTER_CLOSED — the target is needed in a quarter that is over","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:write`.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/buy-planning/targets/{id}/matches":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Buy planning"],"summary":"The target's live matches — the listings that fit it now, exact and near","responses":{"200":{"description":"Matches in the app's order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyMatchList"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Target not found (another organization's id is 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:read`. The same live matches the app's target panel lists, at the target's track floor (Aggressive 80, Balanced 90, Conservative exact only), without the listings of your own organization and the ones you hid. Demo and real organizations are two worlds: a listing reaches a dealer of its own world only. A match carries the listing's public facts, its score and what it misses — never a seller's name, id, floor, thresholds or limits, and never the staff deal fit. Offers on a listing go through Remarketing, not this API."}},"/api/v1/buy-planning/targets/{id}/matches/{vehicleId}/dismiss":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"vehicleId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Buy planning"],"summary":"Hide a match from this target (or bring it back)","responses":{"200":{"description":"Done; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"ok":{"type":"boolean"}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Target not found (another organization's id is 404), or Vehicle not found: the vehicle is not a match of this target (one answer, whether or not such a vehicle exists)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"undo is not a boolean, or the body is not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:write`. As the app's Hide does. An empty body hides; `{ \"undo\": true }` brings it back. Only a match of this target can be hidden: a listing the target finds now, or one already stored for it; `undo` needs one you hid before. Hiding is not a plan fact, so a closed quarter does not refuse it.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyDismiss"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/buy-planning/purchases":{"get":{"tags":["Buy planning"],"summary":"The dealer's purchases of a quarter (?periodKey=)","responses":{"200":{"description":"Purchases, newest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyPurchaseList"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"periodKey is not a quarter, `current` or `all`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:read`. A purchase counts in the quarter of its date. New Cypress closings are counted first, so a purchase made on Cypress is on the list the moment it is asked for.","parameters":[{"name":"periodKey","in":"query","schema":{"type":"string","default":"current"},"description":"A quarter like `2026-Q4`, `current` (the quarter in progress, the default) or `all`"}]},"post":{"tags":["Buy planning"],"summary":"Record a purchase made elsewhere","responses":{"200":{"description":"With ?dryRun=true (since 1.5.0): what would change, nothing written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WriteDryRun"}}}},"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyPurchase"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Target not found (another organization's id is 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — a real date that is not in the future, a price, what the vehicle was","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:write`. A purchase is a fact: it is never refused for a closed quarter, on a closed quarter's target too, so a late sync from a purchasing system is natural. Since 1.5.0 an `Idempotency-Key` makes a retry record it once; without one, recording the same purchase twice records it twice — read first (`GET /purchases`), then record.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyPurchaseWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/buy-planning/purchases/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"tags":["Buy planning"],"summary":"Move a purchase to another target, or out of the plan (`targetId: null`)","responses":{"200":{"description":"The purchase, as moved; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BuyPurchase"},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Purchase not found, or Target not found (another organization's id is 404)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — `targetId` is a target id or null","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:write`. Allowed on a closed quarter's target too: a purchase is a fact. The attribution rule never moves it back.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyPurchaseReassign"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]},"delete":{"tags":["Buy planning"],"summary":"Remove a purchase that was recorded by hand","responses":{"200":{"description":"Removed; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"deleted":{"type":"boolean"}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Purchase not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code FROM_CLOSING — the purchase came from a Cypress closing and follows that closing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:write`.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/buy-planning/drafts":{"post":{"tags":["Buy planning"],"summary":"Sequoia's draft of a quarter — a goal, a budget and the targets to keep (writes nothing)","responses":{"200":{"description":"The draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyDraft"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BUY_PLANNING_NOT_ENABLED (the organization does not have Buy planning), SCOPE_MISSING (the key lacks `buy-planning:read` / `buy-planning:write`), or ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — a mandate of the four and a quarter like 2026-Q4","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:write`. Since 1.5.0. The starting plan the app's \"Plan my quarter\" shows, read from the dealer's purchases and the market. Writes nothing (a POST because it prepares a write): keep it with POST /api/v1/buy-planning/drafts/apply.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyDraftRequest"}}}}}},"/api/v1/buy-planning/drafts/apply":{"post":{"tags":["Buy planning"],"summary":"Keep a draft: the quarter's goal, budget and mandate, the plan's markets and the kept targets, in one step","responses":{"200":{"description":"With ?dryRun=true: what would change, nothing written","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningDryRun"}}}},"201":{"description":"Kept","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyDraftKept"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY — an agent's token with `approve: true`: approving is a person's, nothing is written; or BUY_PLANNING_NOT_ENABLED, SCOPE_MISSING, ORG_NOT_ACTIVE","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code QUARTER_CLOSED — the quarter is over, or a kept target is needed in one; nothing is written. With `approve: true`, the approval's own codes (PERIOD_CLOSED, NOTHING_TO_APPROVE)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — `issues` names each target that failed by its path (targets.2.make)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `buy-planning:write`. Since 1.5.0. The app's \"Create plan\". Sequoia's targets leave an accepted decision each; the dealer's own (`origin: DEALER`) are manual targets. `approve: true` approves the quarter in the same step (no digest: the plan is the one just written); an agent keeps a draft but never approves it. A dry run writes it all in a transaction it rolls back: the same refusals, the targets it would keep (without ids).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyDraftApply"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}]}},"/api/v1/listings":{"post":{"tags":["Cypress API v1"],"summary":"Create a listing for a vehicle; IMMEDIATE puts it live","responses":{"200":{"description":"With ?dryRun=true: the listing it would make and, for IMMEDIATE, whether the car would go live or what it lacks; nothing written","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"wouldCreate":{"type":"object","properties":{"vehicleId":{"type":"string"},"channels":{"type":"array","items":{"type":"string"}},"listingMode":{"type":"string"},"floorPrice":{"type":"number"},"buyNowPrice":{"type":"number"},"startBidPrice":{"type":"number"}}},"launch":{"type":["object","null"],"properties":{"wouldLaunch":{"type":"boolean"},"alreadyLive":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string"}},"blocked":{"type":["string","null"]}}}}}}}},"201":{"description":"Created (Location header set)","content":{"application/json":{"schema":{"type":"object","properties":{"listing":{"$ref":"#/components/schemas/ListingRead"},"launched":{"type":"boolean"},"launchBlocked":{"type":"string","description":"IMMEDIATE that did not go live: why (the status, or what the car lacks: locationState, mileage, condition, buyNowPrice)"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY — an agent's token that sets `floorPrice`: the floor is the seller's, a person sets it (nothing written); also the common 403s","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown vehicle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code EXTERNAL_ID_TAKEN — an id in `externalIds` names another listing of your organization (`taken` names it), nothing is written; or an open listing already exists — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Channels not enabled, or validation failed — code CHANNEL_NOT_GRANTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `listings`; takes an API key or, since 1.5.0, a Connect Cypress token. `listingMode` IMMEDIATE puts the car live in the same request when it is ready by the app's launch rule: its location (state), mileage, condition and a price (the buy-now, else its target). One that is not stays REQUESTED and `launchBlocked` says what it lacks; a dry run says it first. An agent lists without a floor.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListingWrite"},{"type":"object","properties":{"vehicleId":{"type":"string"},"externalIds":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/ExternalId"},"description":"Your own systems' ids for the record, one per source. Set or replaced per source, never removed by omission. One another record of the same kind in your organization holds answers 409 EXTERNAL_ID_TAKEN, naming it; nothing is written. Since 1.5.0 (vehicles since 1.5.0 too)."}},"required":["vehicleId"]}]}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: every check, nothing written; answers { dryRun, wouldCreate, launch }"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]},"get":{"tags":["Cypress API v1"],"summary":"List your listings (?status= filter)","responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ListingRead"}},"totalCount":{"type":"integer"},"nextHref":{"type":"string"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `listings`. Your listings, newest first: each with its vehicle, status (requested, active, paused, sold, not sold, cancelled), prices, channels and listing mode. Filter by status, or find the one your own system names with `externalId`.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"externalId","in":"query","schema":{"type":"string"},"description":"<source>:<id> — the record your system calls by that id (zero or one item). Since 1.5.0."},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time"},"description":"Changed at or after this time; the list then answers the newest change first. A sync reads the event feed (GET /api/v1/events) for changes as they happen, and this to backfill or reconcile. Since 1.5.0."}]}},"/api/v1/listings/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Cypress API v1"],"summary":"Read a listing","responses":{"200":{"description":"The listing","content":{"application/json":{"schema":{"type":"object","properties":{"listing":{"$ref":"#/components/schemas/ListingRead"},"insights":{"type":"array","items":{"$ref":"#/components/schemas/Insight"},"description":"With include=insights"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `listings`. One listing: its vehicle, status, prices, channels, listing mode, when it went live or closed, and the share link when Direct Links is on.","parameters":[{"name":"include","in":"query","schema":{"type":"string","enum":["insights"]},"description":"Since 1.5.0. `insights` adds the record's insights inline (needs `insights:read`; counts against the insights limit)"}]},"patch":{"tags":["Cypress API v1"],"summary":"Update prices/channels, or pause/resume via status","responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"listing":{"$ref":"#/components/schemas/ListingRead"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BELOW_FLOOR when the buy-now price would sit below the floor; also the common 403s","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code EXTERNAL_ID_TAKEN — an id in `externalIds` names another listing of your organization (`taken` names it), nothing is written; or a closed listing, or a deal is in progress — or code CONFLICT when a price would move under a live offer or sale — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Channels not enabled, or validation failed — code CHANNEL_NOT_GRANTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingUpdate"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"true: check every rule and write nothing; answers { dryRun, listingId, wouldChange } or the refusal"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer (Idempotent-Replayed: true); another body with the same key is refused (422 IDEMPOTENCY_KEY_REUSED). Kept 24 hours."}]},"delete":{"tags":["Cypress API v1"],"summary":"Cancel (a vehicle with an open offer or a sale in progress is staged for Cypress's review)","responses":{"200":{"description":"With ?dryRun=true: what the cancel would do (close the listing, or stage it for Cypress and pause it); nothing written","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"wouldChange":{"type":"object","properties":{"listingId":{"type":"string"},"vehicleId":{"type":"string"},"status":{"type":"string"},"delistsVehicle":{"type":"boolean","description":"Always false since 1.5.0: the review archives the vehicle"},"staged":{"type":"boolean"}}},"message":{"type":"string"},"note":{"type":"string"}}}}}},"202":{"description":"Staged for Cypress's review (the vehicle has an open offer or a sale in progress)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedResult"}}}},"204":{"description":"Cancelled: the vehicle was not on the market, or (since 1.8.0) it was and had no open offer and no sale in progress, so it was archived at once"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY — an agent's token: taking a car off market is a person's decision (pause it instead); `vehicleId` names the car. Also the common 403s","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already closed, or the vehicle is sold on Cypress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `listings`; takes an API key or, since 1.5.0, a Connect Cypress token acting for a person. Since 1.8.0, as a seller's delist in the app: a car on the market with no open offer and no sale in progress is archived at once and the listing closes CANCELLED (204; VEHICLES.DISPOSITION.RESOLVED, automatic); one with an open offer or a sale in progress is staged for Cypress's review (202): the listing pauses while it waits (LISTINGS.PAUSED), the approval archives the car with its open offers withdrawn and closes the listing (LISTINGS.CANCELLED), a rejection resumes it (LISTINGS.RESUMED). (1.5.0 to 1.7.0 staged every car on the market.) A listing whose car is not on the market closes at once (204). To take a car off market for a while, pause it instead (PATCH status PAUSED).","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: every check, nothing written; answers { dryRun, wouldChange }"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry gets the first answer"}]}},"/api/v1/listings/bulk":{"post":{"tags":["Cypress API v1"],"summary":"Upsert up to 100 listings by your own ids (since 1.5.0)","responses":{"200":{"description":"Per-row results: 201 created on its vehicle, 200 changed (the listing its externalIds name, through the listing command: prices and channels, as a PATCH; a buy-now below the floor 403 BELOW_FLOOR, a price under a live offer or sale 409 CONFLICT), 4xx refused with code and errors. One bad row never fails the batch","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"integer"},"id":{"type":"string"},"code":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}}}},"created":{"type":"integer"},"updated":{"type":"integer"},"refused":{"type":"integer"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"items missing, empty or more than 100","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `listings`. Each row is a POST /api/v1/listings body (vehicleId, prices, channels, listingMode, externalIds), matched by its externalIds. A row whose ids name a listing of your organization changes it (its vehicle and listingMode are not changed); one that names none creates it. Rows run in order. ?dryRun=true checks every row and writes nothing; an Idempotency-Key makes a retry answer the same, once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object"}}},"required":["items"]}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]},"patch":{"tags":["Cypress API v1"],"summary":"Bulk update by listing ids or VINs (≤500, per-item results)","responses":{"200":{"description":"Per-item results. Since 1.5.0 each item runs the listing command, as a single PATCH does: an item whose price would move under a live offer or sale is 409 CONFLICT, a buy-now below the floor 403 BELOW_FLOOR, a buy-now with no floor 422 INVALID; the item carries the code and the batch goes on","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"listingId":{"type":["string","null"]},"vin":{"type":["string","null"]},"status":{"type":"integer"},"code":{"type":"string","enum":["PLANNING_STOCK","PLANNING_NOT_ENABLED","CHANNEL_NOT_GRANTED","CONFLICT","BELOW_FLOOR","INVALID","NOT_FOUND"]},"errors":{"type":"array","items":{"type":"string"}}}}},"updated":{"type":"integer"},"failed":{"type":"integer"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Provide exactly one of listingIds or vins","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"listingIds":{"type":"array","items":{"type":"string"}},"vins":{"type":"array","items":{"type":"string"}},"set":{"$ref":"#/components/schemas/ListingPatch"}},"required":["set"]}}}}}},"/api/v1/members":{"get":{"tags":["Members & connected apps"],"summary":"Your members, people and agents (?status=ACTIVE|ALL)","responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["PERSON","AGENT"]},"name":{"type":"string"},"email":{"type":["string","null"],"description":"null for an agent"},"role":{"type":"string"},"status":{"type":"string"},"userStatus":{"type":"string"},"joinedOn":{"type":"string","format":"date-time"},"agent":{"type":"object","description":"Agents only: the connection that created it","properties":{"key":{"type":"string"},"connectionId":{"type":"string"},"app":{"type":"string"}}}}}},"totalCount":{"type":"integer"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `members:read`. Your organization's members, people and agents alike: each with their name, email (none for an agent), role and status, and for an agent the app that connected it. Give a task or a Mission Control item to one by their user id.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["ACTIVE","ALL"],"default":"ACTIVE"}}]}},"/api/v1/connections":{"get":{"tags":["Members & connected apps"],"summary":"Apps connected through Connect Cypress, with their scopes and agents","responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object"}},"totalCount":{"type":"integer"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `members:read`. The apps your organization connected through Connect Cypress: each with who approved it and when, the scopes granted, the agents it added and their last activity, and whether it is registered with Cypress or named by its own address."}},"/api/v1/connections/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"tags":["Members & connected apps"],"summary":"Disconnect an app: every token ends and its agents are switched off (connections:write, API keys only)","responses":{"204":{"description":"Disconnected"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found, or already disconnected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/automations":{"get":{"tags":["Automation"],"summary":"Your automations, most recently changed first","responses":{"200":{"description":"A page (no graphs: read an automation for them)","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Automation"}},"totalCount":{"type":"integer"},"href":{"type":"string"},"nextHref":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:read`. Each of your organization's own automations: its name, whether it is active, its published version and draft, and when it last ran. Read one with its graphs with GET /api/v1/automations/{id}. Since 1.10.0 `owner=cypress` lists Cypress's own automations that run on your records (switched on and published), and `owner=all` both: what can move your cars without anyone at your organization doing it.","parameters":[{"name":"active","in":"query","schema":{"type":"boolean"}},{"name":"owner","in":"query","schema":{"type":"string","enum":["organization","cypress","all"],"default":"organization"},"description":"Whose (since 1.10.0)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]},"post":{"tags":["Automation"],"summary":"Create an automation with its first draft","responses":{"200":{"description":"With ?dryRun=true: whether it would be created","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"would":{"type":"object"}}}}}},"201":{"description":"The automation","content":{"application/json":{"schema":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: a node an organization's automation may not contain (`findings`), Operation or Planning stages without Planning, or an app acting for a person who builds no automations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the limit (`limit`, `count`): 50 switched on, 200 in all","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: a node type Cypress does not know (`findings`) — or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:write`. Nothing runs until Cypress publishes it. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin. Audited with the credential.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/automations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Automation"],"summary":"One automation, with the graphs of its draft and its published version","responses":{"200":{"description":"The automation","content":{"application/json":{"schema":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found: unknown, Cypress's, or another organization's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:read`."},"patch":{"tags":["Automation"],"summary":"Rename an automation, or change its category or stages","responses":{"200":{"description":"The automation as it now is","content":{"application/json":{"schema":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: the stages of an automation Cypress has published, or a writer rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:write`. The stages belong to the automation, not to a version: once Cypress has published one, they are part of what it approved, and Cypress changes them. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin. Audited with the credential.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/automations/{id}/draft":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"put":{"tags":["Automation"],"summary":"Save the draft","responses":{"200":{"description":"The automation as it now is","content":{"application/json":{"schema":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: a node an organization's automation may not contain (`findings`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: an unknown node type — or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:write`. A draft may be half wired; the publish rules are asked when you submit (and by validate). After a publish, saving starts the next version; the published one keeps running. Saving a submitted draft withdraws it from Cypress's review. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin. Audited with the credential.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["graph"],"properties":{"graph":{"$ref":"#/components/schemas/AutomationGraph"}}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/automations/{id}/validate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Automation"],"summary":"What publishing would say","responses":{"200":{"description":"`errors` would stop Cypress publishing it; `warnings` are the editor's advice and do not","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":["integer","null"],"description":"The version judged; null for a graph sent in the body"},"publishable":{"type":"boolean"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/AutomationFinding"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/AutomationFinding"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:read`. Judges the draft (else the published version), or a `graph` sent in the body before it is saved. Writes nothing.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"graph":{"$ref":"#/components/schemas/AutomationGraph"}}}}}}}},"/api/v1/automations/{id}/dry-run":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Automation"],"summary":"Try a version on your records","responses":{"202":{"description":"One run per record, to read at its href","content":{"application/json":{"schema":{"type":"object","properties":{"automationId":{"type":"string"},"version":{"type":"integer"},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"subjectId":{"type":["string","null"]},"href":{"type":"string"}}}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: no draft (or no published version) to try","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: records that are not yours (`refused`), more than 25, or none for a contact, business or deal automation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:write`. Every step runs as the automation would and writes nothing; a step the rules refuse shows as refused. Judged as your organization's account admin, as the published automation will act. The draft by default. Runs read QUEUED until the worker starts them; one the worker does not go ahead with (a vehicle outside the automation's stages, a record gone) reads DRY_RUN with the reason in `problems`. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin. Audited with the credential. An agent may try automations.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subjectIds":{"type":"array","maxItems":25,"items":{"type":"string"},"description":"Vehicles for a vehicle automation; contacts, businesses or deals of your book for a CRM one. None: one run without a record (a scheduled or fetching automation)"},"version":{"type":"string","enum":["draft","published"]}}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/automations/{id}/submit":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Automation"],"summary":"Ask Cypress to publish the draft","responses":{"202":{"description":"Submitted: the draft's review reads SUBMITTED (submitting again while it waits changes nothing)","content":{"application/json":{"schema":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: an app acting for a person who builds no automations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: no draft since Cypress last published it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: it could not be published as it is (`findings`, as validate says)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:write`. A Cypress manager publishes it (it then replaces the published version and runs while the automation is switched on, as your organization's account admin would act) or sends it back with a note: AUTOMATION.PUBLISHED or AUTOMATION.SENT_BACK tells you which. An agent may submit: that is how an agent proposes an automation. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin. Audited with the credential.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/automations/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Automation"],"summary":"Switch an automation back on","responses":{"200":{"description":"The automation as it now is","content":{"application/json":{"schema":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY: an agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: 50 automations are switched on already","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:write`. What runs is the version Cypress published. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin. Audited with the credential.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/automations/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Automation"],"summary":"Switch an automation off","responses":{"200":{"description":"The automation as it now is","content":{"application/json":{"schema":{"type":"object","properties":{"automation":{"$ref":"#/components/schemas/Automation"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:write`. Nothing it published is lost; a run paused on a Wait step is cancelled when its wait ends. An agent may switch an automation off. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin. Audited with the credential.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/automations/{id}/runs":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Automation"],"summary":"An automation's runs, newest first","responses":{"200":{"description":"A page","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AutomationRun"}},"totalCount":{"type":"integer"},"href":{"type":"string"},"nextHref":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:read`. Each run of the automation: its status (running, succeeded, partial or failed), whether it was a dry run, how many vehicles it looked at and acted on, its problems and its timing. Read a run step by step with GET /api/v1/automations/runs/{runId}/steps.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["RUNNING","SUCCESS","PARTIAL","FAILED","DRY_RUN"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]}},"/api/v1/automations/runs/{runId}":{"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Automation"],"summary":"One run of your automations","responses":{"200":{"description":"The run","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"$ref":"#/components/schemas/AutomationRun"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found: unknown, or a run of Cypress's or another organization's automations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:read`. A dry run you asked for reads QUEUED until the worker starts it."}},"/api/v1/automations/runs/{runId}/steps":{"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Automation"],"summary":"A run's steps, in the order they ran","responses":{"200":{"description":"A page","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AutomationRunStep"}},"totalCount":{"type":"integer"},"href":{"type":"string"},"nextHref":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `automations:read`. A batch run takes a step per node per vehicle: page through them. Steps on another organization's vehicle are never shown.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]}},"/api/v1/automation/manifest":{"get":{"tags":["Automation"],"summary":"Cypress's automation manifest: its domain as data, and the acts and nodes your credential can run","responses":{"200":{"description":"A Himo manifest (format 1)","content":{"application/json":{"schema":{"type":"object","description":"Records, events and lookups describe the domain. `acts` lists the commands your credential's scopes allow (each with its input schema, refusal codes, dry-run mode and scopes), and `nodes` the triggers and the nodes those acts back. A node that runs only inside Cypress is not listed. Answered with an ETag: send it back in If-None-Match and an unchanged manifest is a 304.","properties":{"himo":{"type":"integer","enum":[1]},"system":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"}}},"records":{"type":"object","additionalProperties":{"type":"object"}},"events":{"type":"object","additionalProperties":{"type":"object"}},"reads":{"type":"object","additionalProperties":{"type":"object"}},"acts":{"type":"object","additionalProperties":{"type":"object"}},"lookups":{"type":"object","additionalProperties":{"type":"object"}},"nodes":{"type":"object","additionalProperties":{"type":"object"}}}}}}},"304":{"description":"Not modified: the manifest is the one your If-None-Match names"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"If-None-Match","in":"header","schema":{"type":"string"}}]}},"/api/v1/offers":{"get":{"tags":["Offers"],"summary":"Offers on your vehicles, or the offers you made (?side=SELLER|BUYER&status=&vehicleId=)","responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OfferRead"}},"totalCount":{"type":"integer"},"nextHref":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unknown side or status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"side","in":"query","schema":{"type":"string","enum":["SELLER","BUYER"],"default":"SELLER"}},{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma list of statuses"},{"name":"vehicleId","in":"query","schema":{"type":"string"}},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time"},"description":"Changed at or after this time; the list then answers the newest change first. A sync reads the event feed (GET /api/v1/events) for changes as they happen, and this to backfill or reconcile. Since 1.5.0."}]}},"/api/v1/offers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Offers"],"summary":"One offer","responses":{"200":{"description":"The offer","content":{"application/json":{"schema":{"type":"object","properties":{"offer":{"$ref":"#/components/schemas/OfferRead"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `offers:read`. One offer as your side sees it: SELLER (on your vehicle) or BUYER (one you made), the vehicle, the amount, its status, the counter amount when there is one, and its link in the app. Read it before accepting, declining or countering, to act on its current status; list_offers lists them by side or status. No buyer identity is returned."}},"/api/v1/offers/{id}/accept":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Offers"],"summary":"Accept an offer on your vehicle (below the floor: 403 PEOPLE_ONLY)","responses":{"200":{"description":"Decided (or, with ?dryRun=true, what would happen)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferDecision"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY, BELOW_FLOOR or POLICY_DENIED; also the common 403s","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the offer is no longer open — or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/offers/{id}/decline":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Offers"],"summary":"Decline an offer on your vehicle","responses":{"200":{"description":"Decided (or, with ?dryRun=true, what would happen)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferDecision"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY, BELOW_FLOOR or POLICY_DENIED; also the common 403s","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the offer is no longer open — or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500}}}}}}}},"/api/v1/offers/{id}/counter":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Offers"],"summary":"Counter an offer on your vehicle (below the floor: 403 PEOPLE_ONLY)","responses":{"200":{"description":"Decided (or, with ?dryRun=true, what would happen)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferDecision"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY, BELOW_FLOOR or POLICY_DENIED; also the common 403s","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the offer is no longer open — or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number"},"message":{"type":"string","maxLength":1000}}}}}}}},"/api/v1/offers/{id}/withdraw":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Offers"],"summary":"Withdraw an open offer you made","responses":{"200":{"description":"Decided (or, with ?dryRun=true, what would happen)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferDecision"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY, BELOW_FLOOR or POLICY_DENIED; also the common 403s","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the offer is no longer open — or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/contacts":{"get":{"tags":["CRM"],"summary":"Your organization's contacts, the most recently changed first","responses":{"200":{"description":"A page","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"totalCount":{"type":"integer"},"href":{"type":"string"},"nextHref":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed: an unknown filter or value — or `owner=me` with an API key (it acts as nobody)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). Filters combine.","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"The address, either name or the company name, ignoring case"},{"name":"lifecycle","in":"query","schema":{"type":"string"},"description":"Comma list of PROSPECT, REACHED, ENGAGED, ON_PLATFORM, ACTIVE, DORMANT"},{"name":"kind","in":"query","schema":{"type":"string"},"description":"Comma list of ORG_PROSPECT, CONSUMER, ON_PLATFORM"},{"name":"owner","in":"query","schema":{"type":"string"},"description":"A member's id, `me` (the person or agent the token acts as) or `none`"},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"businessId","in":"query","schema":{"type":"string"}},{"name":"externalId","in":"query","schema":{"type":"string"},"description":"<source>:<id> — the record your system calls by that id (zero or one item). Since 1.5.0."},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time"},"description":"Changed at or after"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]},"post":{"tags":["CRM"],"summary":"Create a contact, or open the one with that address","responses":{"200":{"description":"The address was already in your book: that contact, blanks filled (or, with ?dryRun=true, what it would do)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"created":{"type":"boolean","const":false}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"created":{"type":"boolean","const":true}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`businessId` is not a business of your book","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code EXTERNAL_ID_TAKEN — an id in `externalIds` names another contact of your organization (`taken` names it), nothing is written; or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: not an address, or an owner who is not an active member — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. A contact made through the API is never matched to a Cypress account with its address: it holds what you sent, and nothing about anyone else's membership.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/contacts/bulk":{"post":{"tags":["CRM"],"summary":"Upsert up to 100 contacts by your own ids","responses":{"200":{"description":"One result per row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpsertResult"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The envelope failed: `items` is 1 to 100 rows (a bad row answers in its own result) — or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. Since 1.5.0. Each row is matched by its `externalIds`: a row whose ids name a contact of your organization changes it, as a PATCH would (its address too); a row whose ids name none is created, or opens the contact with that address, as a POST does. Ids naming two different contacts refuse that row (EXTERNAL_ID_TAKEN). Every row goes through the same command as one at a time; one bad row never fails the batch.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/ContactWrite"}}}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Check every row, write nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/contacts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["CRM"],"summary":"One contact","responses":{"200":{"description":"The contact","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's contact answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). The whole contact: name, emails and phones, company, kind and lifecycle, tags, owner, last activity and its link in the app. Read one contact by its id; list_contacts searches by name, email, tag or lifecycle."},"patch":{"tags":["CRM"],"summary":"Change a contact","responses":{"200":{"description":"The contact as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"created":{"type":"boolean","const":false}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found — or `businessId` is not a business of your book","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code EXTERNAL_ID_TAKEN — an id in `externalIds` names another contact of your organization (`taken` names it), nothing is written; or code CONFLICT: another contact of your book uses that address (`conflictContactId` names it) — or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: an owner who is not an active member — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactPatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/businesses":{"get":{"tags":["CRM"],"summary":"Your organization's businesses, the most recently changed first","responses":{"200":{"description":"A page","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Business"}},"totalCount":{"type":"integer"},"href":{"type":"string"},"nextHref":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed: an unknown filter — or `owner=me` with an API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). Filters combine.","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"The name or the domain, ignoring case"},{"name":"owner","in":"query","schema":{"type":"string"},"description":"A member's id, `me` or `none`"},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"externalId","in":"query","schema":{"type":"string"},"description":"<source>:<id> — the record your system calls by that id (zero or one item). Since 1.5.0."},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]},"post":{"tags":["CRM"],"summary":"Create a business, or open the one with that name or domain","responses":{"200":{"description":"Your book already had it: that business, blanks filled (or, with ?dryRun=true, what it would do)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"business":{"$ref":"#/components/schemas/Business"},"created":{"type":"boolean","const":false}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/Business"},"created":{"type":"boolean","const":true}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code EXTERNAL_ID_TAKEN — an id in `externalIds` names another business of your organization (`taken` names it), nothing is written; or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: an owner who is not an active member — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/businesses/bulk":{"post":{"tags":["CRM"],"summary":"Upsert up to 100 businesses by your own ids","responses":{"200":{"description":"One result per row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpsertResult"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The envelope failed: `items` is 1 to 100 rows (a bad row answers in its own result) — or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. Since 1.5.0. Each row is matched by its `externalIds`: a row whose ids name a business of your organization changes it, as a PATCH would; a row whose ids name none is created, or opens the business with that name or domain. Ids naming two different businesses refuse that row (EXTERNAL_ID_TAKEN). Every row goes through the same command as one at a time; one bad row never fails the batch.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/BusinessWrite"}}}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Check every row, write nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/businesses/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["CRM"],"summary":"One business","responses":{"200":{"description":"The business","content":{"application/json":{"schema":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/Business"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's business answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). The whole company: its name, domain, owner, tags, external ids, last activity and its link in the app. list_businesses searches them by name, owner or tag."},"patch":{"tags":["CRM"],"summary":"Change a business","responses":{"200":{"description":"The business as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"business":{"$ref":"#/components/schemas/Business"},"created":{"type":"boolean","const":false}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code EXTERNAL_ID_TAKEN — an id in `externalIds` names another business of your organization (`taken` names it), nothing is written; or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: an empty name or an owner who is not an active member — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessPatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/deals":{"get":{"tags":["CRM"],"summary":"Your organization's deals, the most recently changed first","responses":{"200":{"description":"A page","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Deal"}},"totalCount":{"type":"integer"},"href":{"type":"string"},"nextHref":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed: an unknown filter or value — or `owner=me` with an API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). Filters combine.","parameters":[{"name":"stage","in":"query","schema":{"type":"string"},"description":"Comma list of stages"},{"name":"kind","in":"query","schema":{"type":"string","enum":["VEHICLE_SALE","ONBOARDING"]}},{"name":"owner","in":"query","schema":{"type":"string"},"description":"A member's id, `me` or `none`"},{"name":"contactId","in":"query","schema":{"type":"string"}},{"name":"businessId","in":"query","schema":{"type":"string"}},{"name":"vehicleId","in":"query","schema":{"type":"string"},"description":"Deals that carry this vehicle"},{"name":"externalId","in":"query","schema":{"type":"string"},"description":"<source>:<id> — the record your system calls by that id (zero or one item). Since 1.5.0."},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]},"post":{"tags":["CRM"],"summary":"Open a deal","responses":{"200":{"description":"With ?dryRun=true: what it would write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"201":{"description":"Opened","content":{"application/json":{"schema":{"type":"object","properties":{"deal":{"$ref":"#/components/schemas/Deal"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: vehicles that are not yours to sell, named in `refused`; also the common 403s","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"A contact, business, promotion, campaign or channel that is not of your book","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code EXTERNAL_ID_TAKEN — an id in `externalIds` names another deal of your organization (`taken` names it), nothing is written; or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: with nobody, an onboarding deal without a business or with vehicles, an owner who is not an active member — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/deals/stages":{"get":{"tags":["CRM"],"summary":"The two pipelines","responses":{"200":{"description":"The pipelines","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealPipelines"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). The two deal pipelines (selling and buying) and the stages of each, in order, with which stages close a deal won or lost. Read it before move_deal_stage, to name a stage that exists."}},"/api/v1/deals/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["CRM"],"summary":"One deal","responses":{"200":{"description":"The deal","content":{"application/json":{"schema":{"type":"object","properties":{"deal":{"$ref":"#/components/schemas/Deal"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's deal answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). The whole deal: its kind, stage and since when, company, owner, expected amount, vehicles, lost reason or close date, and its link in the app. Read one deal by its id; list_deals filters by stage, kind or owner."},"patch":{"tags":["CRM"],"summary":"Change a deal (never its stage)","responses":{"200":{"description":"The deal as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"deal":{"$ref":"#/components/schemas/Deal"}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found — or a contact, business, promotion, campaign or channel that is not of your book","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code EXTERNAL_ID_TAKEN — an id in `externalIds` names another deal of your organization (`taken` names it), nothing is written; or code CONFLICT: a kind the deal cannot survive — or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: with nobody, or an owner who is not an active member — or validation failed (a `stage` included), or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. Recorded in the deal's history.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealPatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/deals/{id}/stage":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["CRM"],"summary":"Move a deal by hand","responses":{"200":{"description":"The deal as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"deal":{"$ref":"#/components/schemas/Deal"}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: a stage the offer and closing flow owns, into or out of (the message names the real action) — or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: LOST without a `lostReason` — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. Within the stages marked `manual` in GET /api/v1/deals/stages, to LOST with a reason, or back from LOST. Starts your CRM automations as a move on the board does.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealStageMove"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/contacts/{id}/notes":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["CRM"],"summary":"The notes on a contact, pinned first then newest","responses":{"200":{"description":"Its notes (at most 200)","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's contact answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`)."},"post":{"tags":["CRM"],"summary":"Add a note to a contact","responses":{"200":{"description":"With ?dryRun=true: what it would write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed (an empty note) — or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. Written under your token's person or agent, or your key's name.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/contacts/{id}/notes/{noteId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"noteId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"tags":["CRM"],"summary":"Reword or pin a note (its author only)","responses":{"200":{"description":"The note as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: only the person or agent who wrote a note may edit it (never an API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (a note of another record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotePatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]},"delete":{"tags":["CRM"],"summary":"Remove a note (its author, or Cypress)","responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"204":{"description":"Removed"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: only the person or agent who wrote it, or Cypress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/businesses/{id}/notes":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["CRM"],"summary":"The notes on a business, pinned first then newest","responses":{"200":{"description":"Its notes (at most 200)","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's business answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`)."},"post":{"tags":["CRM"],"summary":"Add a note to a business","responses":{"200":{"description":"With ?dryRun=true: what it would write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed (an empty note) — or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. Written under your token's person or agent, or your key's name.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/businesses/{id}/notes/{noteId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"noteId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"tags":["CRM"],"summary":"Reword or pin a note (its author only)","responses":{"200":{"description":"The note as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: only the person or agent who wrote a note may edit it (never an API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (a note of another record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotePatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]},"delete":{"tags":["CRM"],"summary":"Remove a note (its author, or Cypress)","responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"204":{"description":"Removed"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: only the person or agent who wrote it, or Cypress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/deals/{id}/notes":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["CRM"],"summary":"The notes on a deal, pinned first then newest","responses":{"200":{"description":"Its notes (at most 200)","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Note"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's deal answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`)."},"post":{"tags":["CRM"],"summary":"Add a note to a deal","responses":{"200":{"description":"With ?dryRun=true: what it would write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed (an empty note) — or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. Written under your token's person or agent, or your key's name.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NoteWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/deals/{id}/notes/{noteId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"noteId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"tags":["CRM"],"summary":"Reword or pin a note (its author only)","responses":{"200":{"description":"The note as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"note":{"$ref":"#/components/schemas/Note"}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: only the person or agent who wrote a note may edit it (never an API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (a note of another record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotePatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]},"delete":{"tags":["CRM"],"summary":"Remove a note (its author, or Cypress)","responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"204":{"description":"Removed"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: only the person or agent who wrote it, or Cypress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/contacts/{id}/interactions":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["CRM"],"summary":"What happened with a contact, newest first","responses":{"200":{"description":"Its interactions (its own; at most 200)","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Interaction"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). The calls, emails, meetings and campaign emails on the contact, newest first (at most 200), each with who it was with, what was said and when, and whether a person, an agent or an integration logged it."},"post":{"tags":["CRM"],"summary":"Log an interaction on a contact","responses":{"200":{"description":"With ?dryRun=true: what it would write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"201":{"description":"Logged","content":{"application/json":{"schema":{"type":"object","properties":{"interaction":{"$ref":"#/components/schemas/Interaction"},"followUp":{"type":["object","null"],"properties":{"id":{"type":"string"},"href":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found — or a deal of another book","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: a person not of this record, or a follow-up the task rules refuse — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. \"Last activity\" (and on a contact, for an outbound one, \"last contacted\") only moves forward.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractionWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/contacts/{id}/interactions/{interactionId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"interactionId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"tags":["CRM"],"summary":"Correct a logged interaction","responses":{"200":{"description":"The interaction as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"interaction":{"$ref":"#/components/schemas/Interaction"}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (one the contact does not show answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: a delivered campaign email, never changed — or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractionPatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]},"delete":{"tags":["CRM"],"summary":"Remove a logged interaction","responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"204":{"description":"Removed"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: a delivered campaign email, never removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/businesses/{id}/interactions":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["CRM"],"summary":"What happened with a business, newest first","responses":{"200":{"description":"Its interactions (logged against it or with one of its people; at most 200)","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Interaction"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). The calls, emails, meetings and campaign emails on the business, newest first (at most 200), each with who it was with, what was said and when, and whether a person, an agent or an integration logged it."},"post":{"tags":["CRM"],"summary":"Log an interaction on a business","responses":{"200":{"description":"With ?dryRun=true: what it would write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"201":{"description":"Logged","content":{"application/json":{"schema":{"type":"object","properties":{"interaction":{"$ref":"#/components/schemas/Interaction"},"followUp":{"type":["object","null"],"properties":{"id":{"type":"string"},"href":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found — or a deal of another book","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: a person not of this record, or a follow-up the task rules refuse — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. \"Last activity\" (and on a contact, for an outbound one, \"last contacted\") only moves forward.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractionWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/businesses/{id}/interactions/{interactionId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"interactionId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"tags":["CRM"],"summary":"Correct a logged interaction","responses":{"200":{"description":"The interaction as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"interaction":{"$ref":"#/components/schemas/Interaction"}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (one the business does not show answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: a delivered campaign email, never changed — or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractionPatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]},"delete":{"tags":["CRM"],"summary":"Remove a logged interaction","responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"204":{"description":"Removed"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: a delivered campaign email, never removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/deals/{id}/interactions":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["CRM"],"summary":"What happened with a deal, newest first","responses":{"200":{"description":"Its interactions (logged against it, or with one of its people and not filed on another deal; at most 200)","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Interaction"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). The calls, emails, meetings and campaign emails on the deal, newest first (at most 200), each with who it was with, what was said and when, and whether a person, an agent or an integration logged it."},"post":{"tags":["CRM"],"summary":"Log an interaction on a deal","responses":{"200":{"description":"With ?dryRun=true: what it would write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"201":{"description":"Logged","content":{"application/json":{"schema":{"type":"object","properties":{"interaction":{"$ref":"#/components/schemas/Interaction"},"followUp":{"type":["object","null"],"properties":{"id":{"type":"string"},"href":{"type":"string"}}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found — or a deal of another book","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: a person not of this record, or a follow-up the task rules refuse — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. \"Last activity\" (and on a contact, for an outbound one, \"last contacted\") only moves forward.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractionWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/deals/{id}/interactions/{interactionId}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"interactionId","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"tags":["CRM"],"summary":"Correct a logged interaction","responses":{"200":{"description":"The interaction as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"interaction":{"$ref":"#/components/schemas/Interaction"}}},{"$ref":"#/components/schemas/CrmDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (one the deal does not show answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: a delivered campaign email, never changed — or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InteractionPatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]},"delete":{"tags":["CRM"],"summary":"Remove a logged interaction","responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrmDryRun"}}}},"204":{"description":"Removed"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: a delivered campaign email, never removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/contacts/tags":{"get":{"tags":["CRM"],"summary":"The tags your contacts carry, the most used first","responses":{"200":{"description":"The vocabulary (at most 500)","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string"},"count":{"type":"integer"}}}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). Reuse these rather than minting near-duplicates."},"post":{"tags":["CRM"],"summary":"Add and remove tags over a selection of contacts","responses":{"200":{"description":"What changed (or, with ?dryRun=true, what would)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagEditResult"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: nothing to add or remove — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. Each change is recorded in the record's history; \"last activity\" does not move.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagEdit"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/businesses/tags":{"get":{"tags":["CRM"],"summary":"The tags your businesses carry, the most used first","responses":{"200":{"description":"The vocabulary (at most 500)","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"tag":{"type":"string"},"count":{"type":"integer"}}}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:read` (or `crm:write`). Reuse these rather than minting near-duplicates."},"post":{"tags":["CRM"],"summary":"Add and remove tags over a selection of businesses","responses":{"200":{"description":"What changed (or, with ?dryRun=true, what would)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagEditResult"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: nothing to add or remove — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write`. Each change is recorded in the record's history; \"last activity\" does not move.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagEdit"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/contacts/{id}/outreach":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["CRM"],"summary":"Email a contact, in the name of the person your token acts for","responses":{"200":{"description":"With ?dryRun=true: whether it would go out, and if not why","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"sent":{"type":"boolean"},"blocked":{"type":["object","null"],"properties":{"code":{"type":"string","enum":["SUPPRESSED","NO_CONSENT"]},"reason":{"type":"string"}}}}}}}},"201":{"description":"Queued for delivery","content":{"application/json":{"schema":{"type":"object","properties":{"outreach":{"$ref":"#/components/schemas/Interaction"},"sent":{"type":"boolean","const":true}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY: an agent or an API key; an email in your organization's name goes out from a person","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found — or a deal of another book","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Held back, and recorded: code SUPPRESSED (an unsubscribe or a bounce) or NO_CONSENT (a private individual who has not opted in to hear from you); `outreach` is the recorded attempt — or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The email could not be queued; the recorded attempt says so. Try again","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `crm:write` and a Connect Cypress token acting for a person: the email goes out in their name, replies to their address. Suppression and consumer consent are checked first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject","body"],"additionalProperties":false,"properties":{"subject":{"type":"string","minLength":1,"maxLength":300},"body":{"type":"string","minLength":1,"maxLength":20000},"dealId":{"type":["string","null"]}}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/tasks":{"get":{"tags":["Tasks"],"summary":"Your organization's tasks, soonest due first (undated last)","responses":{"200":{"description":"A page","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"totalCount":{"type":"integer"},"href":{"type":"string"},"nextHref":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed: an unknown filter, a bad date — or `assignee=me` with an API key (it acts as nobody)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `tasks:read` (or `tasks:write`). Filters combine.","parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma list of OPEN, DONE, CANCELLED"},{"name":"source","in":"query","schema":{"type":"string"},"description":"Comma list of PERSON, AUTOMATION, AGENT"},{"name":"assignee","in":"query","schema":{"type":"string"},"description":"A member's id, `me` (the person or agent the token acts as) or `none` (unassigned)"},{"name":"dueAfter","in":"query","schema":{"type":"string","format":"date-time"},"description":"Due at or after"},{"name":"dueBefore","in":"query","schema":{"type":"string","format":"date-time"},"description":"Due before"},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time"},"description":"Changed at or after this time; the list then answers the newest change first. A sync reads the event feed (GET /api/v1/events) for changes as they happen, and this to backfill or reconcile. Since 1.5.0."},{"name":"contactId","in":"query","schema":{"type":"string"}},{"name":"dealId","in":"query","schema":{"type":"string"}},{"name":"businessId","in":"query","schema":{"type":"string"}},{"name":"vehicleId","in":"query","schema":{"type":"string"}},{"name":"planningGoalId","in":"query","schema":{"type":"string"}},{"name":"saleWindowKey","in":"query","schema":{"type":"string"}},{"name":"lotKey","in":"query","schema":{"type":"string"}},{"name":"buyTargetId","in":"query","schema":{"type":"string"}},{"name":"playKey","in":"query","schema":{"type":"string"}},{"name":"conversationRoomId","in":"query","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,64}$"},"description":"Since 1.9.0. The tasks made from one conversation, by its Huddle room's id"},{"name":"externalId","in":"query","schema":{"type":"string"},"description":"<source>:<id> — the record your system calls by that id (zero or one item). Since 1.5.0."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]},"post":{"tags":["Tasks"],"summary":"Create a task","responses":{"200":{"description":"With ?dryRun=true: what it would write","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskDryRun"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"code NOT_FOUND: a linked record is not your organization's (or does not exist)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code EXTERNAL_ID_TAKEN — an id in `externalIds` names another task of your organization (`taken` names it), nothing is written; or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: no title, no link, or an assignee who is not an active member — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `tasks:write`. Sends TASK.CREATED, and TASK.ASSIGNED when the task is handed to someone other than the caller.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/tasks/bulk":{"post":{"tags":["Tasks"],"summary":"Upsert up to 100 tasks by your own ids","responses":{"200":{"description":"One result per row","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpsertResult"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The envelope failed: `items` is 1 to 100 rows (a bad row answers in its own result) — or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `tasks:write`. Since 1.5.0. Each row is matched by its `externalIds`: a row whose ids name a task of your organization changes it, as a PATCH would (its title, notes, due date, channel, assignee and business; what else it is about is set when it is made); a row whose ids name none is created. Ids naming two different tasks refuse that row (EXTERNAL_ID_TAKEN). Every row goes through the same command as one at a time; one bad row never fails the batch.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/TaskWrite"}}}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Check every row, write nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/tasks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Tasks"],"summary":"One task","responses":{"200":{"description":"The task","content":{"application/json":{"schema":{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's task answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `tasks:read` (or `tasks:write`). The whole task: its title, notes, status, due date, channel, who it is assigned to and who made it, what it belongs to, and its link in the app. Read one task by its id (from list_tasks or a TASK.* webhook); list_tasks finds them by status, assignee or due date."},"patch":{"tags":["Tasks"],"summary":"Change a task","responses":{"200":{"description":"The task as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"}}},{"$ref":"#/components/schemas/TaskDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code EXTERNAL_ID_TAKEN — an id in `externalIds` names another task of your organization (`taken` names it), nothing is written; or IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID — or validation failed (nothing to change, an unknown field), or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `tasks:write`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskPatch"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]},"delete":{"tags":["Tasks"],"summary":"Remove a task","responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskDryRun"}}}},"204":{"description":"Removed"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `tasks:write`. Sends no event.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/tasks/{id}/complete":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Tasks"],"summary":"Mark a task done","responses":{"200":{"description":"The task as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"}}},{"$ref":"#/components/schemas/TaskDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed (the body is empty or `{}`), or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `tasks:write`. Records who finished it (`completedBy`) and sends TASK.COMPLETED.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/tasks/{id}/reassign":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Tasks"],"summary":"Give a task to a member, or to nobody","responses":{"200":{"description":"The task as it is now (or, with ?dryRun=true, the changes)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"task":{"$ref":"#/components/schemas/Task"}}},{"$ref":"#/components/schemas/TaskDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: not an active member of your organization — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `tasks:write`. Sends TASK.ASSIGNED when the task is handed to someone other than the caller.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["assigneeUserId"],"additionalProperties":false,"properties":{"assigneeUserId":{"type":["string","null"]}}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/insights":{"get":{"tags":["Insights"],"summary":"Insights on a vehicle or a buy target","responses":{"200":{"description":"The insights","content":{"application/json":{"schema":{"type":"object","properties":{"vehicleId":{"type":"string"},"targetId":{"type":"string"},"view":{"type":"string","enum":["owner","buyer"],"description":"Vehicles only: `owner` for your own vehicle, `buyer` for another organization's car on sale"},"insights":{"type":"array","items":{"$ref":"#/components/schemas/Insight"}},"links":{"$ref":"#/components/schemas/AppLinks"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found: an unknown id, another organization's target, or another organization's vehicle that is not for sale","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed: name exactly one of vehicleId and targetId; an unknown kind","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"code RATE_LIMITED: 30 insight requests a minute per credential (Retry-After: 60)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `insights:read`. Your own vehicle: `sell-hold`, `pricing`, `campaign`, `sequoia`. Another organization's car on sale: `listing` only. Your own buy target: `buy-guide`, `sequoia`. `kinds` narrows the list (a kind that does not apply is left out).","parameters":[{"name":"vehicleId","in":"query","schema":{"type":"string"}},{"name":"targetId","in":"query","schema":{"type":"string"}},{"name":"kinds","in":"query","schema":{"type":"string"},"description":"Comma list of sell-hold, pricing, campaign, sequoia, listing, buy-guide"}]}},"/api/v1/campaigns":{"post":{"tags":["Marketing"],"summary":"Create a campaign (always a draft)","responses":{"200":{"description":"With ?dryRun=true: what would be created","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"would":{"type":"object"}}}}}},"201":{"description":"The campaign","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"$ref":"#/components/schemas/Campaign"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY: a pasted address list — or POLICY_DENIED: the platform directory, or an app acting for a person who is not a Fleet Manager or admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"code NOT_FOUND: a promotion that is not yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: a message with no subject or body, or cars that are not yours (`refused`) — or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `marketing:write`. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin; an agent drafts and pauses but never activates or sends (PEOPLE_ONLY). Audited with the credential.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]},"get":{"tags":["Marketing"],"summary":"Your campaigns, newest first, with the people each reached","responses":{"200":{"description":"A page","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}},"totalCount":{"type":"integer"},"href":{"type":"string"},"nextHref":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed: an unknown filter or value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `marketing:read`.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED"]}},{"name":"kind","in":"query","schema":{"type":"string","enum":["PROMOTION","CRM"]}},{"name":"content","in":"query","schema":{"type":"string","enum":["PROMOTION","INVENTORY","MESSAGE"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]}},"/api/v1/campaigns/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Marketing"],"summary":"One campaign","responses":{"200":{"description":"The campaign","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"$ref":"#/components/schemas/Campaign"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found: unknown, or another organization's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `marketing:read`. The whole campaign: its kind and goal, subject, vehicles, audience, schedule, whether and why it is paused, the people it reached, and its link in the app. list_campaigns gives the short form of each."},"patch":{"tags":["Marketing"],"summary":"Edit a campaign","responses":{"200":{"description":"The campaign as it now is","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"$ref":"#/components/schemas/Campaign"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY or POLICY_DENIED, as for create","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID — or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `marketing:write`. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin; an agent drafts and pauses but never activates or sends (PEOPLE_ONLY). Audited with the credential. The next send moves only when the schedule actually changes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignWrite"}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]},"delete":{"tags":["Marketing"],"summary":"Delete a campaign that never sent","responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: it has sent; pause it instead (the send record is what unsubscribes were judged against)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `marketing:write`. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin; an agent drafts and pauses but never activates or sends (PEOPLE_ONLY). Audited with the credential.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/campaigns/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Marketing"],"summary":"Activate (or resume) a campaign","responses":{"200":{"description":"The campaign as it now is","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"$ref":"#/components/schemas/Campaign"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY: an agent — or POLICY_DENIED: a campaign addressing the platform directory, or a writer rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: not ready (`blockers`: nothing to say, no cars, every car sold, …)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `marketing:write`. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin; an agent drafts and pauses but never activates or sends (PEOPLE_ONLY). Audited with the credential. Readiness is judged as the app judges it.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/campaigns/{id}/pause":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Marketing"],"summary":"Pause a campaign","responses":{"200":{"description":"The campaign as it now is: a person's pause (pausedReason MANUAL), which does not resume on its own","content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"$ref":"#/components/schemas/Campaign"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `marketing:write`. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin; an agent drafts and pauses but never activates or sends (PEOPLE_ONLY). Audited with the credential. An agent may pause.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/campaigns/{id}/send":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Marketing"],"summary":"Send a campaign now, outside its schedule","responses":{"202":{"description":"Queued for delivery (`sent: false` when the audience resolved to nobody)","content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"sendId":{"type":["string","null"]},"recipientCount":{"type":"integer"},"sent":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code PEOPLE_ONLY: an agent — or POLICY_DENIED: the platform directory, or a writer rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: nothing to send (`blockers`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `marketing:write`. An API key acts as your organization's admin; an app acting for a person needs that person to be a Fleet Manager or an admin; an agent drafts and pauses but never activates or sends (PEOPLE_ONLY). Audited with the credential. The audience resolves and suppression applies exactly as for a scheduled send; the schedule is left alone.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/campaigns/{id}/sends":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Marketing"],"summary":"A campaign's sends, in people","responses":{"200":{"description":"Newest first, at most 100; a test send is marked by its trigger","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CampaignSend"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `marketing:read`. Each time the campaign went out, newest first (at most 100): when, what started it (its schedule, a person, a test), and the people it reached, counted as people, never as rows."}},"/api/v1/campaigns/{id}/interest":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Marketing"],"summary":"Your cars a campaign brought people to","responses":{"200":{"description":"By car, most people first","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CampaignInterest"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `marketing:read`. Views, saves and offers from people who came through the campaign's mail, on your own cars only (a visitor who went on to another seller's car is not your campaign's to report). Test sends never count."}},"/api/v1/message-templates":{"get":{"tags":["Marketing"],"summary":"Your message templates and Cypress's base library","responses":{"200":{"description":"Your own templates, then the base library (published only)","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MessageTemplate"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `marketing:read`. Your organization's own message templates first, then Cypress's published base library: each with its name, subject, body and the fields it fills. A campaign names one by its id."}},"/api/v1/closings":{"get":{"tags":["Closings"],"summary":"The closings you are a party to, newest first","responses":{"200":{"description":"A page","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Closing"}},"summary":{"type":"object","description":"Since 1.9.0. Your open closings on the side and vehicle asked for, read as a whole, on every page and whatever the status, yourTurn, updatedAfter or sort (up to the 500 newest). Worked out: use it as given.","properties":{"open":{"type":"integer"},"yourTurn":{"type":"integer","description":"Of the open ones, those waiting on your side"},"late":{"type":"integer","description":"Of the open ones, those whose current step is past its deadline, whoever's turn it is"},"mostOverdue":{"type":["object","null"],"description":"The longest past due of all, whoever's turn it is (`turn`, `yourTurn`): a closing waiting on the other side can be it. Null when none is late","properties":{"closingId":{"type":"string"},"step":{"type":"string","description":"The current step's key"},"turn":{"type":["string","null"],"enum":["SELLER","BUYER","CYPRESS",null],"description":"Who must act now"},"yourTurn":{"type":"boolean"},"dueDate":{"type":["string","null"],"format":"date-time"},"lateHours":{"type":["integer","null"]},"daysLate":{"type":["integer","null"]},"late":{"type":["string","null"]},"dueInHours":{"type":["integer","null"]},"dueInDays":{"type":["integer","null"]}}},"yourTurnFirst":{"type":["object","null"],"description":"The one to act on first yourself: your turn, the longest past due, else the soonest due. Null when none waits on you","properties":{"closingId":{"type":"string"},"step":{"type":"string","description":"The current step's key"},"turn":{"type":["string","null"],"enum":["SELLER","BUYER","CYPRESS",null],"description":"Who must act now"},"yourTurn":{"type":"boolean"},"dueDate":{"type":["string","null"],"format":"date-time"},"lateHours":{"type":["integer","null"]},"daysLate":{"type":["integer","null"]},"late":{"type":["string","null"]},"dueInHours":{"type":["integer","null"]},"dueInDays":{"type":["integer","null"]}}}}},"totalCount":{"type":"integer"},"href":{"type":"string"},"nextHref":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed: an unknown filter or value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `closing:read`. Each closing as your side sees it: the vehicle, the counterparty, the price, the current step and whose turn it is, with its link in the app. Since 1.9.0 each open step says how late it is (`lateHours`, `daysLate`, `late`) or how long it has left (`dueInHours`, `dueInDays`), `urgency` says it for the current step, and `summary` names the most overdue closing of all (whoever's turn it is) and yours to act on first, worked out: use them as given. Filter by status, side, vehicle or `yourTurn`; `sort=urgency` puts your turn first, then the latest; read one in full, its steps and requirements, with GET /api/v1/closings/{id}.","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["IN_PROGRESS","COMPLETED","CANCELLED"]}},{"name":"side","in":"query","schema":{"type":"string","enum":["SELLER","BUYER"]}},{"name":"vehicleId","in":"query","schema":{"type":"string"}},{"name":"yourTurn","in":"query","schema":{"type":"boolean"},"description":"Only open closings with a step that is your turn"},{"name":"sort","in":"query","schema":{"type":"string","enum":["newest","urgency"],"default":"newest"},"description":"newest (the default): the newest closing first. urgency: your turn first, then by the current step's deadline (the longest past due first, then the soonest due, to the millisecond); a step with no deadline after, a closing with nothing open last (over the 500 newest closings the filters match). Since 1.9.0"},{"name":"updatedAfter","in":"query","schema":{"type":"string","format":"date-time"},"description":"Changed at or after this time; the list then answers the newest change first. A sync reads the event feed (GET /api/v1/events) for changes as they happen, and this to backfill or reconcile. Since 1.5.0."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]}},"/api/v1/closings/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Closings"],"summary":"One closing, as your side sees it","responses":{"200":{"description":"The closing","content":{"application/json":{"schema":{"type":"object","properties":{"closing":{"$ref":"#/components/schemas/Closing"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found: unknown, or a closing you are not a party to","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `closing:read`. The whole closing, as your side sees it: the vehicle, the counterparty as the app shows it, the price, the current step and every step with whose turn it is, the requirements still open, and its link in the app. list_closings gives the short form of each; read one here before reminding, requesting a document or marking a step."}},"/api/v1/closings/{id}/steps/{stepKey}/remind":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"stepKey","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Closings"],"summary":"Remind whoever's turn a step is","responses":{"200":{"description":"With ?dryRun=true: what would happen","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"would":{"type":"object"}}}}}},"202":{"description":"Reminded","content":{"application/json":{"schema":{"type":"object","properties":{"closingId":{"type":"string"},"step":{"type":"string"},"turn":{"type":"string","enum":["SELLER","BUYER","CYPRESS"]},"notified":{"type":"integer","description":"How many people were told"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found: not your closing, or a step your side does not see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the closing is over, the step waits on no one, no one can be told, or your organization reminded about this step in the last hour (`retryAfter`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed: the body takes nothing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `closing:write`. The seller's fleet managers and admins (with the account manager copied), the buyer, or Cypress hear it, through the notifications they already get. Once an hour per step for your organization. Audited.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/closings/{id}/steps/{stepKey}/actions":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"stepKey","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Closings"],"summary":"Mark progress on a step that is your side's","responses":{"200":{"description":"Done (or, with ?dryRun=true, `{ dryRun, would }`)","content":{"application/json":{"schema":{"type":"object","properties":{"closingId":{"type":"string"},"step":{"type":"string"},"action":{"type":"string"},"status":{"type":"string","description":"The step now"},"closingStatus":{"type":"string","description":"The closing now: a confirmed pickup completes it"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: the step is the other side's to mark — or an individual buyer's profile lacks the address the papers need (`missingProfileFields`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found: not your closing, or a step your side does not see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the closing is over, the step is not open yet or already complete, or a requirement is not met (`missing`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: an action this step does not take from your side — or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `closing:write`. The app's own step action runs, with the same checks, notifications and events. Seller: `confirm_funds` (CONFIRM_FUNDS; `method` ACH or CHECK, `reference`, `carrier`, `note`), `issue_gate_pass` (GATE_PASS; `address`, `city`, `state`, `zip`), `submit_title_tracking` (TITLE; `carrier`, `trackingNumber`, `titleHolder`, `titleHolderType`, `titleHolderAddress`), `confirm_check_cleared` (TITLE). Buyer: `confirm_pickup` (PICKUP), which completes the sale. Cypress's own actions are never offered. Audited with the credential.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["confirm_funds","issue_gate_pass","submit_title_tracking","confirm_check_cleared","confirm_pickup"]},"method":{"type":"string","enum":["ACH","CHECK"]},"reference":{"type":"string","maxLength":200},"carrier":{"type":"string","maxLength":100},"note":{"type":"string","maxLength":500},"address":{"type":"string","maxLength":300},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":50},"zip":{"type":"string","maxLength":20},"trackingNumber":{"type":"string","maxLength":100},"titleHolder":{"type":"string","maxLength":200},"titleHolderType":{"type":"string","enum":["SELLER","LENDER"]},"titleHolderAddress":{"type":"string","maxLength":300}}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/closings/{id}/document-requests":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Closings"],"summary":"Ask for a document a requirement still lacks","responses":{"200":{"description":"With ?dryRun=true: what would happen","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"would":{"type":"object"}}}}}},"202":{"description":"Asked","content":{"application/json":{"schema":{"type":"object","properties":{"closingId":{"type":"string"},"requirement":{"type":"object","properties":{"id":{"type":"string"},"step":{"type":"string"},"slot":{"type":"string"},"name":{"type":"string"}}},"askedOf":{"type":"string","enum":["SELLER","BUYER","CYPRESS"]},"notified":{"type":"integer"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found: not your closing, or a requirement your side does not see","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the closing is over, the requirement is waived or already accepted, or your organization asked for it in the last hour (`retryAfter`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `closing:write`. Whoever does the requirement's step owes it (the seller, or the buyer for the pickup's papers) and hears it; both sides' systems get CLOSING.DOCUMENT.REQUESTED. Once an hour per requirement for your organization. Audited.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requirementId"],"additionalProperties":false,"properties":{"requirementId":{"type":"string","description":"From the closing's `requirements`"}}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/closings/{id}/documents/{documentId}/signatures/{party}/resend":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"}},{"name":"party","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Closings"],"summary":"Re-send a signing link","responses":{"200":{"description":"With ?dryRun=true: what would happen","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean"},"would":{"type":"object"}}}}}},"202":{"description":"Sent again","content":{"application/json":{"schema":{"type":"object","properties":{"closingId":{"type":"string"},"documentId":{"type":"string"},"party":{"type":"string"},"name":{"type":["string","null"]}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: a buyer re-sends its own signers' links only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found: not your closing, a document your side does not see, or no such party","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the closing is over, the document was never sent for signatures, the party already signed, it is not their turn yet (an earlier signer signs first), or the link was re-sent in the last ten minutes (`retryAfter`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The signing service did not answer; nothing was recorded as sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `closing:write`. The signing service emails the party the same link again. The seller may re-send to anyone on the document; a buyer to its own signers. Audited.","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/notifications":{"get":{"tags":["Notifications"],"summary":"What your members were told, newest first","responses":{"200":{"description":"A page","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}},"nextCursor":{"type":["string","null"],"description":"Pass as `before` for the next (older) page"},"hasMore":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: a bad cursor or limit — or `recipient=me` with an API key (it acts as nobody), or with a different `userId`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `notifications:read`. The last 30 days (the event log's window).","parameters":[{"name":"userId","in":"query","schema":{"type":"string"},"description":"One recipient (GET /api/v1/members lists your people and agents)"},{"name":"recipient","in":"query","schema":{"type":"string","enum":["me"]},"description":"`me`: the person or agent the token acts as"},{"name":"before","in":"query","schema":{"type":"string"},"description":"A cursor: only notifications older than it"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}]}},"/api/v1/notifications/preferences":{"get":{"tags":["Notifications"],"summary":"A member's notification preferences","responses":{"200":{"description":"The workflows the person may switch off, by channel","content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"},"preferences":{"type":"array","items":{"$ref":"#/components/schemas/NotificationPreference"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED: an app acting for a person asked about someone else — or PEOPLE_ONLY: an agent token (an agent has no preferences and sets no one's)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"code NOT_FOUND: not an active member of your organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: an API key named no one, or named an agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Notifications are not configured on this server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `notifications:read`. An app acting for a person (Connect Cypress) reads that person's; an API key names any active person of your organization with `userId`. A workflow Cypress marks as one that cannot be switched off is not listed.","parameters":[{"name":"userId","in":"query","schema":{"type":"string"},"description":"The member (API keys: required; an app: its own person, or absent)"}]},"patch":{"tags":["Notifications"],"summary":"Set one workflow's channels for a member","responses":{"200":{"description":"The preference as it now is; or, with ?dryRun=true (since 1.5.0), what would change","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"userId":{"type":"string"},"preference":{"$ref":"#/components/schemas/NotificationPreference"}}},{"$ref":"#/components/schemas/WriteDryRun"}]}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code POLICY_DENIED or PEOPLE_ONLY, as for the read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"code NOT_FOUND: not an active member of your organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: a workflow the person may not switch off or that does not exist, an agent, or no one named — or validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Notifications are not configured on this server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `notifications:write` (never a default). The change is recorded in your organization's audit log with the credential that made it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["workflow","channels"],"additionalProperties":false,"properties":{"userId":{"type":"string","description":"The member (API keys: required; an app: its own person, or absent)"},"workflow":{"type":"string","description":"A workflow from the read (`offer.received`, …)"},"channels":{"type":"object","additionalProperties":false,"minProperties":1,"properties":{"email":{"type":"boolean"},"inApp":{"type":"boolean"}}}}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"Since 1.5.0. true: meet every check and answer { dryRun: true, changes }, writing nothing"},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"Since 1.5.0. A retry with the same key and body gets the first answer"}]}},"/api/v1/notifications/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Notifications"],"summary":"One notification","responses":{"200":{"description":"The notification","content":{"application/json":{"schema":{"type":"object","properties":{"notification":{"$ref":"#/components/schemas/Notification"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found: unknown, older than 30 days, or another organization's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `notifications:read`. One notification your members were sent (from the last 30 days): who it was for, what it said, by which channels, and the record it is about. list_notifications finds them."}},"/api/v1/mission-control":{"get":{"tags":["Mission Control"],"summary":"Your organization's board: what needs a person now, most urgent first","responses":{"200":{"description":"The board","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WorkItem"}},"totalCount":{"type":"integer","description":"Every item the filters show, on every page"},"nextHref":{"type":["string","null"],"description":"The next page, with `limit`; null on the last"},"summary":{"$ref":"#/components/schemas/WorkSummary"},"unavailable":{"type":"array","items":{"type":"string"},"description":"Sources that failed to load this time: a board missing a source looks the same as one with nothing to show"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed: an unknown filter or value — or `owner=me` with an API key (it acts as nobody)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `mission-control:read`. A first-party app acting for Cypress staff reads the organization's board with the staff items too (closing-reopen-suggested, bank-transfer-unapplied, archive-request-review; since 1.9.0). Filters combine. The board is short by design (each source shows its most urgent few and one line for the rest); `limit` and `offset` page it in triage order, and `summary` always counts the whole board.","parameters":[{"name":"source","in":"query","schema":{"type":"string"},"description":"Comma list of offers, listings, onboarding, valuations, closings, billing, campaigns, crm, platform"},{"name":"urgency","in":"query","schema":{"type":"string"},"description":"Comma list of decision, overdue, due-soon, attention, fyi"},{"name":"owner","in":"query","schema":{"type":"string","enum":["me","unassigned"]},"description":"`me`: the person or agent the token acts as"},{"name":"automated","in":"query","schema":{"type":"boolean","default":true},"description":"Include the receipts of what automations already did"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200},"description":"At most this many items, most urgent first; absent, the whole board"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]}},"/api/v1/mission-control/items/{itemId}/delegate":{"parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Mission Control"],"summary":"Give an item to one of your agents","responses":{"200":{"description":"The item was a task and is now the agent's, or was delegated before (its open task) — or, with ?dryRun=true, what it would do","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Delegation"},{"type":"object","properties":{"dryRun":{"type":"boolean"},"how":{"type":"string"},"agent":{"type":"object"},"changes":{"type":"object"}}}]}}}},"201":{"description":"A task was made on the item's record, for the agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Delegation"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not on your board (another organization's work answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code IDEMPOTENCY_IN_PROGRESS","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"code INVALID: an aggregate or an item about no one record (\"open it and give its parts to an agent one by one\"), no connected agent, more than one and none named, or one that is not your organization's active agent — or validation failed, or IDEMPOTENCY_KEY_REUSED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `tasks:write` and `mission-control:read`. An item that is a task (crm-task-<id>) is reassigned to the agent; an item about one vehicle, offer, closing, contact, company or deal becomes a task on that record (on the vehicle, for an offer or a closing), titled as the item, due when it is due, and given to the agent. Delegating the same item again while that task is open returns it. Sends TASK.CREATED and TASK.ASSIGNED, or TASK.ASSIGNED.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"agentUserId":{"type":["string","null"],"description":"One of your active agents (GET /api/v1/members lists them, `kind` AGENT). Absent: your only agent"},"note":{"type":["string","null"],"maxLength":5000,"description":"A word for the agent, kept as the task's notes"}}}}}},"parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"}},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}]}},"/api/v1/webhooks/subscriptions":{"get":{"tags":["Webhooks & deliveries"],"summary":"List subscriptions (header values masked)","responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionRead"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Webhooks & deliveries"],"summary":"Register a subscription (signingSecret returned ONCE)","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/SubscriptionRead"},"signingSecret":{"type":"string"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code SCOPE_MISSING / PLANNING_NOT_ENABLED — eventTypes lists a PLAN.* event and the key lacks planning:read (or the organization has no Planning); code SCOPE_MISSING / BUY_PLANNING_NOT_ENABLED — it lists a BUY.* event and the key lacks buy-planning:read (or the organization has no Buy planning); code SCOPE_MISSING — it lists a TASK.* event and the key lacks tasks:read (since 1.5.0); also the common 403s","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed (callback must be HTTPS) — or a PLAN.*, BUY.* or TASK.* event on a MANHEIM-dialect subscription (\"PLAN.* events are available only on the Cypress dialect\", \"BUY.* events are available only on the Cypress dialect\", \"TASK.* events are available only on the Cypress dialect\")","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionWrite"}}}}}},"/api/v1/webhooks/subscriptions/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Webhooks & deliveries"],"summary":"Read a subscription","responses":{"200":{"description":"The subscription","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/SubscriptionRead"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Webhooks & deliveries"],"summary":"Replace a subscription (secret rotation = delete + recreate)","responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","properties":{"subscription":{"$ref":"#/components/schemas/SubscriptionRead"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code SCOPE_MISSING / PLANNING_NOT_ENABLED — eventTypes lists a PLAN.* event and the key lacks planning:read (or the organization has no Planning); code SCOPE_MISSING / BUY_PLANNING_NOT_ENABLED — it lists a BUY.* event and the key lacks buy-planning:read (or the organization has no Buy planning); code SCOPE_MISSING — it lists a TASK.* event and the key lacks tasks:read (since 1.5.0); also the common 403s","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — or a PLAN.* or BUY.* event with dialect MANHEIM (a full replace: an omitted dialect is stored as CYPRESS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionWrite"}}}}},"delete":{"tags":["Webhooks & deliveries"],"summary":"Delete a subscription","responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/subscriptions/{id}/test":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Webhooks & deliveries"],"summary":"Send a PING.TEST through the real pipeline","responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"deliveryId":{"type":"string"},"deliveryHref":{"type":"string"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Subscription is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/subscriptions/{id}/replay":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Webhooks & deliveries"],"summary":"Deliver again, to this subscription only, the stored events after a cursor (last 30 days)","responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"integer"},"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Subscription is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"after: a cursor is a whole number; limit 1 to 1000","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["after"],"properties":{"after":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":1000}}}}}}}},"/api/v1/events":{"get":{"tags":["Webhooks & deliveries"],"summary":"Your organization's event log, oldest first, last 30 days (?after=&limit=&types=)","responses":{"200":{"description":"A page","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/FeedEvent"}},"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"after must be a whole number; types must be known event names; limit 1 to 500","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"after","in":"query","schema":{"type":"string"},"description":"Return events after this cursor. Omit to start at the oldest kept."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"types","in":"query","schema":{"type":"string"},"description":"Comma-separated canonical event names"}]}},"/api/v1/deliveries":{"get":{"tags":["Webhooks & deliveries"],"summary":"Your delivery log (?status=&eventType=)","responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"totalCount":{"type":"integer"},"nextHref":{"type":"string"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"eventType","in":"query","schema":{"type":"string"}}]}},"/api/v1/deliveries/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Webhooks & deliveries"],"summary":"One delivery with the envelope as sent and your endpoint’s response","responses":{"200":{"description":"The delivery","content":{"application/json":{"schema":{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/Delivery"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Needs `webhooks`. The body of a `BUY.*` delivery is the dealer's own target, so it also needs the Buy planning read capability (`buy-planning:read` or `:write`, with Buy planning on), as subscribing to the event does; the body of a `TASK.*` delivery (your organization's task) needs `tasks:read` or `:write` the same way (since 1.5.0). A key without it still reads the delivery, its status and your endpoint's response: `envelope.body` is `null` and `bodyWithheld` names the scope that shows it."}},"/api/compatible/v1/units":{"post":{"tags":["Manheim-compatible v1"],"summary":"Create a unit → 201 + Location (Manheim convention)","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"href":{"type":"string"},"offering":{"type":"object"},"launched":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A unit with this VIN already exists — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"An embedded `offering` needs the `listings` scope too — 403 SCOPE_MISSING (naming `listings`) when the key holds only `vehicles`, and nothing is created.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManheimUnit"}}}}}},"/api/compatible/v1/units/bulk":{"post":{"tags":["Manheim-compatible v1"],"summary":"Bulk push (≤100, per-item results)","responses":{"200":{"description":"Per-item results","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"vin":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string","enum":["PLANNING_STOCK","PLANNING_NOT_ENABLED","SCOPE_MISSING","CHANNEL_NOT_GRANTED"]},"errors":{"type":"array","items":{"type":"string"}}}}},"created":{"type":"integer"},"conflicts":{"type":"integer"},"invalid":{"type":"integer"},"refused":{"type":"integer","description":"Items answered 403 — planning stock on an organization without Planning, or an embedded offering without the listings scope"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Envelope invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"An item's embedded `offering` needs the `listings` scope too; missing it answers that item 403 SCOPE_MISSING (the batch continues). An embedded `offering` naming a channel the organization has no grant for answers that item 422 CHANNEL_NOT_GRANTED (\"Channels not enabled: …\") and the unit is not created (since 1.3.0; the batch continues).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"units":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/ManheimUnit"}}},"required":["units"]}}}}}},"/api/compatible/v1/units/id/{unitId}":{"parameters":[{"name":"unitId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Manheim-compatible v1"],"summary":"Read a unit in Manheim shape (unmapped fields echoed back)","responses":{"200":{"description":"The unit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManheimUnit"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Manheim-compatible v1"],"summary":"Full re-push update → 204 empty (update-is-POST)","responses":{"204":{"description":"Updated"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"VIN change attempted — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManheimUnit"}}}}},"delete":{"tags":["Manheim-compatible v1"],"summary":"Delete an unlisted unit","responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Unit is listed or sold — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/compatible/v1/units/id/{unitId}/actions/sold_elsewhere":{"parameters":[{"name":"unitId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Manheim-compatible v1"],"summary":"Report sold-elsewhere (at once without an open offer or a sale in progress; otherwise staged for Cypress review)","responses":{"202":{"description":"Staged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedResult"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already sold or archived — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DispositionRequest"}}}}}},"/api/compatible/v1/units/mine":{"get":{"tags":["Manheim-compatible v1"],"summary":"All your units (paginated items[])","responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ManheimUnit"}},"totalCount":{"type":"integer"},"nextHref":{"type":"string"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]}},"/api/compatible/v1/offerings":{"post":{"tags":["Manheim-compatible v1"],"summary":"Create an offering for a unit","responses":{"201":{"description":"Created (Location header set)","content":{"application/json":{"schema":{"type":"object","properties":{"offering":{"type":"object"},"launched":{"type":"boolean"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown unit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"An open offering already exists — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Channels not enabled, unit reference missing, or validation failed — code CHANNEL_NOT_GRANTED","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManheimOffering"}}}}}},"/api/compatible/v1/offerings/id/{offeringId}":{"parameters":[{"name":"offeringId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Manheim-compatible v1"],"summary":"Read an offering","responses":{"200":{"description":"The offering","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Manheim-compatible v1"],"summary":"Update prices/channels → 204 (update-is-POST)","responses":{"204":{"description":"Updated"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code BELOW_FLOOR (since 1.5.0) when the buy-now price would sit below the floor; also the common 403s","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Offering is closed — or code CONFLICT (since 1.5.0) when a price would move under a live offer or sale — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — code CHANNEL_NOT_GRANTED when channels are changed to one not granted — or code INVALID (since 1.5.0) for a buy-now on a vehicle with no floor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManheimOffering"}}}}},"delete":{"tags":["Manheim-compatible v1"],"summary":"Cancel (live units are delisted; mid-deal cancels are staged)","responses":{"202":{"description":"Staged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedResult"}}}},"204":{"description":"Cancelled"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already closed, or the unit is sold on Cypress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/compatible/v1/offerings/id/{offeringId}/actions/pause":{"parameters":[{"name":"offeringId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Manheim-compatible v1"],"summary":"Pause a live offering → 204","responses":{"204":{"description":"Paused"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not live, or a deal is in progress — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/compatible/v1/offerings/id/{offeringId}/actions/resume":{"parameters":[{"name":"offeringId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Manheim-compatible v1"],"summary":"Resume a paused offering → 204","responses":{"204":{"description":"Resumed"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not paused — or code PLANNING_STOCK when the vehicle is in Planning (403 PLANNING_NOT_ENABLED if the organization does not have Planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/compatible/v1/offerings/mine":{"get":{"tags":["Manheim-compatible v1"],"summary":"All your offerings (?status= filter)","responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object"}},"totalCount":{"type":"integer"},"nextHref":{"type":"string"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"status","in":"query","schema":{"type":"string"}}]}},"/api/compatible/v1/subscribers":{"get":{"tags":["Manheim-compatible v1"],"summary":"List subscribers (header values masked)","responses":{"200":{"description":"Collection","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionRead"}}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Manheim-compatible v1"],"summary":"Register a subscriber — Manheim {callback, headers, emails}; MANHEIM dialect by default","responses":{"201":{"description":"Created (signingSecret shown ONCE)","content":{"application/json":{"schema":{"type":"object","properties":{"subscriber":{"$ref":"#/components/schemas/SubscriptionRead"},"signingSecret":{"type":"string"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or unknown event names — or a PLAN.* or BUY.* event (\"PLAN.* events are available only on the Cypress dialect\", \"BUY.* events are available only on the Cypress dialect\")","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionWrite"}}}}}},"/api/compatible/v1/subscribers/id/{subscriberId}":{"parameters":[{"name":"subscriberId","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Manheim-compatible v1"],"summary":"Read a subscriber","responses":{"200":{"description":"The subscriber","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRead"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Manheim-compatible v1"],"summary":"Replace a subscriber","responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRead"}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed — or a PLAN.* or BUY.* event (Cypress dialect only)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionWrite"}}}}},"delete":{"tags":["Manheim-compatible v1"],"summary":"Delete a subscriber","responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/compatible/v1/subscribers/id/{subscriberId}/test":{"parameters":[{"name":"subscriberId","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Manheim-compatible v1"],"summary":"Send a PING.TEST through the real pipeline","responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"deliveryId":{"type":"string"}}}}}},"401":{"description":"Missing, malformed, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE (organization not active), ACCOUNT_RULES (a feature off for this account, or one of its caps used), SCOPE_MISSING (key lacks the scope), PLANNING_NOT_ENABLED (planning capability on an org without Planning), or BUY_PLANNING_NOT_ENABLED (a Buy planning capability on an org without Buy planning)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Subscriber is inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (300 requests/min per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/labels":{"get":{"tags":["Vehicles: the app's actions"],"summary":"A vehicle's labels and their history","description":"The labels on one vehicle (each with its name, color, category and how it was put there: by hand, a rule or an automation) and the last 50 changes to them. To put labels on or take them off, use add_vehicle_labels and remove_vehicle_labels. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_vehicle_labels","x-cypress-action":"vehicles.labels.list","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Vehicles: the app's actions"],"summary":"Put one or more labels on a vehicle (by hand)","description":"Puts labels on one vehicle, as a person does from its panel; a label already there stays. Label ids come from list_labels. Automations watching labels run as they do for a person's change. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"add_vehicle_labels","x-cypress-action":"vehicles.labels.add","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"labelIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":50,"description":"The labels to put on"}},"required":["labelIds"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/valuations":{"get":{"tags":["Vehicles: the app's actions"],"summary":"A vehicle's valuation history, newest first","description":"Every valuation the vehicle has had, newest first: the source, wholesale with its range, retail and trade-in, and when. revalue_vehicle asks for a new one; Cypress Intelligence's vehicle_valuation adds what the same year, make and model sold for. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_vehicle_valuations","x-cypress-action":"vehicles.valuations.list","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/activity":{"get":{"tags":["Vehicles: the app's actions"],"summary":"What happened to a vehicle, who did it and when","description":"The vehicle's audit trail as the panel's Activity tab shows it: each change with who made it (a person, an automation, the API) and when, newest first. Page back with `cursor` (the last entry's date). Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_vehicle_activity","x-cypress-action":"vehicles.activity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"At most this many (50 when left out)"},"description":"At most this many (50 when left out)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":40,"description":"Entries before this date (ISO)"},"description":"Entries before this date (ISO)"},{"name":"action","in":"query","required":false,"schema":{"type":"string","maxLength":80,"description":"Only this kind of entry"},"description":"Only this kind of entry"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/listing-readiness":{"get":{"tags":["Vehicles: the app's actions"],"summary":"The checklist a vehicle passes before it goes live, and suggested offer rules","description":"The listing checklist the app shows before Launch: each required field and whether it is there, and the auto-accept and auto-decline thresholds Cypress suggests. Read it before launch_approved_vehicle. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"check_vehicle_listing_readiness","x-cypress-action":"vehicles.listing_readiness","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/listing-metrics":{"get":{"tags":["Vehicles: the app's actions"],"summary":"A live vehicle's listing, its activity and its offer rules","description":"For a vehicle on the market (listed, on hold, under offer or accepted): the listing's status, views, saves and offers, and the offer rules in force. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_vehicle_listing_metrics","x-cypress-action":"vehicles.listing_metrics","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/market-history":{"get":{"tags":["Vehicles: the app's actions"],"summary":"Everywhere a vehicle has been shown, and what came of it","description":"The vehicle's market history as the panel's tab shows it: its listings, the channels and links it was shown on, the campaigns it was in, the offers they brought and how the sale came about. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_vehicle_market_history","x-cypress-action":"vehicles.market_history","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/comps":{"get":{"tags":["Vehicles: the app's actions"],"summary":"Recent Cypress sales like this vehicle: yours one by one, other sellers' as a range, and its Black Book value","description":"Cars sold on Cypress in the last year (`days`) of the same year (one either side), make and model, at a similar mileage (within 30%, never closer than 25,000 miles; a sale with no mileage counts). Your own sales come one by one, newest first, with the price, mileage, date, state and buyer. Other sellers' sales come only as a range (low, middle and high, rounded to $100), and only when five sales from at least two other companies stand behind it; they are never listed one by one or named. `summary` gives the count, the median sold price, that median as a percent of this vehicle's listing price and what the sales fetched against their own ask. `blackBook` is the vehicle's latest Black Book value. `mine=true` reads your own sales only; find_comparable_sales asks by year, make and model without a vehicle. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.9.0.","operationId":"get_vehicle_comps","x-cypress-action":"vehicles.comps","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"mine","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"description":"true: your own sales only, no market range"},"description":"true: your own sales only, no market range"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"description":"How many of your own sales to list, newest first (10 when left out)"},"description":"How many of your own sales to list, newest first (10 when left out)"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":30,"maximum":730,"description":"Sold within this many days (365 when left out)"},"description":"Sold within this many days (365 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/comps":{"get":{"tags":["Vehicles: the app's actions"],"summary":"Recent Cypress sales of a year, make and model; \"my last sold 2021 Ford Transit\" is mine=true with limit 1","description":"The same reading as get_vehicle_comps for a car you name rather than one you hold: the year (one either side), make and model, and a mileage when you have one. Name at least the make or the model. With `mine=true` only your own sales come back, newest first, so `mine=true&limit=1` answers \"my last sold 2021 Ford Transit\". Other sellers' sales come only as a range, as in get_vehicle_comps. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.9.0.","operationId":"find_comparable_sales","x-cypress-action":"vehicles.comps.search","parameters":[{"name":"year","in":"query","required":false,"schema":{"type":"integer","minimum":1900,"maximum":2100,"description":"Model year: the sales of that year and one either side (any year when left out)"},"description":"Model year: the sales of that year and one either side (any year when left out)"},{"name":"make","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":60}},{"name":"model","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":80}},{"name":"mileage","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":2000000,"description":"The mileage to compare with (no mileage filter when left out)"},"description":"The mileage to compare with (no mileage filter when left out)"},{"name":"listingPrice","in":"query","required":false,"schema":{"type":"number","exclusiveMinimum":0,"description":"USD: a price to compare the median with (`summary.pctOfListing`)"},"description":"USD: a price to compare the median with (`summary.pctOfListing`)"},{"name":"mine","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"description":"true: your own sales only, no market range"},"description":"true: your own sales only, no market range"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"description":"How many of your own sales to list, newest first (10 when left out)"},"description":"How many of your own sales to list, newest first (10 when left out)"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":30,"maximum":730,"description":"Sold within this many days (365 when left out)"},"description":"Sold within this many days (365 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/archive-record":{"get":{"tags":["Vehicles: the app's actions"],"summary":"An archived vehicle's archive record","description":"For an archived vehicle: how it left (sold elsewhere, archived, a deal that fell through), when, the reason and Cypress's decision. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_vehicle_archive_record","x-cypress-action":"vehicles.archive_record","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/photos":{"get":{"tags":["Vehicles: the app's actions"],"summary":"A vehicle's pictures and videos, in their order, with links","description":"The vehicle's stills, 360° frames and videos in the order buyers see them, each with a link valid for an hour and whether it is the cover. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_vehicle_photos","x-cypress-action":"vehicles.photos.list","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Vehicles: the app's actions"],"summary":"Upload one picture to a vehicle","description":"Adds one picture to the end of the vehicle's pictures, as the editor's upload does; the first picture a vehicle gets is its cover. Answers the picture with a link valid for an hour. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"add_vehicle_photo","x-cypress-action":"vehicles.photos.add","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentBase64":{"type":"string","minLength":4,"maxLength":14000000,"description":"The picture, base64 (at most 10 MB)"},"contentType":{"type":"string","pattern":"^image\\/(jpeg|png|webp|heic|heif)$","description":"image/jpeg, image/png, image/webp or image/heic"},"fileName":{"type":"string","maxLength":200}},"required":["contentBase64","contentType"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/share-links":{"get":{"tags":["Vehicles: the app's actions"],"summary":"A vehicle's share links (Direct Links) with their commission","description":"The links that show this vehicle to whoever holds them (Direct Links), each with its label, expiry, commission scheme and whether it is the default. list_share_link_visitors names who came through one. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_vehicle_share_links","x-cypress-action":"vehicles.share_links.list","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Vehicles: the app's actions"],"summary":"A link that shows one vehicle to whoever holds it (Direct Links)","description":"Makes a share link for one vehicle (the Direct Links channel), with a label for you and an expiry; Cypress staff may set its commission scheme. Since 1.9.0, `recipientOrgId` addresses it to one buyer organization (an active buyer on Cypress, not your own company): that buyer hears MARKETPLACE.SHARE.RECEIVED in its own organization, and the link still opens for anyone you hand it to. Answers the link. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"create_vehicle_share_link","x-cypress-action":"vehicles.share_links.create","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":120},"expiresAt":{"type":["string","null"],"format":"date-time"},"commissionSchemeId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"Cypress staff only"},"recipientOrgId":{"type":"string","minLength":1,"maxLength":64,"description":"Since 1.9.0. The buyer organization the link is for: it hears MARKETPLACE.SHARE.RECEIVED"}}}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/share-links/{linkId}/visitors":{"get":{"tags":["Vehicles: the app's actions"],"summary":"The buyer companies that opened a share link","description":"The signed-in buyer companies that arrived on this vehicle through one share link, with when; visits by people not signed in are one count, never named. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_share_link_visitors","x-cypress-action":"vehicles.share_links.visitors","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"linkId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The share link"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/history-report":{"get":{"tags":["Vehicles: the app's actions"],"summary":"The third-party inspection report attached to a vehicle","description":"The third-party inspection report attached to the vehicle (a Manheim condition report): its provider, link and status, and what Cypress read from it: the grade, title, keys, tires, warning lights and each damage. A link no provider reads (provider UNKNOWN) is kept as a link only. The vehicle's read (get_vehicle) carries the same report in short. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_vehicle_history_report","x-cypress-action":"vehicles.third_party_report.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Vehicles: the app's actions"],"summary":"Attach a third-party inspection report (a Manheim condition report) by its link","description":"Attaches a third-party inspection report by its link. A Manheim condition report is read: its grade becomes the vehicle's condition (unless a finalized ARVIS inspection set it), and its damages and photos are added; webhooks hear VEHICLES.UPDATED (changedFields inspectionReport) when it lands. A link no provider reads is kept as a link only. A vehicle with a report keeps it unless `force` replaces it. A push can carry the link too (inspectionReportUrl on create_vehicle). Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"attach_vehicle_history_report","x-cypress-action":"vehicles.third_party_report.attach","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"},"force":{"type":"boolean"}},"required":["url"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/fleets":{"get":{"tags":["Vehicles: the app's actions"],"summary":"The organization's fleets (its groups of vehicles)","description":"The fleets the organization sorts its vehicles into, each with its name and how many vehicles it holds. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_fleets","x-cypress-action":"fleets.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/fleet/stats":{"get":{"tags":["Vehicles: the app's actions"],"summary":"The fleet page's numbers: vehicles by status, value, days on market","description":"The figures at the top of the Fleet page: how many vehicles in each status, their value, and how long they have been on the market. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_fleet_stats","x-cypress-action":"fleet.stats","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/fleet/metrics":{"get":{"tags":["Vehicles: the app's actions"],"summary":"The dashboard's tiles over a period: pipeline, stuck, fleet value, sold, days to sell, offers per listing","description":"The dashboard's numbers, from the one computation the dashboard page draws. `tiles` are its tiles in its order and words (Active pipeline, Stuck 7+ days, Wholesale GMV, Retail value, Vehicles sold, Avg days to sell, Offers per listing), each with `display` (the text the dashboard shows, such as \"$1.0M\" or \"122.4d\"), `snapshot` (true: what is true now, with no prior period), `prev`, `delta` (null for a snapshot and when the prior period is 0) and `trend` (a real series only: sold per day, days to sell per week). Draw the tiles as given. Wholesale GMV and Retail value are what the active fleet is worth now: there is no history of fleet value, so `fleetValue` and `retailValue` carry no trend and no prior period; never draw one. `pipeline` has the two pipeline counts; `vehiclesSold`, `avgDaysToSell`, `offersPerListing` and `daysToSellDistribution` are the period figures behind the tiles. The dashboard offers 7d, 30d and 90d (since 1.9.0; 365d is read here only, and is a real 365 days). Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_fleet_metrics","x-cypress-action":"fleet.metrics","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","365d"],"description":"7d, 30d (the default) or 90d, as the dashboard's switch; 365d too"},"description":"7d, 30d (the default) or 90d, as the dashboard's switch; 365d too"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","enum":["7d","30d","90d","365d"]},"periodDays":{"type":"integer"},"from":{"type":"string","description":"The period's first moment (ISO)"},"to":{"type":"string","description":"The period's last moment (ISO)"},"pipeline":{"type":["object","null"],"properties":{"activePipeline":{"type":"integer"},"stuckCount":{"type":"integer"},"totalFleet":{"type":"integer"}},"required":["activePipeline","stuckCount","totalFleet"],"description":"The pipeline's counts (planning stock included); null with no organization"},"tiles":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["activePipeline","stuck","wholesaleGmv","retailValue","vehiclesSold","avgDaysToSell","offersPerListing"]},"label":{"type":"string","description":"The dashboard's label"},"value":{"type":"number"},"display":{"type":"string","description":"The value as the dashboard shows it: \"69\", \"$1.0M\", \"122.4d\", \"0.3\""},"format":{"type":"string","enum":["number","currency","days","decimal"]},"snapshot":{"type":"boolean","description":"True: what is true now; no prior period, no delta, no trend"},"prev":{"type":["number","null"],"description":"The prior period's value; null for a snapshot"},"delta":{"type":["object","null"],"properties":{"pct":{"type":"number"},"better":{"type":"boolean"},"display":{"type":"string","description":"\"↑200.0%\": the arrow means better or worse"}},"required":["pct","better","display"],"description":"Null for a snapshot and when the prior period is 0"},"lowerIsBetter":{"type":"boolean"},"trend":{"type":"array","items":{"type":"number"},"description":"A real series only (sold per day, days to sell per week); empty otherwise"},"trendStep":{"type":["string","null"],"enum":["day","week"]}},"required":["key","label","value","display","format","snapshot","prev","delta","lowerIsBetter","trend","trendStep"]},"description":"The dashboard's tiles, in its order: draw them as given"},"fleetValue":{"type":"object","properties":{"current":{"type":"number"},"prev":{"type":"number"},"trend":{"type":"array","items":{"type":"number"}}},"required":["current","prev","trend"],"description":"Wholesale GMV of the active fleet now: a snapshot, prev 0 and no trend (no history of fleet value exists; never draw one)"},"retailValue":{"type":"object","properties":{"current":{"type":"number"},"prev":{"type":"number"},"trend":{"type":"array","items":{"type":"number"}}},"required":["current","prev","trend"],"description":"Retail value of the active fleet now: a snapshot, as fleetValue"},"vehiclesSold":{"type":"object","properties":{"current":{"type":"number"},"prev":{"type":"number"},"trend":{"type":"array","items":{"type":"number"}}},"required":["current","prev","trend"],"description":"Sold in the period; trend per day"},"avgDaysToSell":{"type":"object","properties":{"current":{"type":"number"},"prev":{"type":"number"},"trend":{"type":"array","items":{"type":"number"}}},"required":["current","prev","trend"],"description":"Average days from added to sold; trend per week"},"offersPerListing":{"type":"object","properties":{"current":{"type":"number"},"prev":{"type":"number"},"trend":{"type":"array","items":{"type":"number"}}},"required":["current","prev","trend"],"description":"Offers per marketable vehicle; trend is [prior, current]"},"daysToSellDistribution":{"type":"object","properties":{"lt3":{"type":"integer"},"d3to7":{"type":"integer"},"d7to14":{"type":"integer"},"d14to30":{"type":"integer"},"gt30":{"type":"integer"}},"required":["lt3","d3to7","d7to14","d14to30","gt30"]}},"required":["period","periodDays","from","to","pipeline","tiles","fleetValue","retailValue","vehiclesSold","avgDaysToSell","offersPerListing","daysToSellDistribution"]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/labels/remove":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Take one or more labels off a vehicle (by hand)","description":"Takes labels off one vehicle, as a person does from its panel; a label that is not there is ignored. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"remove_vehicle_labels","x-cypress-action":"vehicles.labels.remove","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"labelIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":50,"description":"The labels to take off"}},"required":["labelIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/labels":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Add and remove labels across many vehicles in one go","description":"The Fleet page's bulk label edit: on every vehicle named, puts the labels in `add` and takes off those in `remove`. Answers how many vehicles changed. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"edit_labels_on_vehicles","x-cypress-action":"vehicles.labels.batch","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"},"addLabelIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":50,"default":[]},"removeLabelIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":50,"default":[]}},"required":["vehicleIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/transitions":{"post":{"tags":["Vehicles: the app's actions"],"summary":"A step of the vehicle's way to market (submit, approve, reject, hold, deliver, archive…)","description":"The status buttons of the vehicle panel: submit for review (it needs a floor), submit for approval and approve the pricing (they need a target price), reject with a comment, move back to draft or review, hold and resume, the due-diligence steps, confirm or revert delivery, archive. Each answers as the button does: a step that is not open from the vehicle's status, or not open to your role, is refused with the reason. A floor sent here is the seller's: a person sends it. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"change_vehicle_status","x-cypress-action":"vehicles.transition","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["revert-to-draft","submit-for-review","submit-for-approval","approve","direct-approve","reject","hold","resume","return-to-review","revert-to-listed","start-due-diligence","complete-due-diligence","abort-due-diligence","reopen-due-diligence","revert-to-offer-accepted","confirm-delivery","revert-delivery","archive"],"description":"The step"},"floorPrice":{"type":"number","exclusiveMinimum":0,"description":"USD: the floor, with submit-for-review"},"targetPrice":{"type":"number","exclusiveMinimum":0,"description":"USD: the price to list at, with submit-for-approval or direct-approve"},"rejectionFloorPrice":{"type":"number","exclusiveMinimum":0,"description":"USD: a new floor, with reject"},"rejectionComment":{"type":"string","maxLength":2000,"description":"Why, with reject"},"reason":{"type":"string","maxLength":2000,"description":"Why, with revert-delivery (required there)"}},"required":["action"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/submit-for-review":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Send many draft vehicles to Cypress for pricing review","description":"The Fleet page's bulk Submit for review: every draft named that has a floor moves to Review, where Cypress prices it. Answers which moved and why the others did not. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"submit_vehicles_for_review","x-cypress-action":"vehicles.submit_for_review","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"}},"required":["vehicleIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/launch":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Launch an approved vehicle to the marketplace, as the Launch button does","description":"The vehicle panel's Launch: an APPROVED vehicle goes live (LISTED) with its offer rules, once its listing checklist passes (check_vehicle_listing_readiness says what is missing). The rules may be sent here; left out, the suggested ones apply. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `LISTINGS.ACTIVATED`. Since 1.5.0.","operationId":"launch_approved_vehicle","x-cypress-action":"vehicles.launch","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"auctionRule":{"type":"object","properties":{"enabled":{"type":"boolean"},"autoAcceptAbove":{"type":["number","null"],"exclusiveMinimum":0},"autoDenyBelow":{"type":["number","null"],"exclusiveMinimum":0}},"required":["enabled"],"description":"The offer rules: accept above, decline below (USD)"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/launch":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Launch many approved vehicles at once","description":"The Fleet page's bulk Launch: every APPROVED vehicle named whose listing checklist passes goes live; the rest are skipped. Answers how many launched and how many were skipped. Cypress staff launch an organization's vehicles only when it delegated that to Cypress (Act on its behalf): otherwise `403 POLICY_DENIED`, reason `NOT_DELEGATED`, and nothing launches (since 1.9.0). Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"launch_approved_vehicles","x-cypress-action":"vehicles.launch_many","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"}},"required":["vehicleIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/pause":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Pause a live vehicle (on hold): its open offers are withdrawn and the buyers told","description":"The panel's Pause: a LISTED vehicle goes ON HOLD, its listing pauses, its open offers are withdrawn and their buyers told; Cypress is told when the seller pauses. Resume it with resume_vehicle. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"pause_vehicle","x-cypress-action":"vehicles.pause","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500},"note":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/resume":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Resume a vehicle on hold (Cypress or the organization's admin)","description":"The panel's Resume: an ON HOLD vehicle is LISTED again and its listing published. In the app this is Cypress's or the organization admin's; a Fleet Manager asks them. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"resume_vehicle","x-cypress-action":"vehicles.resume","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/delist":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Delist a live vehicle: at once without an open offer; with one, Cypress reviews a seller's request","description":"The panel's Remove from market. A seller's vehicle with no open offer is archived at once (answered `archived: true`); one with an open offer is staged for Cypress to review (answered `staged: true`, the listing paused meanwhile). Cypress's own (a CM token) archives at once, withdrawing the listing and its open offers. To take a car off the market for a while, use pause_vehicle. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"delist_vehicle","x-cypress-action":"vehicles.delist","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500},"note":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/archive/undo":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Put a vehicle you archived at once back where it was, within 24 hours","description":"Within 24 hours of an archive your organization made at once (delist or sold elsewhere with no open offer and no sale in progress), puts the vehicle back on the status it had: a listed car is listed again at its last price. Offers the archive withdrew are not revived. Refused with 409 CONFLICT once Cypress reviewed the archive (it went to review, or Cypress recorded a decision), after 24 hours, or when the vehicle changed since (relisted, restored, archived again, a request filed on it): ask your account manager then. A person's act: your fleet managers and admins; never an agent's or an API key's, and not Cypress staff's (they use roll_back_archive). Told as VEHICLES.UPDATED with `toStatus`. Since 1.9.0. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Emits `VEHICLES.UPDATED`. Since 1.9.0.","operationId":"undo_vehicle_archive","x-cypress-action":"vehicles.archive.undo","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":2000,"description":"Why, for the activity log"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/dispose":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Cypress archives a vehicle in one step, with who is responsible and the decision","description":"The staff Dispose: archives a vehicle at once with the full cleanup (offers withdrawn, a closing in progress cancelled), recording the disposition, who is responsible and Cypress's decision toward them. A vehicle in Post-Sale needs both. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"dispose_vehicle","x-cypress-action":"vehicles.dispose","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000},"disposition":{"type":"string","enum":["SOLD_ELSEWHERE","ARCHIVED","DEAL_FELL_THROUGH","REMOVED"],"default":"ARCHIVED"},"culpritRole":{"type":"string","enum":["SELLER","BUYER","CYPRESS"]},"decision":{"type":"string","enum":["NO_ACTION","WARNING","PENALTY_FEE","ESCALATE_REVIEW"]},"decisionNotes":{"type":"string","maxLength":2000}},"required":["reason"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/offer-rules":{"put":{"tags":["Vehicles: the app's actions"],"summary":"Auto-accept above and auto-decline below, on a live vehicle","description":"The panel's offer rules on a live vehicle: an offer above `autoAcceptAbove` is accepted at once, one below `autoDenyBelow` declined. Nothing about the listing changes. The thresholds sit against the floor, so they are a person's to set. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"set_vehicle_offer_rules","x-cypress-action":"vehicles.offer_rules.set","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"autoAcceptAbove":{"type":["number","null"],"exclusiveMinimum":0},"autoDenyBelow":{"type":["number","null"],"exclusiveMinimum":0}},"required":["enabled"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/apply-pricing-rule":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Evaluate the pricing rules for a vehicle; with confirm, apply the outcome","description":"Runs the organization's pricing rules on one vehicle: which rule matches and what it would do (approve and list, reject to draft, or leave it for review). A dry run, or `confirm` left false, only says it; `confirm: true` applies it. Since 1.10.0 a rule that would list the vehicle first passes the listing checklist the Launch button checks (location state, mileage, condition; the rule's price is the asking price): when something is missing it is refused with what is missing and the vehicle stays where it was. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"apply_pricing_rule","x-cypress-action":"vehicles.pricing_rule.apply","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/apply-pricing-rules":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Evaluate (and with confirm, apply) the pricing rules across many vehicles","description":"The bulk version of apply_pricing_rule, with its rules: each vehicle in review (or approved) is judged by Cypress's rules and its own organization's, and answers its matching outcome and listing price; `confirm: true` applies them (approve and list, reject to draft, or leave for review) and says where each went (`toStatus`). A vehicle in any other status is named with an error and left alone. Since 1.9.0 a vehicle in review is approved and listed as the single apply does (it used to need to be approved first), each answer names the rule that matched (`ruleId`, `ruleName`, null when none did), and without `confirm` a draft is judged too, as if it were in review: what the rule would do once it is sent there (nothing is written). Since 1.10.0 each answer that lists also carries the offer lines the rule sets (`computedAutoAcceptAbove`, `computedAutoDenyBelow`), and a rule that would list a vehicle missing part of the listing checklist (location state, mileage, condition) names it in `missing` and, with `confirm`, leaves the vehicle where it was with an error. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Since 1.5.0.","operationId":"apply_pricing_rules","x-cypress-action":"vehicles.pricing_rules.apply_many","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"},"confirm":{"type":"boolean"}},"required":["vehicleIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/revalue":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Value a vehicle again now","description":"Marks the vehicle's valuation as stale and asks for a new one, as the panel's Revalue does; it arrives in a minute or two (list_vehicle_valuations shows it). Counts against the organization's valuations. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"revalue_vehicle","x-cypress-action":"vehicles.revalue","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/revalue":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Value up to 200 vehicles again","description":"The Fleet page's bulk revalue: asks for a new valuation of each vehicle named (at most 200). Counts against the organization's valuations. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"revalue_vehicles","x-cypress-action":"vehicles.revalue_many","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":200}},"required":["vehicleIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/photos/{photoId}":{"delete":{"tags":["Vehicles: the app's actions"],"summary":"Delete one of a vehicle's pictures","description":"Deletes one picture of the vehicle, as the editor's remove does. A cover that is removed passes to the next picture; list_vehicle_photos lists the ids. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"remove_vehicle_photo","x-cypress-action":"vehicles.photos.remove","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"photoId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/photos/{photoId}/cover":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Make one picture the vehicle's cover","description":"Makes one of the vehicle's pictures its cover: the one buyers see first, in lists and links. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"set_vehicle_cover_photo","x-cypress-action":"vehicles.photos.cover","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"photoId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/photos/order":{"put":{"tags":["Vehicles: the app's actions"],"summary":"Set the order of a vehicle's pictures","description":"Sets the order buyers see the vehicle's stills in, first to last (360° frames keep theirs). Name every still once. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"reorder_vehicle_photos","x-cypress-action":"vehicles.photos.order","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":200,"description":"The stills, first to last"}},"required":["ids"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/videos":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Upload one video to a vehicle","description":"Adds one video (a walkaround) to the vehicle. Answers the video with a link valid for an hour. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"add_vehicle_video","x-cypress-action":"vehicles.videos.add","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentBase64":{"type":"string","minLength":4,"maxLength":70000000,"description":"The video, base64 (at most 50 MB)"},"contentType":{"type":"string","pattern":"^video\\/(mp4|quicktime|webm)$","description":"video/mp4, video/quicktime or video/webm"},"fileName":{"type":"string","maxLength":200}},"required":["contentBase64","contentType"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/videos/{videoId}":{"delete":{"tags":["Vehicles: the app's actions"],"summary":"Delete one of a vehicle's videos","description":"Deletes one video of the vehicle, as the editor's remove does; buyers stop seeing it at once. list_vehicle_photos lists the videos with their ids. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"remove_vehicle_video","x-cypress-action":"vehicles.videos.remove","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"videoId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/share-links":{"post":{"tags":["Vehicles: the app's actions"],"summary":"One share link per vehicle, for many vehicles","description":"The Fleet page's bulk share links: one link per vehicle named, with the same label (and, for Cypress staff, commission scheme). Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"create_share_links","x-cypress-action":"vehicles.share_links.create_many","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"},"label":{"type":"string","maxLength":120},"commissionSchemeId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"Cypress staff only"}},"required":["vehicleIds"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/share-links/revoke":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Stop every share link of the vehicles named","description":"Revokes every share link of the vehicles named: whoever holds one no longer sees the vehicle through it. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"revoke_share_links","x-cypress-action":"vehicles.share_links.revoke_many","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"}},"required":["vehicleIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/visibility":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Public on the marketplace, or only through share links","description":"Sets the vehicles named PUBLIC (on the marketplace) or LINK_ONLY (only whoever holds a share link sees them; the organization needs the Direct Links channel). Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"set_vehicles_visibility","x-cypress-action":"vehicles.visibility.set","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"},"visibility":{"type":"string","enum":["PUBLIC","LINK_ONLY"]}},"required":["vehicleIds","visibility"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/storefront":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Put vehicles on the organization's public storefront, or take them off","description":"Shows the vehicles named on the organization's own storefront page, or takes them off it (the storefront must be published to show anything). Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"set_vehicles_on_storefront","x-cypress-action":"vehicles.storefront.set","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"},"storefrontEnabled":{"type":"boolean"}},"required":["vehicleIds","storefrontEnabled"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/fleet/vehicles":{"post":{"tags":["Vehicles: the app's actions"],"summary":"The fleet page's Add vehicle: the VIN decoded, and valued at once when it is complete","description":"Adds one vehicle as the fleet page's Add vehicle does: the VIN is decoded (year, make, model, trim and specs filled in), and a vehicle sent with its mileage, condition and purchase price is approved and valued on the spot; otherwise it starts as a draft. Since 1.9.0 it takes `keyCount` (0 for none) and the seller's `damageNote`; itemized damage lines are add_vehicle_damage. A VIN already in the organization is refused (409). A Cypress Manager adds into the organization it acts for, when that organization delegated onboarding. To push a full record from your own system with your ids, use create_vehicle (an API key). Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.CREATED`. Since 1.5.0.","operationId":"add_vehicle","x-cypress-action":"vehicles.add","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vin":{"type":"string","minLength":17,"maxLength":17,"pattern":"^[A-HJ-NPR-Z0-9]{17}$"},"fleetId":{"type":"string"},"mileage":{"type":"integer","exclusiveMinimum":0},"exteriorColor":{"type":"string","maxLength":100},"interiorColor":{"type":"string","maxLength":100},"locationCity":{"type":"string","maxLength":100},"locationState":{"type":"string","maxLength":2},"purchaseDate":{"type":"string","format":"date-time"},"purchasePrice":{"type":"number","exclusiveMinimum":0},"condition":{"type":"string","enum":["EXCELLENT","GOOD","FAIR","POOR"]},"keyCount":{"type":"integer","minimum":0,"maximum":99},"damageNote":{"type":"string","maxLength":2000}},"required":["vin"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/fleet/vehicles/{id}":{"patch":{"tags":["Vehicles: the app's actions"],"summary":"The vehicle panel's edits: specs, location, condition, mileage, fleet, prices, visibility","description":"Changes the fields sent, as the vehicle panel's edit does; a field left out is kept, an empty string or null clears it. A change to the condition, the grade, `keyCount` or `damageNote` (since 1.9.0) is told on the car's Updates to every buyer with an open offer. A vehicle in Operation or Planning takes no selling figure (floorPrice, targetPrice, availableAt: 422 PLANNING_STOCK). The floor is the seller's consent line: only a fleet manager or an admin sets it (a Cypress Manager only where the organization delegated pricing), and an agent never sets the floor; an agent sets the target (listing) price under the limits: never below the floor (403 BELOW_FLOOR), never while a live offer or a sale is open (409 CONFLICT). Every change is in the vehicle's activity and reaches webhooks as VEHICLES.UPDATED. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"edit_vehicle","x-cypress-action":"vehicles.edit","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"make":{"type":["string","null"],"maxLength":100},"model":{"type":["string","null"],"maxLength":100},"trim":{"type":["string","null"],"maxLength":200},"bodyClass":{"type":["string","null"],"maxLength":100},"driveType":{"type":["string","null"],"maxLength":100},"engineCylinders":{"type":["string","null"],"maxLength":20},"engineDisplacement":{"type":["string","null"],"maxLength":20},"engineHp":{"type":["string","null"],"maxLength":20},"fuelType":{"type":["string","null"],"maxLength":50},"transmission":{"type":["string","null"],"maxLength":100},"exteriorColor":{"type":["string","null"],"maxLength":100},"interiorColor":{"type":["string","null"],"maxLength":100},"locationCity":{"type":["string","null"],"maxLength":100},"locationState":{"type":["string","null"],"maxLength":2,"description":"Two-letter state"},"locationZip":{"type":["string","null"],"maxLength":10},"locationAddress":{"type":["string","null"],"maxLength":300},"locationName":{"type":["string","null"],"maxLength":200},"condition":{"type":["string","null"],"enum":["EXCELLENT","GOOD","FAIR","POOR"]},"conditionScore":{"type":["number","null"],"minimum":0,"maximum":5,"description":"0 to 5"},"keyCount":{"type":["integer","null"],"minimum":0,"maximum":99,"description":"How many keys come with the car; 0 for none (since 1.9.0)"},"damageNote":{"type":["string","null"],"maxLength":2000,"description":"The seller's own words on the car's damage (since 1.9.0); itemized lines: add_vehicle_damage"},"fleetId":{"type":["string","null"],"maxLength":64,"description":"The fleet it belongs to (list_fleets); null takes it out of its fleet"},"mileage":{"type":["integer","null"],"exclusiveMinimum":0},"year":{"type":["integer","null"],"minimum":1900,"maximum":2100},"category":{"type":"string","enum":["PRIVATE","RENTAL","REPOSITION","FLEET","COMMERCIAL"]},"purchasePrice":{"type":["number","null"],"exclusiveMinimum":0,"description":"USD: what the organization paid"},"floorPrice":{"type":["number","null"],"exclusiveMinimum":0,"description":"USD: the lowest price the seller accepts (a person sets it)"},"targetPrice":{"type":["number","null"],"exclusiveMinimum":0,"description":"USD: the price it lists at (a person sets it)"},"availableAt":{"type":["string","null"],"description":"When it can be sold (ISO date); null clears it"},"marketplaceVisibility":{"type":"string","enum":["PUBLIC","LINK_ONLY"]},"storefrontEnabled":{"type":"boolean"},"conditionChecked":{"type":"boolean","description":"true: you looked at the car and its condition is as set (it is recorded with your name and the time; `conditionCheck` on the vehicle read); false clears it. A person says it: an agent's token may not (PEOPLE_ONLY). Since 1.10.0"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/fleet":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Put up to 500 vehicles in one fleet, or take them out of their fleet","description":"The fleet grid's Assign to fleet: every vehicle named moves to the fleet (list_fleets), or out of any fleet with fleetId null. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"assign_vehicles_to_fleet","x-cypress-action":"vehicles.assign_fleet","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"},"fleetId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"The fleet; null takes the vehicles out of their fleet"}},"required":["vehicleIds","fleetId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/delete":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Delete up to 500 vehicles that have not gone to market","description":"The fleet grid's Delete: removes vehicles in draft, review, pending approval or approved. If any vehicle named is listed, under offer or sold, nothing is deleted and the answer names them (409): delist or archive those instead. Each deleted vehicle is told as VEHICLES.DELETED to the subscriptions that list it. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"delete_vehicles","x-cypress-action":"vehicles.delete_many","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"}},"required":["vehicleIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/status":{"post":{"tags":["Vehicles: the app's actions"],"summary":"The same status step for up to 500 vehicles","description":"The fleet grid's Change status: the step change_vehicle_status takes, for many vehicles at once, each judged by the same rules (a step not open from a vehicle's status, or not open to your role, is refused for it with the reason; the others move). Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"change_vehicles_status","x-cypress-action":"vehicles.transition_many","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"},"transition":{"type":"string","enum":["revert-to-draft","submit-for-review","submit-for-approval","approve","direct-approve","reject","hold","resume","return-to-review","revert-to-listed","start-due-diligence","complete-due-diligence","abort-due-diligence","reopen-due-diligence","revert-to-offer-accepted","confirm-delivery","revert-delivery","archive"],"description":"The step"}},"required":["vehicleIds","transition"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/floor-prices":{"post":{"tags":["Vehicles: the app's actions"],"summary":"A floor for up to 500 vehicles: an amount, or from each vehicle's retail or wholesale valuation","description":"Sets each vehicle's floor (vehicles not yet on the market): `absolute` (the value in USD), `multiplier` (the vehicle's latest retail valuation times the value), `fixed-delta` (that retail valuation plus the value, in USD; negative lowers it) or `wholesale-percent` (since 1.9.0: the latest wholesale valuation plus the value in percent; -2 is 2% under wholesale). In `wholesale-percent` a valuation older than the refresh window (30 days, the window in which Cypress does not pay for a new one) is not used unless `allowStale` is true: revalue_vehicle first. A vehicle that cannot be priced is skipped and named in the answer with its reason (and a `code`, NO_VALUATION or VALUATION_STALE, for the wholesale mode); `floors` lists each vehicle's new floor (with the wholesale and its date in the wholesale mode). A dry run works out every floor and writes nothing. The floor is the seller's consent line: a fleet manager's or an admin's (a Cypress Manager only where the organization delegated pricing); never an agent's. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Since 1.5.0.","operationId":"set_floor_prices","x-cypress-action":"vehicles.floor_prices.set","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"},"mode":{"type":"string","enum":["absolute","multiplier","fixed-delta","wholesale-percent"]},"value":{"type":"number","description":"USD (absolute, fixed-delta), a factor (multiplier) or a percent over wholesale, negative for under (wholesale-percent)"},"allowStale":{"type":"boolean","description":"wholesale-percent: also use a valuation older than the refresh window"}},"required":["vehicleIds","mode","value"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/listing-prices":{"post":{"tags":["Vehicles: the app's actions"],"summary":"A listing price for up to 500 vehicles: an amount, or from each vehicle's floor","description":"Sets each vehicle's listing (target) price: `absolute` (the value in USD), `percent-floor` (the floor plus the value in percent) or `fixed-delta` (the floor plus the value, in USD). Only vehicles in review are changed: any other, and one without a floor in a floor-based mode, is skipped and named in the answer (a car on the market changes through update_listing or edit_vehicle). An agent sets it under the limits: never below a vehicle's floor (403 BELOW_FLOOR, nothing written), never while a live offer or a sale is open on it (409 CONFLICT). Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"set_listing_prices","x-cypress-action":"vehicles.listing_prices.set","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"},"mode":{"type":"string","enum":["absolute","percent-floor","fixed-delta"]},"value":{"type":"number"}},"required":["vehicleIds","mode","value"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/archive-request":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Sold elsewhere, or archive: at once without an open offer or a sale in progress; otherwise Cypress reviews it","description":"The vehicle panel's Sold elsewhere and Archive. Planning stock, and a vehicle with no open offer and no sale in progress, are archived at once (`archived: true`; VEHICLES.DISPOSITION.RESOLVED, automatic). One with an open offer or a sale in progress waits for a Cypress Manager's review (`staged: true`; VEHICLES.DISPOSITION.STAGED now, RESOLVED with the decision): a live listing is paused at once so no buyer offers on a car on its way out, and resumes if the request is rejected. A second request while one waits answers the first. Since 1.9.0 `?dryRun=true` says which path it would take and why, writing nothing: `path` AT_ONCE or CYPRESS_REVIEW, `why` in words, `reviewReason` (OPEN_OFFERS, SALE_IN_PROGRESS), `openOffers`, whether a live listing `pauses`, and `alreadyPending` when a request already waits. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Emits `VEHICLES.DISPOSITION.STAGED`. Since 1.5.0.","operationId":"request_vehicle_archive","x-cypress-action":"vehicles.archive_request","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"disposition":{"type":"string","enum":["SOLD_ELSEWHERE","ARCHIVED"],"description":"SOLD_ELSEWHERE (the default) or a plain ARCHIVED"},"reason":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/damages":{"get":{"tags":["Vehicles: the app's actions"],"summary":"The damage lines the seller declared on a vehicle, with their pictures","description":"Every damage line declared on the vehicle (area, description, severity MINOR, MODERATE, SEVERE or CRITICAL, its picture), oldest first. The seller's statement, not an inspection's finding: get_vehicle_history_report and the vehicle's read have those. Since 1.9.0. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.9.0.","operationId":"list_vehicle_damages","x-cypress-action":"vehicles.damages.list","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Vehicles: the app's actions"],"summary":"Add a damage line to a vehicle: where, what, how bad, and an optional picture","description":"Declares one damage line on the vehicle, a fleet manager's or an admin's (or Cypress staff for the organization): `area` (rear bumper, driver door), `description`, `severity`, and optionally a picture, kept among the car's photos as a DAMAGE photo (never the cover). Every buyer with an open offer on the car is told on their offer (`buyersTold`), the car's activity records it, and it reaches webhooks as VEHICLES.UPDATED with `changedFields: [\"damages\"]`. A seller's statement of the car's condition is a person's act. Since 1.9.0. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.9.0.","operationId":"add_vehicle_damage","x-cypress-action":"vehicles.damages.add","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"area":{"type":"string","minLength":1,"maxLength":100,"description":"Where on the car: rear bumper, hood, driver door"},"description":{"type":"string","minLength":1,"maxLength":1000},"severity":{"type":"string","enum":["MINOR","MODERATE","SEVERE","CRITICAL"]},"contentBase64":{"type":"string","minLength":4,"maxLength":14000000,"description":"The picture, base64 (at most 10 MB)"},"contentType":{"type":"string","pattern":"^image\\/(jpeg|png|webp|heic|heif)$","description":"image/jpeg, image/png, image/webp or image/heic"},"fileName":{"type":"string","maxLength":200}},"required":["area","description","severity"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/damages/{damageId}":{"delete":{"tags":["Vehicles: the app's actions"],"summary":"Remove a damage line declared by mistake","description":"Removes one declared damage line (a correction). Its picture stays among the car's photos (`photoKept`; remove_vehicle_photo takes it off). Buyers with an open offer are told, and it reaches webhooks as VEHICLES.UPDATED. Since 1.9.0. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.9.0.","operationId":"remove_vehicle_damage","x-cypress-action":"vehicles.damages.remove","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"damageId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/notices":{"get":{"tags":["Vehicles: the app's actions"],"summary":"What changed on a vehicle that its seller or Cypress was told about","description":"The notices on one vehicle (a price changed, details or location updated, a document added), newest first, with who they were for. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_vehicle_notices","x-cypress-action":"vehicles.notices.list","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/channel-flow":{"get":{"tags":["Vehicles: the app's actions"],"summary":"How buyers reached a vehicle, channel by channel, to views, offers and a sale","description":"The flow the vehicle's analytics draw: each channel that showed the car (the marketplace, share links, the storefront, campaigns) and how many views, offers and sales came through it, over the period. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_vehicle_channel_flow","x-cypress-action":"vehicles.channel_flow","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/engagement":{"get":{"tags":["Vehicles: the app's actions"],"summary":"Cypress's engagement report on a vehicle: views, reach, offers, over a period","description":"The staff engagement overview of one vehicle: views, unique viewers, the companies reached, offers and their trend over the period. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_vehicle_engagement","x-cypress-action":"vehicles.engagement","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/engagement/breakdowns":{"get":{"tags":["Vehicles: the app's actions"],"summary":"The engagement report cut by channel, region and buyer type","description":"The staff engagement of one vehicle, broken down by channel, by region and by kind of buyer, over the period. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_vehicle_engagement_breakdowns","x-cypress-action":"vehicles.engagement.breakdowns","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/engagement/actors":{"get":{"tags":["Vehicles: the app's actions"],"summary":"The buyers who viewed, saved or offered on a vehicle","description":"The staff list of the companies and people who engaged with one vehicle over the period, each with views, saves and offers. get_vehicle_engagement_actor reads one in full. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_vehicle_engagement_actors","x-cypress-action":"vehicles.engagement.actors","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/engagement/actors/{actorKey}":{"get":{"tags":["Vehicles: the app's actions"],"summary":"One buyer's whole history with a vehicle","description":"Everything one buyer (actorKey, from list_vehicle_engagement_actors) did on the vehicle, across all time. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_vehicle_engagement_actor","x-cypress-action":"vehicles.engagement.actor","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"actorKey","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/forecast":{"get":{"tags":["Planning: the app's actions"],"summary":"The next weeks for your lots: dealer demand and other sellers' supply, as ranges","description":"The Sell rail's \"Next weeks\", as Cedar reads it: for each of your lots, how many vehicles dealers want in the next 13 weeks and in each of your next four sale windows (ranges, from two dealers or more); for each open window, how much other sellers plan of the same lots (a level); and a one-line read. It takes no lot or date: the probes are your own lots and windows. Needs Planning. Needs `planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_sell_forecast","x-cypress-action":"planning.forecast","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/demand":{"get":{"tags":["Planning: the app's actions"],"summary":"Planned dealer demand per lot, and per lot and sale window (counts only)","description":"What the Planning page shows beside each lot: how many vehicles dealers plan to buy of it, overall and in each of the windows named. Lot keys (a year, make and model: \"2025|CHEVY|TRAVERSE\") and window ids come from get_sell_quarter; one you do not hold is ignored. Counts only, no dealer named. Needs `planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_plan_demand","x-cypress-action":"planning.demand","parameters":[{"name":"lotKeys","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":42000,"description":"Lot keys, comma-separated (at most 200)"},"description":"Lot keys, comma-separated (at most 200)"},{"name":"windowIds","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":4200,"description":"Sale window ids, comma-separated (at most 20)"},"description":"Sale window ids, comma-separated (at most 20)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/market-board":{"get":{"tags":["Planning: the app's actions"],"summary":"What dealers want and what sellers plan to bring, across Cypress, anonymously","description":"The Market tab of both Planning pages: the models dealers want (presence only, never a quantity or a name), what sellers plan to bring this quarter by make and model (ranges from three sellers), the models selling fastest, and for those the live listings and the Cypress trend. Your own organization is left out. Needs Sell or Buy planning. Needs `insights:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_market_board","x-cypress-action":"planning.market_board","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/execution":{"get":{"tags":["Planning: the app's actions"],"summary":"The quarter's execution: each handed-off vehicle's stage, ask, best offer and sale against its plan value","description":"The Execution tab: for every vehicle the plan handed to Sell, its stage, ask, best open offer, sale price and days to sale against the plan value frozen at hand-off; with the quarter's goals, attainment, the shortfall ladder and Sequoia's remedies. Read-only: the acts live in Sell. Needs `planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_plan_execution","x-cypress-action":"planning.execution","parameters":[{"name":"periodKey","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","description":"The quarter (the current one when left out)"},"description":"The quarter (the current one when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/reviews":{"get":{"tags":["Planning: the app's actions"],"summary":"Planned against executed per closed window, what became of each vehicle, and the roll-up","description":"The Review tab: each closed sale window's review (planned, handed, slipped, with reasons), what happened to each vehicle after the hand-off (sale price against the frozen plan value and the ask, days to sale, sold elsewhere, left the fleet, returned), the feedback recorded on it, and a roll-up of the outcomes. The newest 12 reviews (of the quarter named, when one is). Needs `planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_window_reviews","x-cypress-action":"planning.reviews.list","parameters":[{"name":"periodKey","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","description":"Only the windows that count in this quarter"},"description":"Only the windows that count in this quarter"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/tasks":{"get":{"tags":["Planning: the app's actions"],"summary":"The tasks behind a side's quarter plan, open and done, with what each is about","description":"The plan's Tasks tab: the tasks about a side's plan (Sell: its goals, windows, lots and the quarter; Buy: its targets and the quarter) for one quarter, or every quarter's with `all`, each with what it is about and whether it was carried over. For the tasks of one goal, window, lot or target, list_tasks filters by it. Needs `tasks:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_plan_tasks","x-cypress-action":"planning.tasks","parameters":[{"name":"side","in":"query","required":true,"schema":{"type":"string","enum":["SELL","BUY"]}},{"name":"periodKey","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$"}},{"name":"all","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"description":"true: every quarter's"},"description":"true: every quarter's"},{"name":"only","in":"query","required":false,"schema":{"type":"string","enum":["quarter"],"description":"quarter: only the tasks about the quarter's plan as a whole"},"description":"quarter: only the tasks about the quarter's plan as a whole"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/decisions":{"get":{"tags":["Planning: the app's actions"],"summary":"Sequoia's suggestions and their answers on the sell plan, with its last run","description":"The Sell rail and the Decisions tab: Sequoia's suggestions with their reasons, confidence and status, live ones best first (`live=1`) or every row newest first, and when Sequoia last read the plan. Answer one with answer_sell_decision. Needs `planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_sell_decisions","x-cypress-action":"planning.decisions.list","parameters":[{"name":"live","in":"query","required":false,"schema":{"type":"string","enum":["0","1"],"description":"1: only the live suggestions (suggested, needs you), best first; left out: every row, newest first"},"description":"1: only the live suggestions (suggested, needs you), best first; left out: every row, newest first"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"periodKey","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","description":"Only this quarter's decisions"},"description":"Only this quarter's decisions"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/groups":{"get":{"tags":["Planning: the app's actions"],"summary":"The fleet's planning groups with their sizes, and the groups Sequoia suggests","description":"The groups the fleet is sorted into for planning (each with its rule, colour and how many vehicles it holds), and the groups Sequoia suggests that are not taken yet. Needs `planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_plan_groups","x-cypress-action":"planning.groups.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Planning: the app's actions"],"summary":"A named group of the fleet, with a rule or without","description":"Defines a group (a name, an optional rule and colour). It holds no vehicles until apply_plan_group (by its rule) or set_plan_group_members (by hand). A name already taken is refused. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"create_plan_group","x-cypress-action":"planning.groups.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":60},"rule":{"type":["object","null"],"properties":{"all":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["year","ageYears","mileage","planningClass","make","model","locationState","band","valueNow","decay13w","stage","lotKey"]},"op":{"type":"string","enum":["lte","gte","eq","neq","in","contains"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"number"},{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"minItems":1,"maxItems":40}]}},"required":["field","op","value"]},"minItems":1,"maxItems":8,"description":"Every condition must hold"}},"required":["all"],"description":"A group's rule: the vehicles it takes"},"color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}$","description":"#RRGGBB"},"source":{"type":"string","enum":["FM","SEQUOIA"],"description":"SEQUOIA when it is one of Sequoia's suggested groups"}},"required":["name"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/cost-assumptions":{"get":{"tags":["Planning: the app's actions"],"summary":"Weekly running cost and contribution per vehicle class, beside the baseline","description":"What a week of keeping a car, SUV, truck or van costs the fleet and earns it, as the plan reckons holding against selling: each figure with the baseline, who set it and when, and how many vehicles carry their own. Needs `planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_plan_cost_assumptions","x-cypress-action":"planning.cost_assumptions.get","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Planning: the app's actions"],"summary":"Set (or clear with null) weekly running cost and contribution per vehicle class","description":"Sets the figures the plan weighs holding against selling with, per class (USD a week; null goes back to the baseline). Settings: audited, no plan version. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"set_plan_cost_assumptions","x-cypress-action":"planning.cost_assumptions.set","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"vehicleClass":{"type":"string","enum":["CAR","SUV","TRUCK","VAN"]},"field":{"type":"string","enum":["weeklyRunningCost","weeklyContribution"]},"value":{"type":["number","null"],"minimum":0,"maximum":10000,"description":"USD a week: running cost 0 to 5,000, contribution 0 to 10,000; null clears"}},"required":["vehicleClass","field","value"]},"minItems":1,"maxItems":8}},"required":["rows"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/vehicles/{id}/cost-assumptions":{"get":{"tags":["Planning: the app's actions"],"summary":"A vehicle's weekly running cost and contribution, where it overrides its class","description":"The figures one vehicle carries over its class's (null: it takes the class's, which get_plan_cost_assumptions reads). Needs `planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_vehicle_plan_costs","x-cypress-action":"planning.vehicle_costs.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Planning: the app's actions"],"summary":"Override (or clear) one vehicle's weekly running cost and contribution","description":"Gives one vehicle its own weekly figures over its class's (null goes back to the class's; a field left out stays). Audited, no plan version. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"set_vehicle_plan_costs","x-cypress-action":"planning.vehicle_costs.set","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"weeklyRunningCost":{"type":["number","null"],"minimum":0,"maximum":5000,"description":"USD a week"},"weeklyContribution":{"type":["number","null"],"minimum":0,"maximum":10000,"description":"USD a week"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/planned-demand":{"get":{"tags":["Planning: the app's actions"],"summary":"How many dealers plan to buy a vehicle like one of yours","description":"How many dealer companies plan to buy a vehicle like this one, and how many such vehicles they still need: counted by company, from two up, never named. The vehicle panel's Leads tab shows it. Needs `insights:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_vehicle_planned_demand","x-cypress-action":"vehicles.planned_demand","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/moves/windows":{"post":{"tags":["Planning: the app's actions"],"summary":"Schedule, reschedule or unschedule vehicles across several sale windows in one plan version","description":"The schedule's moves as the app makes them: each move takes vehicles into a sale window, or (`toWindowId: null`) back to Not scheduled; several moves are ONE plan version (a spread), since window ids change with every version. Window ids are the latest plan's (get_sell_plan). A blocked vehicle is staged as conditional; one that cannot move is answered as skipped. For the bench, operation, parking and tracks, use move_plan_vehicles, park_plan_vehicles and track_plan_vehicles. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `PLAN.VEHICLE.SCHEDULED`. Since 1.5.0.","operationId":"schedule_plan_vehicles","x-cypress-action":"planning.moves.windows","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"moves":{"type":"array","items":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"},"toWindowId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"The sale window; null: back to Not scheduled"}},"required":["vehicleIds","toWindowId"]},"minItems":1,"maxItems":12},"reason":{"type":"string","maxLength":300,"description":"Why: it rides in the plan's history"}},"required":["moves"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/lots/allocate":{"post":{"tags":["Planning: the app's actions"],"summary":"\"Schedule 12 of the 2021 Sentras in October\": the best N of a lot or group, spread over a month's windows","description":"Ranks a lot's (or a group's) unscheduled vehicles under the mandate and the quarter's goals, takes the best N that may be scheduled, and spreads them over one window or a month's open windows (EVEN or FRONT), in one plan version. Disputed evidence is skipped and named, a payoff blocker schedules as waiting, crowding is a warning. A dry run answers the lines it would write, with their order and net cash. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Emits `PLAN.VEHICLE.SCHEDULED`. Since 1.5.0.","operationId":"allocate_plan_lot","x-cypress-action":"planning.lots.allocate","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lotKey":{"type":"string","minLength":1,"maxLength":200,"description":"The lot (\"2021|NISSAN|SENTRA\"); or a groupId"},"groupId":{"type":"string","minLength":1,"maxLength":64,"description":"Allocate from a group instead of a lot"},"subLotKey":{"type":"string","maxLength":40,"description":"A mileage band of the lot (\"60000-75000\")"},"count":{"type":"integer","minimum":1,"maximum":200},"windowId":{"type":"string","minLength":1,"maxLength":64,"description":"One sale window; or a monthKey"},"monthKey":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","description":"YYYY-MM: that month's open windows"},"spread":{"type":"string","enum":["EVEN","FRONT"],"default":"EVEN"},"trackId":{"type":"string","minLength":1,"maxLength":64,"description":"Only this track's vehicles, ranked by its objective"},"reason":{"type":"string","maxLength":300,"description":"Why: it rides in the plan's history"}},"required":["count"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/groups/{id}":{"patch":{"tags":["Planning: the app's actions"],"summary":"Rename a group, recolour it or change its rule","description":"Renames, recolours or changes the rule of a group. Its members change only with apply_plan_group or set_plan_group_members. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"update_plan_group","x-cypress-action":"planning.groups.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":60},"rule":{"type":["object","null"],"properties":{"all":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["year","ageYears","mileage","planningClass","make","model","locationState","band","valueNow","decay13w","stage","lotKey"]},"op":{"type":"string","enum":["lte","gte","eq","neq","in","contains"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"number"},{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"minItems":1,"maxItems":40}]}},"required":["field","op","value"]},"minItems":1,"maxItems":8,"description":"Every condition must hold"}},"required":["all"],"description":"A group's rule: the vehicles it takes"},"color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}$","description":"#RRGGBB"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Planning: the app's actions"],"summary":"Delete a group; its vehicles are left in no group","description":"Deletes a group. Its vehicles stay in the plan, in no group (one plan version when it had members). Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"remove_plan_group","x-cypress-action":"planning.groups.remove","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/groups/{id}/apply":{"post":{"tags":["Planning: the app's actions"],"summary":"The group becomes what its rule matches now, minus the vehicles you leave out","description":"Matches join the group (leaving any other: one group per vehicle), members that no longer match leave; sold vehicles never match. One plan version. A rule sent here is stored on the group. A dry run answers who the rule would take, the group each is in now, how many would leave another group and how many are in Sell: send the rule with it. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Since 1.5.0.","operationId":"apply_plan_group","x-cypress-action":"planning.groups.apply","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"type":"object","properties":{"all":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["year","ageYears","mileage","planningClass","make","model","locationState","band","valueNow","decay13w","stage","lotKey"]},"op":{"type":"string","enum":["lte","gte","eq","neq","in","contains"]},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"number"},{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"minItems":1,"maxItems":40}]}},"required":["field","op","value"]},"minItems":1,"maxItems":8,"description":"Every condition must hold"}},"required":["all"],"description":"A group's rule: the vehicles it takes"},"exclude":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":500,"description":"Matches to leave out"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/groups/members":{"post":{"tags":["Planning: the app's actions"],"summary":"Hand-pick vehicles into a group (or out of any group)","description":"Puts the vehicles named in a group, moving them from any other, or with `groupId: null` out of any group. One plan version. A vehicle that is not the fleet's is answered as skipped. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"set_plan_group_members","x-cypress-action":"planning.groups.members","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"groupId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"null: out of any group"},"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":500,"description":"Vehicle ids, at most 500"}},"required":["groupId","vehicleIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/tracks":{"post":{"tags":["Planning: the app's actions"],"summary":"A custom track: a name, the objective it ranks by, the posture Sell takes","description":"Adds a track to the live strategy: the objective its vehicles are ranked by and the posture Sell takes with them (list at, below or above market; accept from a share of the plan value; urgency). One plan version. The posture sets the price offers are judged by, so this is a person's. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"add_plan_track","x-cypress-action":"planning.tracks.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":60},"objective":{"type":"string","enum":["PRESERVE_VALUE","BALANCED_RENEWAL","EV_MIGRATION","CASH_RELEASE"]},"posture":{"type":"object","properties":{"listAt":{"type":"string","enum":["MARKET","ABOVE","BELOW"],"description":"Where Sell lists the track's vehicles against the market"},"acceptPct":{"type":"number","minimum":0.5,"maximum":1.2,"description":"Accept an offer from this share of the plan value (0.5 to 1.2)"},"urgency":{"type":"string","enum":["FAST","NORMAL","PATIENT"]}},"required":["listAt","acceptPct","urgency"]}},"required":["name","objective","posture"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/tracks/{id}":{"patch":{"tags":["Planning: the app's actions"],"summary":"Rename a track, or change its objective or posture","description":"Changes a track in one plan version. A rename, or a new posture, relabels every vehicle in Sell that rides it. An agent may rename it or change its objective; the posture is a person's. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"change_plan_track","x-cypress-action":"planning.tracks.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":60},"objective":{"type":"string","enum":["PRESERVE_VALUE","BALANCED_RENEWAL","EV_MIGRATION","CASH_RELEASE"]},"posture":{"type":"object","properties":{"listAt":{"type":"string","enum":["MARKET","ABOVE","BELOW"],"description":"Where Sell lists the track's vehicles against the market"},"acceptPct":{"type":"number","minimum":0.5,"maximum":1.2,"description":"Accept an offer from this share of the plan value (0.5 to 1.2)"},"urgency":{"type":"string","enum":["FAST","NORMAL","PATIENT"]}},"required":["listAt","acceptPct","urgency"]}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Planning: the app's actions"],"summary":"Delete a track; its vehicles move to the General track","description":"Deletes a track. Its vehicles move to the default track (labels in Sell follow) and goals lose it. The General track cannot be removed. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"remove_plan_track","x-cypress-action":"planning.tracks.remove","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/blockers/{id}/remove":{"post":{"tags":["Planning: the app's actions"],"summary":"Remove an open blocker that should never have been there, with the reason","description":"Removes an open blocker added by mistake (the wrong vehicle, a duplicate). The reason rides in the plan's history and the vehicle's readiness is evaluated again. A resolved blocker is history and stays; to clear one with its evidence, use change_plan_blocker. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"remove_plan_blocker","x-cypress-action":"planning.blockers.remove","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":300}},"required":["reason"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/vehicles/{id}/details":{"patch":{"tags":["Planning: the app's actions"],"summary":"Year, make, model, odometer, condition, colours, Unit # or location of a vehicle that lives only in planning","description":"Changes the details of a vehicle that lives only in planning; one handed to Sell is refused (IN_SELL), its details are Sell's. Data only: audited field by field, an odometer change is a reading, no valuation is bought and no remarketing automation runs. A field left out stays; null clears it. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"update_plan_vehicle_details","x-cypress-action":"planning.vehicle_details.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":["integer","null"],"minimum":1980,"maximum":2100},"make":{"type":["string","null"],"maxLength":40},"model":{"type":["string","null"],"maxLength":60},"trim":{"type":["string","null"],"maxLength":80},"bodyClass":{"type":["string","null"],"maxLength":40},"driveType":{"type":["string","null"],"maxLength":40},"fuelType":{"type":["string","null"],"maxLength":40},"transmission":{"type":["string","null"],"maxLength":40},"engineCylinders":{"type":["string","null"],"maxLength":20},"engineDisplacement":{"type":["string","null"],"maxLength":20},"engineHp":{"type":["string","null"],"maxLength":20},"mileage":{"type":["integer","null"],"minimum":0,"maximum":2000000,"description":"Miles"},"conditionScore":{"type":["number","null"],"minimum":0,"maximum":5},"exteriorColor":{"type":["string","null"],"maxLength":40},"interiorColor":{"type":["string","null"],"maxLength":40},"category":{"type":["string","null"],"enum":["RENTAL","FLEET","COMMERCIAL","PRIVATE","REPOSITION"]},"stockNumber":{"type":["string","null"],"maxLength":64,"description":"Unit #"},"locationCity":{"type":["string","null"],"maxLength":80},"locationState":{"type":["string","null"],"maxLength":40},"locationName":{"type":["string","null"],"maxLength":120},"locationAddress":{"type":["string","null"],"maxLength":120},"locationZip":{"type":["string","null"],"pattern":"^\\d{5}$"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/decisions/{id}":{"patch":{"tags":["Planning: the app's actions"],"summary":"Accept, dismiss or put off one of Sequoia's suggestions on the sell plan","description":"Records the answer to a live suggestion (list_sell_decisions): accepted, dismissed for the quarter, or put off a week. It only records the answer: the act the suggestion names is its own tool. A row that is no longer live is answered as it is. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `INSIGHT.ANSWERED`. Since 1.5.0.","operationId":"answer_sell_decision","x-cypress-action":"planning.decisions.answer","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ACCEPTED","DISMISSED","SKIPPED"],"description":"ACCEPTED, DISMISSED (not this quarter) or SKIPPED (remind me next week)"}},"required":["status"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/planning/reviews/{id}/feedback":{"post":{"tags":["Planning: the app's actions"],"summary":"Agree, partly agree or disagree with a sale window's review, in words","description":"The fleet manager's verdict on a window review (list_window_reviews). It feeds Sequoia's memory of this fleet and informs its next proposals; it changes no policy. Needs `planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"add_window_review_feedback","x-cypress-action":"planning.reviews.feedback","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"type":"string","enum":["AGREE","PARTIAL","DISAGREE"]},"text":{"type":"string","minLength":3,"maxLength":1000}},"required":["verdict","text"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/planning-request":{"post":{"tags":["Planning: the app's actions"],"summary":"Ask Cypress to switch the Planning product on for your organization","description":"Tells Cypress your organization wants Planning (Sell planning), as the teaser's button does. The first request is kept and Cypress is told once; asking again answers the first request's date. Refused when Planning is already on. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"request_planning","x-cypress-action":"organization.planning.request","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/planning/sell-desk":{"get":{"tags":["Planning: the app's actions"],"summary":"Every seller's lots in the quarter's open windows, with the dealers whose targets match them","description":"The Cypress desk on the Sell side: each seller's lots in the open sale windows with the seller's ask and floor, the dealers whose open targets match them (named, with their target and maximum) and each pair's fit. Both sides' limits: Cypress staff only, every read audited. With an organization named, the desk is about that seller. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_sell_desk","x-cypress-action":"planning.sell_desk","parameters":[{"name":"periodKey","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","description":"The quarter (the current one when left out)"},"description":"The quarter (the current one when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/buy-planning/plan":{"get":{"tags":["Buy planning: the app's actions"],"summary":"The buy plan as its page shows it: settings, the quarter and its approval, targets with progress","description":"The Buy planning page's one read: the plan's settings (buying markets, match notices, digest, default track), the quarter's goal, budget, mandate and approval (with the digest an approval binds to and what changed since), and every target with its progress and live match counts. The quarter's money is the page's own computation: `quarter.spent` is the money on vehicles already bought (the page's \"spent\"; `spentInPlan` + `spentOutsidePlan`), `inClosingAmount` the closings in progress, `spentOrInClosing` both (the Plan tab's \"Spent or in closing\"); `budgetPct` is measured on `spent` (since 1.9.0: before, `spent` included the closings in progress). get_buy_quarter and list_buy_targets read the quarter and the targets on their own; the settings are read only here. Needs `buy-planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_buy_plan","x-cypress-action":"buy-planning.plan.get","parameters":[{"name":"periodKey","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","description":"The quarter (the current one when left out)"},"description":"The quarter (the current one when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"quarter":{"type":"object","properties":{"periodKey":{"type":"string"},"label":{"type":"string"},"unitsGoal":{"type":["integer","null"]},"budget":{"type":["number","null"],"description":"USD; null when unset (a budget of $0 is unset)"},"plannedUnits":{"type":"integer"},"filled":{"type":"integer","description":"Purchases done this quarter (the page's \"bought\")"},"committed":{"type":"integer","description":"Purchases whose closing is in progress (the page's \"in closing\")"},"outsidePlan":{"type":"integer","description":"Purchases this quarter no target claimed (done or in closing)"},"spent":{"type":"number","description":"USD: money on vehicles already bought this quarter, in the plan and outside it: the page's \"spent\""},"spentInPlan":{"type":"number","description":"USD: the part of `spent` a target claimed"},"spentOutsidePlan":{"type":"number","description":"USD: the part of `spent` no target claimed"},"inClosingAmount":{"type":"number","description":"USD: money on closings in progress (not spent yet)"},"inClosingOutsidePlan":{"type":"number","description":"USD: the part of `inClosingAmount` no target claimed"},"spentOrInClosing":{"type":"number","description":"USD: `spent` + `inClosingAmount`: the Plan tab's \"Spent or in closing\""},"budgetPct":{"type":["number","null"],"description":"`spent` against the budget, in percent; null with no budget"},"spentOrInClosingPct":{"type":["number","null"],"description":"`spentOrInClosing` against the budget, in percent; null with no budget"}},"required":["periodKey","label","unitsGoal","budget","plannedUnits","filled","committed","outsidePlan","spent","spentInPlan","spentOutsidePlan","inClosingAmount","inClosingOutsidePlan","spentOrInClosing","budgetPct","spentOrInClosingPct"],"description":"The quarter's numbers, as the page's header and Plan tab show them (absent from a staff token's portfolio, mode \"portfolio\")"}}}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Buy planning: the app's actions"],"summary":"Where you buy, how you hear about matches, and the default track for new targets","description":"The buy plan's settings: the states you buy in, whether each new match is told and whether a digest is sent, a note, and the track new targets take. Every field is set as sent (a note left out is cleared), except `defaultTrack`, kept when left out. The match badges are read again and so is Sequoia's advice. Needs `buy-planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"set_buy_plan_settings","x-cypress-action":"buy-planning.plan.settings","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"states":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2}$"},"maxItems":60,"description":"The two-letter state codes the plan buys in"},"notifyMatches":{"type":"boolean"},"digest":{"type":"boolean"},"note":{"type":["string","null"],"maxLength":2000},"defaultTrack":{"type":"string","enum":["AGGRESSIVE","BALANCED","CONSERVATIVE"],"description":"Left out: kept"}},"required":["states","notifyMatches","digest"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/buy-planning/forecast":{"get":{"tags":["Buy planning: the app's actions"],"summary":"The next weeks for your targets: what fits now, and what sellers plan to bring","description":"The Buy rail's \"Next weeks\", as Cedar reads it: the listings that fit the plan now and, for each open target still due, its live fits, what sellers plan to bring to market by when (ranges, from two sellers or more) and a one-line read. Your own saved targets are the probes. Needs `buy-planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_buy_forecast","x-cypress-action":"buy-planning.forecast","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/buy-planning/fit":{"get":{"tags":["Buy planning: the app's actions"],"summary":"For listings you are looking at: the target each fits, and how well","description":"The Marketplace's \"fits my plan\" badges: for each listing named, the one of your targets it fits best, with the target's label and a score. A listing that fits none, one of your own and one you hid from a target are left out. It reads your own targets only, so no seller learns who matched. Needs `buy-planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_buy_fit","x-cypress-action":"buy-planning.fit","parameters":[{"name":"vehicleIds","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":21000,"description":"Listing (vehicle) ids, comma-separated (at most 100)"},"description":"Listing (vehicle) ids, comma-separated (at most 100)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/buy-planning/targets/{id}/matches/{vehicleId}/analysis":{"get":{"tags":["Buy planning: the app's actions"],"summary":"One listing against one of your targets: price position, trend, timing, your fit and budget","description":"The Buy analysis of a live listing that matches one of your targets: where its price sits in the market, the Cypress trend to the target's needed-by week, the timing against other fits and planned supply, and your own fit and budget. Nothing of the seller beyond the public listing. A listing that does not match the target is not found. Needs `buy-planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_buy_match_analysis","x-cypress-action":"buy-planning.matches.analysis","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The buy target"}},{"name":"vehicleId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/buy-planning/catalog":{"get":{"tags":["Buy planning: the app's actions"],"summary":"The makes, models, trims, bodies and fuels Cypress has seen, to name in a target","description":"What a buy target's spec may name, as the target editor offers it: the makes (or a make's models, or a model's trims; or the body styles or fuels) Cypress has seen, most seen first, with counts. No price, no seller. Needs `buy-planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"search_buy_catalog","x-cypress-action":"buy-planning.catalog","parameters":[{"name":"kind","in":"query","required":true,"schema":{"type":"string","enum":["make","model","trim","body","fuel"]}},{"name":"make","in":"query","required":false,"schema":{"type":"string","maxLength":60,"description":"With kind model or trim"},"description":"With kind model or trim"},{"name":"model","in":"query","required":false,"schema":{"type":"string","maxLength":60,"description":"With kind trim"},"description":"With kind trim"},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":60,"description":"Only options whose name contains this"},"description":"Only options whose name contains this"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/buy-planning/decisions":{"get":{"tags":["Buy planning: the app's actions"],"summary":"Sequoia's suggestions and their answers on the buy plan, with its last run","description":"The Buy rail and the Decisions tab: Sequoia's suggestions with their reasons, confidence and status, live ones best first (`live=1`) or every row newest first, and when Sequoia last read the plan. Answer one with answer_buy_decision. Needs `buy-planning:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_buy_decisions","x-cypress-action":"buy-planning.decisions.list","parameters":[{"name":"live","in":"query","required":false,"schema":{"type":"string","enum":["0","1"],"description":"1: only the live suggestions (suggested, needs you), best first; left out: every row, newest first"},"description":"1: only the live suggestions (suggested, needs you), best first; left out: every row, newest first"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500}},{"name":"periodKey","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","description":"Only this quarter's decisions"},"description":"Only this quarter's decisions"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/buy-planning/decisions/{id}":{"patch":{"tags":["Buy planning: the app's actions"],"summary":"Accept, dismiss or put off one of Sequoia's suggestions on the buy plan","description":"Records the answer to a live suggestion (list_buy_decisions): accepted, dismissed for the quarter, or put off a week. It only records the answer: the act the suggestion names is its own tool. Needs `buy-planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `INSIGHT.ANSWERED`. Since 1.5.0.","operationId":"answer_buy_decision","x-cypress-action":"buy-planning.decisions.answer","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ACCEPTED","DISMISSED","SKIPPED"],"description":"ACCEPTED, DISMISSED (not this quarter) or SKIPPED (remind me next week)"}},"required":["status"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/buy-planning/targets/{id}/bundle-requests":{"post":{"tags":["Buy planning: the app's actions"],"summary":"Ask Cypress to work several of a target's matches from one seller as a bundle","description":"\"Ask Cypress to bundle\": two or more current matches of one target, all from one seller. Cypress staff are told (with the seller); your audit trail never names it. Cypress then works the bundle with per-vehicle offers. Needs `buy-planning:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"request_buy_bundle","x-cypress-action":"buy-planning.bundle_request","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The buy target"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":2,"maxItems":50,"description":"Two or more matches, from one seller"},"note":{"type":"string","maxLength":1000}},"required":["vehicleIds"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/buy-planning-request":{"post":{"tags":["Buy planning: the app's actions"],"summary":"Ask Cypress to switch Buy planning on for your organization","description":"Tells Cypress your organization wants Buy planning, as the teaser's button does. The first request is kept and Cypress is told once; asking again answers the first request's date. Refused when Buy planning is already on. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"request_buy_planning","x-cypress-action":"organization.buy_planning.request","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/buy-planning/board":{"get":{"tags":["Buy planning: the app's actions"],"summary":"The demand board: every dealer's open targets and what fits them, with both sides' limits","description":"The Cypress desk on the Buy side: each dealer's open targets with what they still need, their target and maximum prices, the live matches, the win-win fits and the best one, unlisted stock that fits, and whether the dealer delegated offers to Cypress. Both sides' limits: Cypress staff only, every read audited. With an organization named, the board is about that dealer. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_buy_board","x-cypress-action":"buy-planning.board","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts/{id}/deliverability":{"get":{"tags":["CRM: the app's actions"],"summary":"Whether a contact's address can still be mailed, and why not","description":"What the contact panel says about the address: `unreachable` (it bounced or unsubscribed, and since when: Cypress will not mail it) and `lastFailedAttempt` (the last send that failed, shown even when the address is not suppressed, since a soft bounce does not suppress). Read it before email_contact or before putting the contact in a campaign. Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_contact_deliverability","x-cypress-action":"contacts.deliverability","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The contact's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts/{id}/business-suggestion":{"get":{"tags":["CRM: the app's actions"],"summary":"The business of your book an unattached contact probably works at","description":"For a contact with no business: the business of your book that matches their email domain or company name, with the reason, or null. Only a suggestion: attach them with update_contact (businessId). Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"suggest_contact_business","x-cypress-action":"contacts.business_suggestion","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The contact's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts/{id}/engagement":{"get":{"tags":["CRM: the app's actions"],"summary":"A contact's engagement with you: the cars they viewed, saved and offered on, the emails they opened","description":"The contact's engagement as the record's Engagement tab shows it: what they looked at, saved and made offers on, and how they answered your mail, with you only (what they do with other sellers is not yours to read). Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_contact_engagement","x-cypress-action":"contacts.engagement","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The contact's Cypress id"}},{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["buyer","seller"],"description":"Cypress staff only: the seller direction. Everyone else reads the buyer direction, what happened with them"},"description":"Cypress staff only: the seller direction. Everyone else reads the buyer direction, what happened with them"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts/{id}/timeline":{"get":{"tags":["CRM: the app's actions"],"summary":"Everything that happened with a contact, newest first","description":"The record's Timeline: emails sent, opened and clicked, site visits, interactions, notes, deal stage moves and tasks, in one list, newest first. list_contact_interactions and list_contact_notes read one kind each. Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_contact_timeline","x-cypress-action":"contacts.timeline","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The contact's Cypress id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":10,"maximum":300,"description":"At most this many entries (100 when left out)"},"description":"At most this many entries (100 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts/{id}/insight":{"get":{"tags":["CRM: the app's actions"],"summary":"Sakura's read on a customer: a profile label, what it sees, and what to do next","description":"The customer profile Sakura writes from the contact's engagement with you: a label, the read and a recommendation. Served from a cache up to a day old; `refresh` writes it again. Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_contact_insight","x-cypress-action":"contacts.insight","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The contact's Cypress id"}},{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["buyer","seller"],"description":"Cypress staff only: the seller direction. Everyone else reads the buyer direction, what happened with them"},"description":"Cypress staff only: the seller direction. Everyone else reads the buyer direction, what happened with them"},{"name":"refresh","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"description":"true writes it again now instead of serving the cached read (an AI call: use it after something changed, not on every read)"},"description":"true writes it again now instead of serving the cached read (an AI call: use it after something changed, not on every read)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/businesses/{id}/engagement":{"get":{"tags":["CRM: the app's actions"],"summary":"A business's engagement with you, all its people merged","description":"The company grain of get_contact_engagement: what everyone at the business viewed, saved and offered on, and how they answered your mail, with you only. Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_business_engagement","x-cypress-action":"businesses.engagement","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The business's Cypress id"}},{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["buyer","seller"],"description":"Cypress staff only: the seller direction. Everyone else reads the buyer direction, what happened with them"},"description":"Cypress staff only: the seller direction. Everyone else reads the buyer direction, what happened with them"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/businesses/{id}/timeline":{"get":{"tags":["CRM: the app's actions"],"summary":"A business's history: its own record, its people's and its pipeline, newest first","description":"The company record's Timeline: its own notes and interactions, its people's timelines (each entry naming the person) and its deals' moves, newest first. Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_business_timeline","x-cypress-action":"businesses.timeline","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The business's Cypress id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":10,"maximum":300,"description":"At most this many entries (100 when left out)"},"description":"At most this many entries (100 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/businesses/{id}/insight":{"get":{"tags":["CRM: the app's actions"],"summary":"Sakura's read on a business, at the company grain","description":"get_contact_insight for a company: Sakura's label, read and recommendation from everyone at the business. Cached up to a day; `refresh` writes it again. Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_business_insight","x-cypress-action":"businesses.insight","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The business's Cypress id"}},{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["buyer","seller"],"description":"Cypress staff only: the seller direction. Everyone else reads the buyer direction, what happened with them"},"description":"Cypress staff only: the seller direction. Everyone else reads the buyer direction, what happened with them"},{"name":"refresh","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"description":"true writes it again now instead of serving the cached read (an AI call: use it after something changed, not on every read)"},"description":"true writes it again now instead of serving the cached read (an AI call: use it after something changed, not on every read)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deals/{id}/timeline":{"get":{"tags":["CRM: the app's actions"],"summary":"Everything on a deal: what was said and written, stage moves, cars added and dropped","description":"The deal's Timeline: its interactions and notes, its changes, its stage moves and the cars that came and went, newest first. Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_deal_timeline","x-cypress-action":"deals.timeline","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The deal's Cypress id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":10,"maximum":300,"description":"At most this many entries (100 when left out)"},"description":"At most this many entries (100 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deals/{id}/insight":{"get":{"tags":["CRM: the app's actions"],"summary":"Sakura's read on a deal: where it stands, the next action and the channel for it","description":"The deal panel's Sakura card: a short read of the deal and the next action with its channel (call, email…). Cached up to 12 hours; `refresh` writes it again. create_task schedules the step. Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_deal_insight","x-cypress-action":"deals.insight","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The deal's Cypress id"}},{"name":"refresh","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"description":"true writes it again now instead of serving the cached read (an AI call: use it after something changed, not on every read)"},"description":"true writes it again now instead of serving the cached read (an AI call: use it after something changed, not on every read)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deals/{id}/contacts":{"get":{"tags":["CRM: the app's actions"],"summary":"A deal's point of contact and everyone else on it, with their role","description":"The people on a deal: its primary point of contact (flagged `isPrimary`) and everyone added with add_deal_contact, each with their role (the signer, the fleet manager…). Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_deal_contacts","x-cypress-action":"deals.contacts.list","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The deal's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["CRM: the app's actions"],"summary":"Put a contact of your book on a deal, with their role, or make them its point of contact","description":"The deal's People: adds a contact with a role (the signer, the fleet manager…); with `primary: true` they become the deal's point of contact and the current one stays on the deal as a secondary. Needs `crm:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"add_deal_contact","x-cypress-action":"deals.contacts.add","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The deal's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string","minLength":1,"maxLength":64,"description":"The contact's Cypress id"},"role":{"type":["string","null"],"maxLength":80,"description":"What they are on this deal"},"primary":{"type":"boolean","description":"Make them the point of contact"}},"required":["contactId"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/crm/analytics":{"get":{"tags":["CRM: the app's actions"],"summary":"The acquisition and sales funnels, KPIs, stages, lost reasons and sources of your book","description":"The CRM's Analytics tab for a period (by when records were created): the acquisition funnel (contacts reached, engaged, onboarded), the sales funnel, the KPIs (open pipeline, win rate, vehicles sold, GMV), each stage's count, value and days, why deals were lost, and the best sources. Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_crm_analytics","x-cypress-action":"crm.analytics","parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/crm/insight":{"get":{"tags":["CRM: the app's actions"],"summary":"Sakura's summary of the whole CRM: what needs you","description":"The CRM's Sakura card: a short read of the whole book. Cached up to 6 hours; `refresh` writes it again. Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_crm_insight","x-cypress-action":"crm.insight","parameters":[{"name":"refresh","in":"query","required":false,"schema":{"type":"string","enum":["true","false"],"description":"true writes it again now instead of serving the cached read (an AI call: use it after something changed, not on every read)"},"description":"true writes it again now instead of serving the cached read (an AI call: use it after something changed, not on every read)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts/{id}/delete":{"post":{"tags":["CRM: the app's actions"],"summary":"Delete a contact with its notes, interactions, tasks and change history","description":"The record's Delete: the contact goes, with its notes, logged interactions, tasks, Sakura profile and change history; its deals stay, without them. Refused (409) for a contact that became an organization on Cypress (it is the record of that): mark them dormant with update_contact instead. Needs `crm:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CONTACT.DELETED`. Since 1.5.0.","operationId":"delete_contact","x-cypress-action":"contacts.delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The contact's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/businesses/{id}/delete":{"post":{"tags":["CRM: the app's actions"],"summary":"Delete a company that has no deals; its people stay, unattached","description":"The record's Delete: the business goes with its notes and change history; its people are kept, with no company. Refused (409) when it has deals (close or move them first) or became an organization on Cypress. Needs `crm:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `BUSINESS.DELETED`. Since 1.5.0.","operationId":"delete_business","x-cypress-action":"businesses.delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The business's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deals/{id}/delete":{"post":{"tags":["CRM: the app's actions"],"summary":"Delete a deal that never reached a real offer","description":"The deal's Delete, with its notes and change history. Refused (409) when one of its cars has a real offer: that deal is part of the sales record, so move it to LOST with move_deal_stage instead. Needs `crm:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `DEAL.DELETED`. Since 1.5.0.","operationId":"delete_deal","x-cypress-action":"deals.delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The deal's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/businesses/from-organization":{"post":{"tags":["CRM: the app's actions"],"summary":"A company that came through your share links (or an organization you picked) as a business of your book","description":"The Direct Links visitor panel's Add to CRM: makes (or opens) the business for a company organization, by its id (list_share_link_visitors names them). A company, never a person: a private individual is refused (422); you learn who they are if they make an offer. Needs `crm:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `BUSINESS.CREATED`. Since 1.5.0.","operationId":"add_business_from_organization","x-cypress-action":"businesses.from_organization","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organizationId":{"type":"string","minLength":1,"maxLength":64,"description":"The visiting company's organization id"}},"required":["organizationId"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deals/{id}/contacts/remove":{"post":{"tags":["CRM: the app's actions"],"summary":"Remove a contact from a deal (the deal and the contact stay)","description":"Takes the contact off the deal. Removing the point of contact leaves the deal with its business only, and is refused (422) when the deal has no business. Needs `crm:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"remove_deal_contact","x-cypress-action":"deals.contacts.remove","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The deal's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactId":{"type":"string","minLength":1,"maxLength":64,"description":"The contact's Cypress id"}},"required":["contactId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deals/{id}/vehicles":{"post":{"tags":["CRM: the app's actions"],"summary":"Add up to 200 of your vehicles to a deal","description":"The deal's Add vehicles: every vehicle named goes on the deal (one already there stays). A vehicle that is not yours to sell refuses the whole call (403) and is named. Needs `crm:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"add_deal_vehicles","x-cypress-action":"deals.vehicles.add","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The deal's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":200,"description":"Vehicle ids, at most 200"}},"required":["vehicleIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deals/{id}/vehicles/remove":{"post":{"tags":["CRM: the app's actions"],"summary":"Drop cars from a deal (kept as DROPPED) or remove them","description":"With `drop: true` the cars stay on the deal's record as DROPPED; without it their lines are removed, which a car with an offer on this deal refuses (409: drop it instead). Needs `crm:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"remove_deal_vehicles","x-cypress-action":"deals.vehicles.remove","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The deal's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":200,"description":"Vehicle ids, at most 200"},"drop":{"type":"boolean","description":"Keep the line as DROPPED rather than remove it"}},"required":["vehicleIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/crm/imports":{"post":{"tags":["CRM: the app's actions"],"summary":"The CRM import: up to 5,000 rows of companies, people and deals; a dry run previews every row","description":"The CRM Import wizard. A dry run answers each row's intent (create, fill blanks, skip) and its issues, computed from your book, and writes nothing; a real run checks the rows again and imports them in the background (202, with the batch: get_crm_import follows it). Blanks are filled, never overwritten. Each record made sends its own CONTACT.CREATED, BUSINESS.CREATED or DEAL.CREATED. Send the same `clientRequestId` when retrying a run whose answer was lost. Needs `crm:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Since 1.5.0.","operationId":"import_crm_records","x-cypress-action":"crm.imports.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"type":"object","properties":{"businessName":{"type":"string","maxLength":500},"contactName":{"type":"string","maxLength":500},"firstName":{"type":"string","maxLength":500},"lastName":{"type":"string","maxLength":500},"email":{"type":"string","maxLength":500},"phone":{"type":"string","maxLength":500},"state":{"type":"string","maxLength":500},"city":{"type":"string","maxLength":500},"website":{"type":"string","maxLength":500},"tags":{"type":"string","maxLength":500,"description":"Comma separated"},"dealTitle":{"type":"string","maxLength":500},"dealStage":{"type":"string","maxLength":500},"dealAmount":{"type":"string","maxLength":500,"description":"USD"}}},"minItems":1,"maxItems":5000},"options":{"type":"object","properties":{"source":{"type":"string","minLength":1,"maxLength":120,"description":"Provenance written on every record (import when left out)"},"defaultTags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20},"createOnboardingDealPerNewBusiness":{"type":"boolean"},"clientRequestId":{"type":"string","minLength":8,"maxLength":64,"description":"One per import: a retry with it finds the batch instead of making a second"}}}},"required":["rows"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"202":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/crm/imports/{batchId}":{"get":{"tags":["CRM: the app's actions"],"summary":"An import's status, with what happened to each row","description":"The import import_crm_records started: its status (PENDING, IMPORTING, COMPLETE, FAILED), its counts and each row's outcome (SUCCESS, SKIPPED, ERROR, with the reason). Needs `crm:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_crm_import","x-cypress-action":"crm.imports.get","parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The batch import_crm_records answered"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/businesses/{id}/link-organization":{"post":{"tags":["CRM: the app's actions"],"summary":"Record that a prospect business became an organization on Cypress, or clear a wrong link","description":"The business record's Link to organization: sets the organization the business became (a customer organization), which wins its open onboarding deals; `organizationId: null` clears a link made in error. A business already linked elsewhere is refused (409): clear it first. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"link_business_organization","x-cypress-action":"businesses.link_organization","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The business's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organizationId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"The customer organization; null clears the link"}},"required":["organizationId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts/{id}/account-candidates":{"get":{"tags":["CRM: the app's actions"],"summary":"The Cypress accounts a contact could be: their own addresses, or people at their company's organization","description":"The contact record's Convert: accounts that match one of the contact's addresses, or members of the organization their business became, each with why. Names and emails of members of other organizations: Cypress staff only on the API. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_contact_account_candidates","x-cypress-action":"contacts.account_candidates","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The contact's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts/{id}/link-account":{"post":{"tags":["CRM: the app's actions"],"summary":"Record that a contact is a person with an account on Cypress","description":"Links the contact to the account (list_contact_account_candidates names them); the contact becomes ON_PLATFORM. A contact linked to someone else is refused (409). Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"link_contact_account","x-cypress-action":"contacts.link_account","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The contact's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","minLength":1,"maxLength":64,"description":"The account"}},"required":["userId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/content":{"patch":{"tags":["Marketing: the app's actions"],"summary":"A campaign's content kind, its promotion, its message document, reply-to and vehicle sheet","description":"The campaign editor's Content card, the part update_campaign does not reach: what it carries (PROMOTION, MESSAGE or INVENTORY), which promotion (null detaches it), the message as a document, whether the promotion's own copy or yours is sent, where replies land (null: the author's mailbox) and whether the vehicle sheet is attached. A live campaign's next send carries the change. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"set_campaign_content","x-cypress-action":"campaigns.content.set","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The campaign's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contentKind":{"type":"string","enum":["PROMOTION","MESSAGE","INVENTORY"]},"promotionId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"A promotion of yours (list_promotions); null detaches it"},"bodyDocument":{"type":["object","null"],"additionalProperties":{},"description":"The message as the editor's document (blocks); null clears it"},"useCustomMessage":{"type":"boolean","description":"Send your message rather than the promotion's own copy"},"replyToEmail":{"type":["string","null"],"maxLength":254,"format":"email","description":"Where a reply lands; null: the author's own mailbox"},"attachVehicleSheet":{"type":"boolean","description":"Attach the spreadsheet of the cars"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/preview":{"get":{"tags":["Marketing: the app's actions"],"summary":"The campaign email rendered as an inbox shows it, for a sample contact","description":"The email the next send would deliver, rendered from the same template (hero, cars, call to action, footer) for a sample contact: `full` (a contact with a name and company) or `sparse` (only an email). Answers the subject and the HTML. Read it before activate_campaign or send_campaign_now. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"preview_campaign_email","x-cypress-action":"campaigns.preview","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The campaign's Cypress id"}},{"name":"contact","in":"query","required":false,"schema":{"type":"string","enum":["full","sparse"],"description":"The sample contact (full when left out)"},"description":"The sample contact (full when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/recipients":{"get":{"tags":["Marketing: the app's actions"],"summary":"Who a campaign mailed, address by address, and how far each email got","description":"The Delivery tab: each recipient's address and status (FAILED, BOUNCED, UNSUBSCRIBED, VIEWED, CLICKED, OPENED, DELIVERED, SENT, PENDING: the most final wins) with its timestamps, 50 a page. Real sends only, unless `sendId` names a test send. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"list_campaign_recipients","x-cypress-action":"campaigns.recipients.list","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The campaign's Cypress id"}},{"name":"sendId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"One send (list_campaign_sends)"},"description":"One send (list_campaign_sends)"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["FAILED","BOUNCED","UNSUBSCRIBED","VIEWED","CLICKED","OPENED","DELIVERED","SENT","PENDING"]}},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Part of an address"},"description":"Part of an address"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/audience/estimate":{"post":{"tags":["Marketing: the app's actions"],"summary":"How many people an audience would mail, and how many suppression drops, before you save it","description":"The editor's reach line for an audience you send (saved or not), resolved against the campaign owner's subscribers or book: `resolved`, `estimate` (who would be mailed), `suppressed` (bounced or unsubscribed, dropped), and for a CRM slice its description and whether it is the whole book. Writes nothing; its dry run answers the same. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Since 1.5.0.","operationId":"estimate_campaign_audience","x-cypress-action":"campaigns.audience.estimate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The campaign's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["filter","cherry-pick","email-list","subscribers","crm"],"description":"subscribers (your storefront's), crm (a slice of your book), email-list (addresses you paste), filter or cherry-pick (Cypress staff only)"},"crm":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":2000},"businessIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":500},"lifecycle":{"type":"array","items":{"type":"string","enum":["PROSPECT","REACHED","ENGAGED","ON_PLATFORM","ACTIVE","DORMANT"]}},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20},"withoutOpenDeal":{"type":"boolean","description":"Only people with no open deal"},"engagedUnworked":{"type":"boolean","description":"Only people who engaged and nobody has worked yet"}},"description":"With crm: which part of your book"},"emails":{"type":"array","items":{"type":"string","maxLength":320},"maxItems":5000,"description":"With email-list"},"roles":{"type":"array","items":{"type":"string","enum":["BUYER","SELLER"]},"description":"With filter (staff)"},"segments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["alert-matched","behavioral","active-recent"]},"days":{"type":"integer","exclusiveMinimum":0}},"required":["kind"]},"description":"With filter (staff)"},"orgIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"description":"With cherry-pick (staff)"},"excludeOrgIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"description":"With filter (staff): companies left out"}},"required":["mode"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/audience/contacts":{"post":{"tags":["Marketing: the app's actions"],"summary":"The contacts a slice of your book would mail, named, with the book's reachable count","description":"The CRM audience's list of people, resolved exactly as the send resolves it (suppression and the consumer-consent door included, so a private individual who never opted in is never listed): the total, the first names with their company and lifecycle, and the book's size, reachable and unreachable. Writes nothing. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Since 1.5.0.","operationId":"preview_campaign_contacts","x-cypress-action":"campaigns.audience.contacts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The campaign's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":2000},"businessIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":500},"lifecycle":{"type":"array","items":{"type":"string","enum":["PROSPECT","REACHED","ENGAGED","ON_PLATFORM","ACTIVE","DORMANT"]}},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20},"withoutOpenDeal":{"type":"boolean","description":"Only people with no open deal"},"engagedUnworked":{"type":"boolean","description":"Only people who engaged and nobody has worked yet"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/test":{"post":{"tags":["Marketing: the app's actions"],"summary":"Email a test of the campaign to up to 20 addresses","description":"The editor's Test now: the campaign as it stands goes to the addresses named (at most 20), marked as a test (never counted in analytics, no event). Suppressed addresses are skipped and named. Delivery is asynchronous: get_campaign_test_send says how it went. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"send_campaign_test","x-cypress-action":"campaigns.test_send","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The campaign's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"string","maxLength":320},"minItems":1,"maxItems":20,"description":"Where the test goes"}},"required":["emails"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Marketing: the app's actions"],"summary":"The last test send: its status, how many it went to and how many were delivered","description":"The last test send_campaign_test made: its status, when it went, how many it was for, how many the provider accepted, and why it failed if it did. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_campaign_test_send","x-cypress-action":"campaigns.test_send.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The campaign's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/audience/candidates":{"post":{"tags":["Marketing: the app's actions"],"summary":"The companies a filter audience would address, before exclusions","description":"The editor's company checklist for a filter audience (roles and segments over the whole platform), before `excludeOrgIds` is taken out; an email-list audience answers its addresses. Cypress staff only. Cypress staff only: a CM token. `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Since 1.5.0.","operationId":"list_campaign_audience_candidates","x-cypress-action":"campaigns.platform.audience_candidates","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The campaign's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["filter","cherry-pick","email-list","subscribers","crm"],"description":"subscribers (your storefront's), crm (a slice of your book), email-list (addresses you paste), filter or cherry-pick (Cypress staff only)"},"crm":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":2000},"businessIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":500},"lifecycle":{"type":"array","items":{"type":"string","enum":["PROSPECT","REACHED","ENGAGED","ON_PLATFORM","ACTIVE","DORMANT"]}},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20},"withoutOpenDeal":{"type":"boolean","description":"Only people with no open deal"},"engagedUnworked":{"type":"boolean","description":"Only people who engaged and nobody has worked yet"}},"description":"With crm: which part of your book"},"emails":{"type":"array","items":{"type":"string","maxLength":320},"maxItems":5000,"description":"With email-list"},"roles":{"type":"array","items":{"type":"string","enum":["BUYER","SELLER"]},"description":"With filter (staff)"},"segments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["alert-matched","behavioral","active-recent"]},"days":{"type":"integer","exclusiveMinimum":0}},"required":["kind"]},"description":"With filter (staff)"},"orgIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"description":"With cherry-pick (staff)"},"excludeOrgIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"description":"With filter (staff): companies left out"}},"required":["mode"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/organizations":{"get":{"tags":["Marketing: the app's actions"],"summary":"Business organizations on Cypress, for a cherry-pick audience","description":"The cherry-pick picker: active and provisional business organizations by name, buyers or sellers. Cypress staff only (not while acting for an organization). Cypress staff only: a CM token. Since 1.5.0.","operationId":"search_campaign_organizations","x-cypress-action":"campaigns.platform.organizations","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"roles","in":"query","required":false,"schema":{"type":"string","maxLength":40,"description":"BUYER, SELLER or both, comma separated"},"description":"BUYER, SELLER or both, comma separated"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/platform":{"patch":{"tags":["Marketing: the app's actions"],"summary":"The whole campaign editor for Cypress staff: platform audiences, owner, status","description":"Everything the editor saves, for Cypress staff: content, schedule, any audience (filter and cherry-pick included, which update_campaign refuses), who the campaign belongs to (until it first sends), and its status (ACTIVE starts sending on its schedule; PAUSED sends CAMPAIGN.PAUSED). Activation is refused with its blockers (422). Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"edit_platform_campaign","x-cypress-action":"campaigns.platform.edit","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The campaign's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"goal":{"type":"string","enum":["VEHICLE_SALE","ONBOARDING"]},"contentKind":{"type":"string","enum":["PROMOTION","MESSAGE","INVENTORY"]},"promotionId":{"type":["string","null"],"minLength":1,"maxLength":64},"startDate":{"type":["string","null"],"format":"date-time"},"endDate":{"type":["string","null"],"format":"date-time"},"subject":{"type":["string","null"],"maxLength":300},"body":{"type":["string","null"],"maxLength":20000},"replyToEmail":{"type":["string","null"],"maxLength":254,"format":"email"},"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":200},"attachVehicleSheet":{"type":"boolean"},"useCustomMessage":{"type":"boolean"},"bodyDocument":{"type":["object","null"],"additionalProperties":{}},"audienceConfig":{"type":"object","properties":{"mode":{"type":"string","enum":["filter","cherry-pick","email-list","subscribers","crm"],"description":"subscribers (your storefront's), crm (a slice of your book), email-list (addresses you paste), filter or cherry-pick (Cypress staff only)"},"crm":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":2000},"businessIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":500},"lifecycle":{"type":"array","items":{"type":"string","enum":["PROSPECT","REACHED","ENGAGED","ON_PLATFORM","ACTIVE","DORMANT"]}},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":40},"maxItems":20},"withoutOpenDeal":{"type":"boolean","description":"Only people with no open deal"},"engagedUnworked":{"type":"boolean","description":"Only people who engaged and nobody has worked yet"}},"description":"With crm: which part of your book"},"emails":{"type":"array","items":{"type":"string","maxLength":320},"maxItems":5000,"description":"With email-list"},"roles":{"type":"array","items":{"type":"string","enum":["BUYER","SELLER"]},"description":"With filter (staff)"},"segments":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["alert-matched","behavioral","active-recent"]},"days":{"type":"integer","exclusiveMinimum":0}},"required":["kind"]},"description":"With filter (staff)"},"orgIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"description":"With cherry-pick (staff)"},"excludeOrgIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"description":"With filter (staff): companies left out"}},"required":["mode"]},"schedule":{"type":"object","properties":{"frequency":{"type":"string","enum":["DAILY","WEEKLY","BIWEEKLY","MONTHLY"]},"sendDayOfWeek":{"type":["integer","null"],"minimum":0,"maximum":6},"sendDayOfMonth":{"type":["integer","null"],"minimum":1,"maximum":28},"sendDaysOfWeek":{"type":"array","items":{"type":"integer","minimum":0,"maximum":6},"maxItems":7},"sendHour":{"type":"integer","minimum":0,"maximum":23},"timezone":{"type":"string","minLength":1,"maxLength":64}},"required":["frequency"]},"status":{"type":"string","enum":["DRAFT","ACTIVE","PAUSED"]},"sellerOrgId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"Who it belongs to; null: the platform"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/platform/send":{"post":{"tags":["Marketing: the app's actions"],"summary":"Send any campaign to its audience now, platform audiences included","description":"The editor's Send now for Cypress staff: the campaign's audience is resolved as the scheduler resolves it and mailed at once. send_campaign_now does the same for an organization's own audiences and refuses the platform's. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CAMPAIGN.SENT`. Since 1.5.0.","operationId":"send_platform_campaign_now","x-cypress-action":"campaigns.platform.send_now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The campaign's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/message-templates/{id}":{"get":{"tags":["Marketing: the app's actions"],"summary":"A message template with the version being edited (the draft, else the published one)","description":"One template of yours or of Cypress's base library: its name, category, subject and document, whether you may edit it (a base template is cloned first) and its published version. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_message_template","x-cypress-action":"message_templates.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The message template's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Marketing: the app's actions"],"summary":"Write a template's name, category, subject and document (the draft; campaigns are unchanged)","description":"Saves the draft as the template editor does; a draft is never refused for being unfinished. Nothing a campaign sends changes until publish_message_template. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"save_message_template_draft","x-cypress-action":"message_templates.save_draft","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The message template's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"],"maxLength":500},"category":{"type":"string","enum":["NEW_INVENTORY","PRICE_DROP","FOLLOW_UP","OUTREACH","ANNOUNCEMENT","OTHER"]},"subject":{"type":"string","maxLength":300},"document":{"type":"object","additionalProperties":{},"description":"The message as the editor's document (blocks)"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Marketing: the app's actions"],"summary":"Take a template out of the library (it is kept, never deleted)","description":"Archives the template: it leaves the library and the campaign picker. It is kept, because a campaign may have copied from it. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"archive_message_template","x-cypress-action":"message_templates.archive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The message template's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/message-templates/drafts":{"post":{"tags":["Marketing: the app's actions"],"summary":"A new, empty message template of your organization","description":"Starts a template (a draft) in your library; save_message_template_draft writes it and publish_message_template makes it usable in campaigns. `platform` puts it in Cypress's base library (Cypress staff only). Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"create_message_template","x-cypress-action":"message_templates.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"category":{"type":"string","enum":["NEW_INVENTORY","PRICE_DROP","FOLLOW_UP","OUTREACH","ANNOUNCEMENT","OTHER"]},"description":{"type":["string","null"],"maxLength":500},"platform":{"type":"boolean","description":"Cypress staff only: the base library"}},"required":["name"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/message-templates/{id}/clone":{"post":{"tags":["Marketing: the app's actions"],"summary":"A full copy of a template (yours or Cypress's) into your library","description":"Makes it yours: a full copy, never a reference, so a later change to the original does not touch your version. Answers the copy's id. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"clone_message_template","x-cypress-action":"message_templates.clone","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The message template's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/message-templates/{id}/publish":{"post":{"tags":["Marketing: the app's actions"],"summary":"Make a template's draft its live version, usable in campaigns","description":"The gate: the draft becomes a new immutable version that campaigns can insert. Refused (422) with every blocker (no subject line, no body, a body that is not valid). Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"publish_message_template","x-cypress-action":"message_templates.publish","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The message template's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/message-templates/{id}/versions":{"get":{"tags":["Marketing: the app's actions"],"summary":"A template's published versions, newest first","description":"Every published version of the template, newest first, each immutable: its subject and body as published, who published it and when, and which campaigns copied it. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_message_template_versions","x-cypress-action":"message_templates.versions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The message template's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/message-templates/{id}/versions/{versionId}/restore":{"post":{"tags":["Marketing: the app's actions"],"summary":"Copy a published version into a template's draft","description":"Restoring is an editing step: the version is copied into the draft, and nothing changes for campaigns until publish_message_template. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"restore_message_template_version","x-cypress-action":"message_templates.restore","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The message template's Cypress id"}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The version (list_message_template_versions)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketing/analytics/overview":{"get":{"tags":["Marketing: the app's actions"],"summary":"The engagement report of one campaign, promotion, vehicle or deal: mail, visits, saves, offers, temperature","description":"The Marketing analytics report for one thing of yours over a period: deliveries, opens and clicks (where something was mailed), views, saves and offers, the trend and its temperature. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_engagement_overview","x-cypress-action":"engagement.overview","parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["campaign","promotion","vehicle","deal"],"description":"What the report is about"},"description":"What the report is about"},{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Its id (a campaign, promotion, vehicle or deal of yours)"},"description":"Its id (a campaign, promotion, vehicle or deal of yours)"},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketing/analytics/summary":{"get":{"tags":["Marketing: the app's actions"],"summary":"Every campaign, promotion or vehicle of yours with its numbers and temperature","description":"The analytics summary table: all your campaigns, promotions or vehicles (`kind`) over a period, each with its engagement totals and temperature, so the ones that need you stand out. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_engagement_summary","x-cypress-action":"engagement.summary","parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["promotion","campaign","vehicle"],"description":"promotion when left out"},"description":"promotion when left out"},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketing/analytics/breakdowns":{"get":{"tags":["Marketing: the app's actions"],"summary":"Engagement by source, device and kind of visitor, for one campaign, promotion, vehicle or deal","description":"The report's three tallies: where the traffic came from, on what device, and by whom (companies, private buyers, not signed in). Click sources appear only where something was mailed. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_engagement_breakdowns","x-cypress-action":"engagement.breakdowns","parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["campaign","promotion","vehicle","deal"],"description":"What the report is about"},"description":"What the report is about"},{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Its id (a campaign, promotion, vehicle or deal of yours)"},"description":"Its id (a campaign, promotion, vehicle or deal of yours)"},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketing/analytics/by-vehicle":{"get":{"tags":["Marketing: the app's actions"],"summary":"Each car's views, saves and offers within one campaign, promotion, vehicle or deal","description":"Per-car performance within the report's scope, with each car's market status: which cars the campaign or promotion actually moved. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_engagement_by_vehicle","x-cypress-action":"engagement.by_vehicle","parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["campaign","promotion","vehicle","deal"],"description":"What the report is about"},"description":"What the report is about"},{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Its id (a campaign, promotion, vehicle or deal of yours)"},"description":"Its id (a campaign, promotion, vehicle or deal of yours)"},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketing/analytics/sankey":{"get":{"tags":["Marketing: the app's actions"],"summary":"Where traffic came from, which cars it landed on, and what it did","description":"The report's flow (the Sankey chart) as nodes and links: sources, cars and outcomes (viewed, saved, offered). Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_engagement_flow","x-cypress-action":"engagement.flow","parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["campaign","promotion","vehicle","deal"],"description":"What the report is about"},"description":"What the report is about"},{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Its id (a campaign, promotion, vehicle or deal of yours)"},"description":"Its id (a campaign, promotion, vehicle or deal of yours)"},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketing/analytics/visitors":{"get":{"tags":["Marketing: the app's actions"],"summary":"The people and companies who engaged with one campaign, promotion, vehicle or deal","description":"The report's Visitors: each actor who engaged, with their activity and, where one exists, the contact of your book they are. get_engaged_visitor opens one. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"list_engaged_visitors","x-cypress-action":"engagement.visitors","parameters":[{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["campaign","promotion","vehicle","deal"],"description":"What the report is about"},"description":"What the report is about"},{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Its id (a campaign, promotion, vehicle or deal of yours)"},"description":"Its id (a campaign, promotion, vehicle or deal of yours)"},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketing/analytics/customers":{"get":{"tags":["Marketing: the app's actions"],"summary":"Everyone engaging with what is yours in a period, matched to your book","description":"The Customers grid: every actor engaging with your campaigns, promotions and cars over the period, whatever brought them, each matched to a contact of your book where one exists. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"list_warm_customers","x-cypress-action":"engagement.customers","parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["7d","30d","90d","all"],"description":"The period: 7d, 30d (the default), 90d or all"},"description":"The period: 7d, 30d (the default), 90d or all"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketing/analytics/actors/{actorKey}":{"get":{"tags":["Marketing: the app's actions"],"summary":"One person's or company's full engagement history with what is yours","description":"One actor (a key from list_engaged_visitors or list_warm_customers): everything they did, all time. Name the report it came from: `scope` and `id`, or `scope: customers`. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"get_engaged_visitor","x-cypress-action":"engagement.visitor","parameters":[{"name":"actorKey","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"The actor's key"}},{"name":"scope","in":"query","required":true,"schema":{"type":"string","enum":["campaign","promotion","vehicle","deal","customers"],"description":"The report it came from"},"description":"The report it came from"},{"name":"id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The report's id (not with customers)"},"description":"The report's id (not with customers)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/promotions":{"get":{"tags":["Promotions: the app's actions"],"summary":"Your promotions (curated sets of cars with their own page), with their state and counts","description":"The Promotions page: each promotion with its state (Draft, Scheduled, Live, Expired, Paused, Archived), how many cars it holds and how many are available, and its temperature. A promotion is the content a campaign can carry (create_campaign with PROMOTION). Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_promotions","x-cypress-action":"promotions.list","parameters":[{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"visibility","in":"query","required":false,"schema":{"type":"string","enum":["Draft","Scheduled","Live","Expired","Paused","Archived"],"description":"Its state"},"description":"Its state"},{"name":"listMode","in":"query","required":false,"schema":{"type":"string","enum":["CHERRY_PICK","DYNAMIC_QUERY"]}},{"name":"createdFrom","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"createdTo","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Promotions: the app's actions"],"summary":"A new promotion (a draft): a hand-picked list of cars, or a list kept by filters","description":"Starts a draft promotion of your organization, CHERRY_PICK (you name the cars) or DYNAMIC_QUERY (saved filters keep it current). Fill it with update_promotion, then publish_promotion. Cypress staff may name the owner (`organizationId`; null: the platform's). Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `PROMOTION.UPDATED`. Since 1.5.0.","operationId":"create_promotion","x-cypress-action":"promotions.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"listMode":{"type":"string","enum":["CHERRY_PICK","DYNAMIC_QUERY"]},"organizationId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"Cypress staff only: who it belongs to"}},"required":["name","listMode"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/promotions/{id}":{"get":{"tags":["Promotions: the app's actions"],"summary":"One promotion: its copy, dates, visibility, cars or filters, featured cars and hero","description":"The promotion editor's record: name, tagline, dates, PUBLIC or UNLISTED, its cars (cherry-picked) or saved filters (dynamic), the featured cars and the hero in its three framings (links valid for an hour). Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_promotion","x-cypress-action":"promotions.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The promotion's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Promotions: the app's actions"],"summary":"A promotion's copy, dates, visibility, cars or filters, and featured cars","description":"The promotion editor's save. `vehicleIds` replaces a cherry-picked list (your own cars only; link-only cars are refused) and tells each car's seller it was added or removed; `savedFilters` sets a dynamic one. UNLISTED makes it a page only the people it is sent to reach. A live promotion's page changes at once. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `PROMOTION.UPDATED`. Since 1.5.0.","operationId":"update_promotion","x-cypress-action":"promotions.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The promotion's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"tagline":{"type":"string","maxLength":200},"audienceNote":{"type":"string","maxLength":500},"startDate":{"type":["string","null"],"format":"date-time"},"endDate":{"type":["string","null"],"format":"date-time"},"listMode":{"type":"string","enum":["CHERRY_PICK","DYNAMIC_QUERY"]},"visibility":{"type":"string","enum":["PUBLIC","UNLISTED"],"description":"PUBLIC: browsable; UNLISTED: reached only through its link"},"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":500,"description":"CHERRY_PICK: the whole list"},"savedFilters":{"type":"object","additionalProperties":{},"description":"DYNAMIC_QUERY: the filters"},"featuredVehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":10,"description":"Shown first (at most 10)"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Promotions: the app's actions"],"summary":"Delete a promotion that never sent mail","description":"The Delete on the Promotions page, for a promotion that never sent real mail: the promotion, its list and its campaigns go. One that has sent mail answers 409 CONFLICT and nothing is deleted: archive it (archive_promotion) and its sends, the people they reached and its results stay. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `PROMOTION.UPDATED`. Since 1.5.0.","operationId":"delete_promotion","x-cypress-action":"promotions.delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The promotion's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/promotions/{id}/publish":{"post":{"tags":["Promotions: the app's actions"],"summary":"Put a promotion live (its page, on your storefront or the marketplace)","description":"The editor's Publish: the promotion goes live on its dates (PUBLIC ones are browsable). Refused (422) when it would hold no car. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `PROMOTION.UPDATED`. Since 1.5.0.","operationId":"publish_promotion","x-cypress-action":"promotions.publish","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The promotion's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/promotions/{id}/pause":{"post":{"tags":["Promotions: the app's actions"],"summary":"Take a live promotion's page down for a while","description":"The editor's Pause: the page stops showing until publish_promotion puts it back. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `PROMOTION.UPDATED`. Since 1.5.0.","operationId":"pause_promotion","x-cypress-action":"promotions.pause","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The promotion's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/promotions/{id}/archive":{"post":{"tags":["Promotions: the app's actions"],"summary":"End a promotion: its page comes down and it leaves the working list","description":"The editor's Archive. It is kept with its analytics; publish_promotion can bring it back. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `PROMOTION.UPDATED`. Since 1.5.0.","operationId":"archive_promotion","x-cypress-action":"promotions.archive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The promotion's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/promotions/{id}/insight":{"get":{"tags":["Promotions: the app's actions"],"summary":"Sakura's read of how a promotion is doing","description":"Sakura's read of one promotion, as the analytics page's card shows it: how it is doing against its goal, what is working, and what to change next. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_promotion_insight","x-cypress-action":"promotions.insight","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The promotion's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/promotions/{id}/hero":{"post":{"tags":["Promotions: the app's actions"],"summary":"Upload the picture at the top of a promotion's page and email","description":"The hero editor's upload: `source` (the default) is a new picture, used for every framing until one is cropped; `marketplace` or `email` replaces that framing only. At most 10 MB. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"upload_promotion_hero","x-cypress-action":"promotions.hero.upload","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The promotion's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentBase64":{"type":"string","minLength":4,"maxLength":14000000,"description":"The picture, base64 (at most 10 MB)"},"contentType":{"type":"string","pattern":"^image\\/(jpeg|png|webp)$","description":"image/jpeg, image/png or image/webp"},"fileName":{"type":"string","maxLength":200},"target":{"type":"string","enum":["source","marketplace","email"],"description":"Which framing (source when left out)"}},"required":["contentBase64","contentType"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/promotions/{id}/hero/generate":{"post":{"tags":["Promotions: the app's actions"],"summary":"An AI-made hero picture for a promotion, from its name and cars","description":"The hero editor's Generate: an image model draws a hero from the promotion and it replaces the current one (the source framing). Answers its link and the model that drew it; 503 when image generation is not configured. Needs `marketing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"generate_promotion_hero","x-cypress-action":"promotions.hero.generate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The promotion's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/vehicles/{id}/offers":{"post":{"tags":["Offers: the app's actions"],"summary":"Offer an amount on a vehicle for sale, as the Make Offer button does","description":"Makes an offer, as your organization, on a vehicle for sale (listed or under offer). The seller's offer rules judge it at once: `autoStatus` says whether it was accepted on the spot (the sale is binding and a closing starts), declined, or left for the seller to review. When the seller has published terms, send the `sellerTermsVersionId` that get_marketplace_vehicle shows: sending it accepts them. A vehicle shown only through a share link or a storefront needs that link's token or that storefront's slug. To buy at the asking price, use buy_vehicle_now; to take back an open offer, withdraw_offer. Needs `marketplace:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `OFFERS.CREATED`. Since 1.5.0.","operationId":"make_offer","x-cypress-action":"offers.make","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"USD"},"conditions":{"type":"string","maxLength":2000,"description":"Conditions you attach to the offer"},"message":{"type":"string","maxLength":2000,"description":"A note to the seller"},"sellerTermsVersionId":{"type":"string","minLength":1,"maxLength":64,"description":"The seller's terms you accept (get_marketplace_vehicle `sellerTerms.versionId`); required when the seller has terms"},"p2pToken":{"type":"string","maxLength":200,"description":"The share link's token, when the vehicle reached you through one"},"storefrontSlug":{"type":"string","maxLength":120,"description":"The seller's storefront slug, when you offer from their storefront"}},"required":["amount"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/vehicles/{id}/buy":{"post":{"tags":["Offers: the app's actions"],"summary":"Buy now: an offer at the asking price, accepted at once, and the closing starts","description":"The Buy Now button: an offer at the vehicle's asking price that is accepted immediately. The sale is binding, the other open offers on the vehicle are closed and the closing starts (get_closing follows it). The seller's terms, a share link's token and a storefront slug work as in make_offer. Needs `marketplace:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `OFFERS.CREATED`. Since 1.5.0.","operationId":"buy_vehicle_now","x-cypress-action":"offers.buy_now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","maxLength":2000,"description":"A note to the seller"},"sellerTermsVersionId":{"type":"string","minLength":1,"maxLength":64,"description":"The seller's terms you accept; required when the seller has terms"},"p2pToken":{"type":"string","maxLength":200},"storefrontSlug":{"type":"string","maxLength":120}}}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/offers/{id}/accept-counter":{"post":{"tags":["Offers: the app's actions"],"summary":"Accept the seller's counter on an offer you made: the sale is binding","description":"For an offer of yours the seller COUNTERED: accepts the counter amount before it expires. The sale is binding, the vehicle's other offers close and the closing starts. An offer made before the seller published terms needs the `sellerTermsVersionId` now (accepting it accepts the terms). Needs `marketplace:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `OFFERS.ACCEPTED`. Since 1.5.0.","operationId":"accept_counter_offer","x-cypress-action":"offers.counter.accept","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The offer's Cypress id (list_offers)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sellerTermsVersionId":{"type":"string","minLength":1,"maxLength":64,"description":"The seller's terms you accept, when the offer carries none yet"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/offers/{id}/counter-back":{"post":{"tags":["Offers: the app's actions"],"summary":"Counter the seller's counter: your offer becomes the new amount, back with the seller","description":"For an offer of yours the seller COUNTERED: replaces your amount with a new one and sends it back to the seller to decide (the offer is NEW again; the counter is cleared). To take the seller's number instead, use accept_counter_offer. Needs `marketplace:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"counter_back_offer","x-cypress-action":"offers.counter.answer","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The offer's Cypress id (list_offers)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","exclusiveMinimum":0,"description":"USD"},"message":{"type":"string","maxLength":1000,"description":"A note to the seller"}},"required":["amount"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/offers/made":{"get":{"tags":["Offers: the app's actions"],"summary":"Your organization's offers as a buyer, with the vehicle, the seller's counter and its message","description":"The Buyer Hub's list: each offer you made with its vehicle (year, make, model, mileage, location, asking price), its status, the seller's counter and the seller's message, the terms version it was made under, Sakura's read when there is one, and the buy plan target it counts toward. Since 1.9.0 each carries `conditionAtOffer`: the car's condition as you saw it when you made the offer (grade and score, the latest inspection with its date, provider and grade, the ARVIS score, the damage count), null on older offers; and `counterHoursLeft`, the whole hours left to accept a live seller counter (never negative), worked out: use it as given. The seller is never named. list_offers (side BUYER) is the short form. Needs `marketplace:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_offers_made","x-cypress-action":"offers.made.list","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["all","active","countered","accepted","declined","expired"],"description":"active = new or in review; expired includes withdrawn (all when left out)"},"description":"active = new or in review; expired includes withdrawn (all when left out)"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["date","amount"]}},{"name":"dir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"1-based (1 when left out)"},"description":"1-based (1 when left out)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"vehicleId":{"type":"string"},"vehicleLabel":{"type":"string"},"amount":{"type":"number","description":"USD"},"targetPrice":{"type":["number","null"],"description":"The asking price, USD"},"status":{"type":"string","description":"NEW, REVIEWED, COUNTERED, ACCEPTED, REJECTED, EXPIRED or WITHDRAWN; a counter past its deadline reads EXPIRED"},"counterAmount":{"type":["number","null"],"description":"The seller's counter, USD"},"counterExpiresAt":{"type":["string","null"],"description":"When the seller's counter expires (ISO)"},"counterHoursLeft":{"type":["integer","null"],"description":"Since 1.9.0. Whole hours left to accept the seller's counter (COUNTERED), never negative; null without a live counter"},"createdAt":{"type":"string"}},"required":["id","vehicleId","vehicleLabel","amount","targetPrice","status","counterAmount","counterExpiresAt","counterHoursLeft","createdAt"]}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"pages":{"type":"integer"}},"required":["offers","total","page","limit","pages"]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/offers/{id}/activity":{"get":{"tags":["Offers: the app's actions"],"summary":"The history of an offer you made, as the buyer sees it","description":"For an offer your organization made: its own events (made, countered, accepted, declined, withdrawn), the listing's public events (listed, paused, resumed) and, once the sale is yours, the closing's. Other buyers' offers and the seller's internal work are never shown. Needs `offers:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_offer_activity","x-cypress-action":"offers.made.activity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The offer's Cypress id (list_offers)"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/offers/{id}/sakura-read":{"post":{"tags":["Offers: the app's actions"],"summary":"Sakura's advice on an offer you made: hold, raise, accept the counter or walk away","description":"Sakura reads one of your offers against the vehicle and the market and answers its advice (an action, its confidence, its reasoning and a suggested amount), as the Buyer Hub panel does. Each call is a new read. Needs `insights:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"read_offer_with_sakura","x-cypress-action":"offers.made.sakura_read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The offer's Cypress id (list_offers)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/offers/received":{"get":{"tags":["Offers: the app's actions"],"summary":"Offers on your vehicles with the buyer, your floor and rules, the channel and the commission","description":"The Seller Hub's offer list: each offer on your vehicles with the buyer (name, email, organization, whether a private person), your floor, target and offer rules, the channel it came through, the commission it carries and the terms the buyer accepted. Since 1.9.0 each carries `buyerRecord` (`purchasesWithYou`, `lastPurchaseAt`, `avgDaysToPay`): the buyer's record with you only, never with another seller, null when you never closed a deal together; and `conditionAtOffer`, the car's condition as the buyer saw it when the offer was made (null on older offers). Since 1.9.0 the facts are worked out, to use as given rather than worked out again: on each offer `waitingHours`, `ofListing` (0.962 is 96.2% of the listing price), `underFloorBy` or `aboveFloorBy` and, while it waits for your answer, `answerOrder` (1 = answer first: offers not under the floor first, then the longest waiting, then the highest share of the listing) with `answerWhy`; and `summary` (`count`, `answerFirst`, `oldest`, `closestToListing`, `underFloor`), each by offer id, over every offer waiting for your answer that the search and vehicle filters match, whatever the tab, sort and page. A counter you sent carries `counterHoursLeft`, the whole hours the buyer has left to take it; one past its deadline reads EXPIRED and is in the resolved tab, not countered. Filter by tab or vehicle, search by vehicle or buyer. list_offers is the short form without the buyer. Needs `offers:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"list_offers_received","x-cypress-action":"offers.received.list","parameters":[{"name":"tab","in":"query","required":false,"schema":{"type":"string","enum":["all","needs_action","countered","auto_accepted","resolved"]}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["date","amount","status"]}},{"name":"dir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"search","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Vehicle make, model or VIN, or the buyer's name or email"},"description":"Vehicle make, model or VIN, or the buyer's name or email"},{"name":"vehicleId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"1-based (1 when left out)"},"description":"1-based (1 when left out)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"offers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"vehicleId":{"type":"string"},"vehicleLabel":{"type":"string"},"vehicleVin":{"type":"string"},"amount":{"type":"number","description":"USD"},"targetPrice":{"type":["number","null"],"description":"The listing price buyers see, USD"},"floorPrice":{"type":["number","null"],"description":"Your floor, USD"},"status":{"type":"string","description":"NEW, REVIEWED, COUNTERED, ACCEPTED, REJECTED, EXPIRED or WITHDRAWN; a counter past its deadline reads EXPIRED"},"counterAmount":{"type":["number","null"],"description":"Your counter, USD"},"counterExpiresAt":{"type":["string","null"],"description":"When your counter expires (ISO)"},"counterHoursLeft":{"type":["integer","null"],"description":"Since 1.9.0. Whole hours the buyer has left on your live counter (0 = under an hour); null without a live counter"},"createdAt":{"type":"string","description":"When the offer was made (ISO)"},"waitingHours":{"type":["integer","null"],"description":"Since 1.9.0. Whole hours since the offer was made, while it waits for your answer (NEW or REVIEWED); null otherwise"},"ofListing":{"type":["number","null"],"description":"Since 1.9.0. The offer over the listing price, to three decimals (0.962 is 96.2%); null without a listing price"},"underFloorBy":{"type":["number","null"],"description":"Since 1.9.0. How far below your floor, USD; null at or above it, or with no floor"},"aboveFloorBy":{"type":["number","null"],"description":"Since 1.9.0. How far above your floor, USD (0 at the floor); null below it, or with no floor"},"answerOrder":{"type":["integer","null"],"description":"Since 1.9.0. Its place among the offers waiting for your answer (1 = answer first); null when it is not waiting for you"},"answerWhy":{"type":["string","null"],"description":"Since 1.9.0. Why that place, in plain words: \"above the floor by $600, waiting 20h, 96.2% of listing\""}},"required":["id","vehicleId","vehicleLabel","vehicleVin","amount","targetPrice","floorPrice","status","counterAmount","counterExpiresAt","createdAt","waitingHours","ofListing","underFloorBy","aboveFloorBy","answerOrder","answerWhy"]}},"summary":{"type":"object","properties":{"count":{"type":"integer","description":"Offers waiting for your answer"},"answerFirst":{"type":["object","null"],"properties":{"offerId":{"type":"string"},"why":{"type":"string"}},"required":["offerId","why"]},"oldest":{"type":["object","null"],"properties":{"offerId":{"type":"string"},"waitingHours":{"type":"integer"}},"required":["offerId","waitingHours"]},"closestToListing":{"type":["object","null"],"properties":{"offerId":{"type":"string"},"ofListing":{"type":"number"}},"required":["offerId","ofListing"],"description":"The highest share of its listing price"},"underFloor":{"type":"array","items":{"type":"object","properties":{"offerId":{"type":"string"},"by":{"type":"number","description":"USD below the floor"}},"required":["offerId","by"]},"description":"In the order to answer them"}},"required":["count","answerFirst","oldest","closestToListing","underFloor"],"description":"Since 1.9.0. The offers waiting for your answer (NEW or REVIEWED) that the search and vehicle filters match, on every page and whatever the tab or sort, each named by its offer id"},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"pages":{"type":"integer"}},"required":["offers","summary","total","page","limit","pages"]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/vehicles":{"get":{"tags":["Marketplace: the app's actions"],"summary":"Vehicles for sale on Cypress, filtered and sorted","description":"The marketplace's search: vehicles for sale (and, unless `hideSold`, those sold in the last 30 days), with their asking price, the buyer-safe offer terms, the latest retail value, how many people viewed them and (since 1.9.0) `engagement`: HOT, WARM or COLD, how buyers are taking to each. Comma-separated lists filter by any of their values. get_marketplace_vehicle opens one. Needs `marketplace:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"search_marketplace","x-cypress-action":"marketplace.vehicles.search","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Free text"},"description":"Free text"},{"name":"make","in":"query","required":false,"schema":{"type":"string","maxLength":500,"description":"Comma-separated makes"},"description":"Comma-separated makes"},{"name":"condition","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Comma-separated conditions"},"description":"Comma-separated conditions"},{"name":"fuelType","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Comma-separated fuel types"},"description":"Comma-separated fuel types"},{"name":"bodyClass","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Comma-separated body classes"},"description":"Comma-separated body classes"},{"name":"state","in":"query","required":false,"schema":{"type":"string","maxLength":400,"description":"Comma-separated US states"},"description":"Comma-separated US states"},{"name":"region","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Comma-separated market regions"},"description":"Comma-separated market regions"},{"name":"ids","in":"query","required":false,"schema":{"type":"string","maxLength":4000,"description":"Comma-separated vehicle ids: only these"},"description":"Comma-separated vehicle ids: only these"},{"name":"minPrice","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"maxPrice","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"minYear","in":"query","required":false,"schema":{"type":"integer"}},{"name":"maxYear","in":"query","required":false,"schema":{"type":"integer"}},{"name":"minMileage","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"maxMileage","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["newest","price_asc","price_desc","year_desc","year_asc","mileage_asc","mileage_desc"]}},{"name":"hideSold","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":48,"description":"At most 48 (24 when left out)"},"description":"At most 48 (24 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/vehicles/{id}":{"get":{"tags":["Marketplace: the app's actions"],"summary":"One marketplace vehicle: specs, pictures, the seller's standing, the terms and the offer rules a buyer sees","description":"A vehicle as its marketplace page shows it: specs, condition, pictures with links valid for an hour, the latest valuation, Sakura's market note, `engagement` (HOT, WARM or COLD while it is on the market, since 1.9.0), the seller's standing (never its name), the buyer-safe offer terms and the seller's terms with the `versionId` make_offer needs. Needs `marketplace:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_marketplace_vehicle","x-cypress-action":"marketplace.vehicles.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/share-links/{token}":{"get":{"tags":["Marketplace: the app's actions"],"summary":"The vehicle behind a share link, as its marketplace page shows it, with the seller's terms and the token to offer with","description":"A seller shared a car with you through a share link (Direct Links): its token, from the link's URL (`/p2p/{token}`) or from MARKETPLACE.SHARE.RECEIVED, opens the car here, even one kept off the open marketplace (LINK_ONLY). The answer is get_marketplace_vehicle's, with the seller's terms (`sellerTerms.versionId`) and `shareLink`: its token, label, expiry, who shared it (as the link's page shows anyone who holds it) and whether it was addressed to your organization. Offer through it with make_offer and `p2pToken` set to the token. A link the seller revoked or let expire, or a car no longer for sale, answers 409; an unknown token 404. Needs `marketplace:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.9.0.","operationId":"open_share_link","x-cypress-action":"marketplace.share_links.get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","minLength":8,"maxLength":200,"description":"The share link's token"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/picks":{"get":{"tags":["Marketplace: the app's actions"],"summary":"Live vehicles that fit what you bid on, bought and save searches for, each with why","description":"The marketplace's \"For you\": vehicles for sale like the ones you made offers on and, since 1.9.0, the ones your organization bought (a completed purchase counts twice an offer: make, model, body, price band), else those matching your saved searches, each with the plain reason it was picked (`reason`). A car your organization said \"not for me\" to (dismiss_marketplace_pick) never comes back, and cars like it rank lower. The picks are the person's own. Needs `marketplace:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). Since 1.5.0.","operationId":"list_marketplace_picks","x-cypress-action":"marketplace.picks","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/picks/{vehicleId}/dismiss":{"post":{"tags":["Marketplace: the app's actions"],"summary":"\"Not for me\" on a pick, with why: the car never comes back, and cars like it rank lower","description":"Your organization's \"not for me\" on a car Sakura picked, with the reason: PRICE (too dear: cars as dear rank lower), MILEAGE (too many miles), MODEL (not this model), LOCATION (too far: the same state ranks lower) or OTHER, and a note in your words. The car never comes back in your organization's picks. Saying it again replaces the reason. restore_marketplace_pick takes it back. Only your organization ever reads it; the seller is never told. Needs `marketplace:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"dismiss_marketplace_pick","x-cypress-action":"marketplace.picks.dismiss","parameters":[{"name":"vehicleId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["PRICE","MILEAGE","MODEL","LOCATION","OTHER"],"description":"Why: PRICE, MILEAGE, MODEL, LOCATION or OTHER"},"note":{"type":"string","maxLength":500,"description":"In your words, for your team"}},"required":["reason"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Marketplace: the app's actions"],"summary":"The car may be picked for you again","description":"Takes back your organization's \"not for me\" on a car (dismiss_marketplace_pick): it may come back in your picks, and cars like it are no longer ranked lower for it. A car that was never dismissed is ignored, so a retry is harmless. Needs `marketplace:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"restore_marketplace_pick","x-cypress-action":"marketplace.picks.restore","parameters":[{"name":"vehicleId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/purchase-profile":{"get":{"tags":["Marketplace: the app's actions"],"summary":"Your usual, from your own completed purchases: price, age and mileage bands, makes, models, body classes, states","description":"What your organization typically buys on Cypress, from its own completed purchases (an accepted offer of yours on a car now sold) in the last year (`days`): the price you paid, the age and mileage when bought (each the middle half, the whole range under four purchases, with the median), the model years that age reads as today, the makes, models, body classes and states bought in, how often you buy and when you last did, and a plain line (\"Your usual, from 12 purchases…\"). Use it to prefill a buy plan target. Only your own trades: no seller is named. Needs `marketplace:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.9.0.","operationId":"get_purchase_profile","x-cypress-action":"marketplace.purchase_profile","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":30,"maximum":1095,"description":"Purchases completed within this many days (365 when left out)"},"description":"Purchases completed within this many days (365 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/saved-vehicles":{"get":{"tags":["Marketplace: the app's actions"],"summary":"The vehicles you saved (your watchlist), with the price when you saved each","description":"Your favorites: each vehicle still on the marketplace that you saved, with when and the asking price at the time (compare with today's to see a drop). The list is the person's own. Needs `marketplace:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). Since 1.5.0.","operationId":"list_saved_vehicles","x-cypress-action":"marketplace.saved.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Marketplace: the app's actions"],"summary":"Add a marketplace vehicle to your saved vehicles","description":"Saves a vehicle for sale to your watchlist (saving one already saved changes nothing). The seller sees that someone saved it, never who. Needs `marketplace:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"save_vehicle","x-cypress-action":"marketplace.saved.add","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicleId":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},"required":["vehicleId"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/saved-vehicles/{vehicleId}":{"delete":{"tags":["Marketplace: the app's actions"],"summary":"Take a vehicle off your saved vehicles","description":"Takes a vehicle off your organization's watchlist (saved vehicles); a vehicle that is not on it is ignored, so a retry is harmless. Needs `marketplace:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"unsave_vehicle","x-cypress-action":"marketplace.saved.remove","parameters":[{"name":"vehicleId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/alerts":{"get":{"tags":["Marketplace: the app's actions"],"summary":"Your saved searches (alerts), with their criteria, how they notify you and how many cars matched","description":"Your active saved searches: each one's criteria, whether it notifies at once or in a digest, whether matches are saved for you, and how many vehicles matched. list_marketplace_alert_matches names the matches. Needs `marketplace:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). Since 1.5.0.","operationId":"list_marketplace_alerts","x-cypress-action":"marketplace.alerts.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Marketplace: the app's actions"],"summary":"A saved search that tells you when a matching vehicle is listed","description":"Saves a search (an alert): from now on, a newly listed vehicle that matches tells you (at once, or in a daily or weekly digest). The vehicles already for sale that match are recorded at once and, with `autoSave`, added to your saved vehicles. Answers the alert with how many matched. Needs `marketplace:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"create_marketplace_alert","x-cypress-action":"marketplace.alerts.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"makes":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":50},"models":{"type":"array","items":{"type":"string","maxLength":80},"maxItems":100},"bodyClass":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":30},"fuelTypes":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20},"conditions":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":10},"states":{"type":"array","items":{"type":"string","maxLength":2},"maxItems":60,"description":"US state codes"},"minYear":{"type":"integer"},"maxYear":{"type":"integer"},"maxMileage":{"type":"integer","minimum":0},"minPrice":{"type":"number","exclusiveMinimum":0,"description":"USD"},"maxPrice":{"type":"number","exclusiveMinimum":0,"description":"USD"},"pushEnabled":{"type":"boolean","description":"Tell you at once (true when left out)"},"digestEnabled":{"type":"boolean"},"digestCadence":{"type":"string","enum":["DAILY","WEEKLY"]},"digestIncludeExisting":{"type":"boolean"},"autoSave":{"type":"boolean","description":"Add every match to your saved vehicles"}}}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/alerts/{id}":{"patch":{"tags":["Marketplace: the app's actions"],"summary":"Change a saved search's criteria or how it tells you","description":"Changes one of your saved searches; only the fields sent change (null clears a number). Needs `marketplace:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"update_marketplace_alert","x-cypress-action":"marketplace.alerts.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The saved search"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"makes":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":50},"bodyClass":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":30},"fuelTypes":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":20},"conditions":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":10},"states":{"type":"array","items":{"type":"string","maxLength":2},"maxItems":60},"minYear":{"type":["integer","null"]},"maxYear":{"type":["integer","null"]},"maxMileage":{"type":["integer","null"],"minimum":0},"minPrice":{"type":["number","null"],"exclusiveMinimum":0,"description":"USD"},"maxPrice":{"type":["number","null"],"exclusiveMinimum":0,"description":"USD"},"pushEnabled":{"type":"boolean"},"digestEnabled":{"type":"boolean"},"digestCadence":{"type":"string","enum":["DAILY","WEEKLY"]},"digestIncludeExisting":{"type":"boolean"},"autoSave":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Marketplace: the app's actions"],"summary":"Switch a saved search off","description":"Switches one of your saved searches off: it stops telling you about new matches. Needs `marketplace:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"delete_marketplace_alert","x-cypress-action":"marketplace.alerts.delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The saved search"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/marketplace/alerts/{id}/matches":{"get":{"tags":["Marketplace: the app's actions"],"summary":"The vehicles still for sale that a saved search matched (up to 50)","description":"The ids of the vehicles a saved search matched that are still for sale, newest first; search_marketplace with `ids` lists them. Needs `marketplace:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). Since 1.5.0.","operationId":"list_marketplace_alert_matches","x-cypress-action":"marketplace.alerts.matches","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The saved search"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/activity":{"get":{"tags":["Closings: the app's actions"],"summary":"What happened in a sale and its closing, who did it and when","description":"The closing's timeline as Post-Sale shows it: the sale (the offer and its acceptance), each step, document and incident, with who did it (a person, Cypress, an integration) and when, newest first. A buyer sees its own offer only. Needs `closing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_closing_activity","x-cypress-action":"closings.activity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"At most this many (60 when left out)"},"description":"At most this many (60 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/incidents":{"get":{"tags":["Closings: the app's actions"],"summary":"The problems reported on a closing, with their thread and status","description":"The incidents reported on a closing in progress (a wrong document, money not arrived, the car not at the yard…), each with its step, category, status and messages; a message's pictures carry a `url` valid for an hour. Needs `closing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_closing_incidents","x-cypress-action":"closings.incidents.list","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Closings: the app's actions"],"summary":"Tell Cypress something is wrong with a closing in progress","description":"Reports an incident on a closing in progress, on one of its steps or the whole closing: Cypress is told and works it with you (message_closing_incident adds to the thread). Since 1.9.0 it takes up to 5 pictures (`photos`), filed with the first message; list_closing_incidents answers each with a link valid for an hour. Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.UPDATED`. Since 1.5.0.","operationId":"report_closing_incident","x-cypress-action":"closings.incidents.report","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stepKey":{"type":"string","enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"},"category":{"type":"string","enum":["WRONG_VEHICLE_INFO","INCORRECT_SALE_PRICE","MISSING_SIGNATURE_FIELDS","DOCUMENT_FORMAT_ISSUE","SIGNING_LINK_NOT_WORKING","WRONG_BUYER_DETAILS","BUYER_DECLINED_TO_SIGN","AMOUNT_DISCREPANCY","ACH_TRANSFER_FAILED","WRONG_ACCOUNT_DETAILS","COMMISSION_AMOUNT_DISPUTE","INVOICE_NOT_RECEIVED","PAYMENT_NOT_APPLIED","FUNDS_NOT_RECEIVED","PARTIAL_PAYMENT","PAYMENT_REVERSED","TITLE_NOT_RECEIVED","WRONG_TRACKING_NUMBER","DAMAGED_IN_TRANSIT","TITLE_WRONG_VEHICLE","TITLE_HAS_LIENS","ACCESS_DENIED","PASS_NOT_ACCEPTED","WRONG_LOCATION","CAR_NOT_AT_LOCATION","WRONG_VIN","VEHICLE_DAMAGE","KEYS_NOT_PROVIDED","CONDITION_DIFFERS_FROM_LISTING","BUYER_NO_SHOW","COMMUNICATION_ISSUE","DELAY_SLA_BREACH","OTHER"]},"description":{"type":"string","minLength":1,"maxLength":2000},"photos":{"type":"array","items":{"type":"object","properties":{"contentBase64":{"type":"string","minLength":4,"maxLength":14000000,"description":"The picture, base64 (at most 10 MB)"},"contentType":{"type":"string","pattern":"^image\\/(jpeg|png|webp|heic|heif)$","description":"image/jpeg, image/png, image/webp or image/heic"},"fileName":{"type":"string","maxLength":200}},"required":["contentBase64","contentType"]},"maxItems":5,"description":"Up to 5 pictures (the VIN plate, the damage, the gate); the incident reads answer each with a link valid for an hour"}},"required":["category","description"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/incidents/{incidentId}/messages":{"post":{"tags":["Closings: the app's actions"],"summary":"Write in the thread of an incident you reported","description":"Adds a message to the thread of an incident your side reported (Cypress is told), with up to 5 pictures (`photos`, since 1.9.0). Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.UPDATED`. Since 1.5.0.","operationId":"message_closing_incident","x-cypress-action":"closings.incidents.message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"incidentId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The incident (list_closing_incidents)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":4000},"awaitingReplyFrom":{"type":"string","enum":["CM","SELLER","BUYER"],"description":"Whose answer the thread waits for"},"photos":{"type":"array","items":{"type":"object","properties":{"contentBase64":{"type":"string","minLength":4,"maxLength":14000000,"description":"The picture, base64 (at most 10 MB)"},"contentType":{"type":"string","pattern":"^image\\/(jpeg|png|webp|heic|heif)$","description":"image/jpeg, image/png, image/webp or image/heic"},"fileName":{"type":"string","maxLength":200}},"required":["contentBase64","contentType"]},"maxItems":5,"description":"Up to 5 pictures (the VIN plate, the damage, the gate); the incident reads answer each with a link valid for an hour"}},"required":["message"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/sapele-read":{"post":{"tags":["Closings: the app's actions"],"summary":"Sapele's read of a closing: its health, the next step, who owes it and how urgent it is","description":"Sapele (Cypress's closing assistant) reads a closing's steps, deadlines, documents and open incidents and answers its health, the next step, who is responsible and how many days are left, as the Post-Sale panel does. Each call is a new read. Needs `insights:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"read_closing_with_sapele","x-cypress-action":"closings.sapele_read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/deal-setup":{"get":{"tags":["Closings: the app's actions"],"summary":"The deal's facts (pickup, bank, lender, title, transport, custom values) and each side's confirmation","description":"Deal Setup as Post-Sale shows it: the choices each side made (pickup location, the bank account paid into, the lender, the title address, the transporter), the custom values, the Bill of Sale template, and whether each side confirmed. Your side's half is yours to edit; the other's is read-only. A closing that predates Deal Setup says so (enable_closing_deal_setup). Needs `closing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"get_closing_deal_setup","x-cypress-action":"closings.deal_setup.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Closings: the app's actions"],"summary":"Choose the deal's pickup, bank account, lender, title address or transporter, or set custom values","description":"Changes your side's half of Deal Setup (only what is sent changes). It stays editable to the end. A change never reopens a completed step by itself: when it alters a value that paper on a completed step printed (not a box it left blank), the answer names that step in `reopenSuggested` and a Cypress Manager decides whether it is reopened and the paper made again. `rolledBack` is always null. Read get_deal_setup_impact first. Only the seller picks the Bill of Sale template. Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.UPDATED`. Since 1.5.0.","operationId":"update_closing_deal_setup","x-cypress-action":"closings.deal_setup.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"side":{"type":"string","enum":["SELLER","BUYER"],"description":"The side you act for; left out, your own (Cypress staff must name one)"},"selections":{"type":"object","properties":{"pickupLocationId":{"type":["string","null"],"minLength":1,"maxLength":64},"bankAccountId":{"type":["string","null"],"minLength":1,"maxLength":64},"lenderId":{"type":["string","null"],"minLength":1,"maxLength":64},"titleAddressId":{"type":["string","null"],"minLength":1,"maxLength":64},"transporterId":{"type":["string","null"],"minLength":1,"maxLength":64}},"description":"Library records to use (null clears one)"},"values":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":120},"value":{"type":["string","null"],"maxLength":4000}},"required":["key","value"]},"maxItems":50},"bosTemplateId":{"type":"string","minLength":1,"maxLength":64,"description":"The seller's Bill of Sale template for this deal"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Closings: the app's actions"],"summary":"Give a closing that predates Deal Setup its Deal Setup","description":"For a closing opened before Deal Setup existed: adds it. Steps already open stay open; a step still locked then waits for both sides to confirm. Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"enable_closing_deal_setup","x-cypress-action":"closings.deal_setup.enable","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/deal-setup/confirm":{"post":{"tags":["Closings: the app's actions"],"summary":"Sign off your side of Deal Setup; the second sign-off bills the commission and opens the Bill of Sale","description":"Your side confirms its half of Deal Setup. When both sides have, the commission is invoiced and the Bill of Sale step opens. A deal recorded as closed off-platform has nothing left to confirm. Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.UPDATED`. Since 1.5.0.","operationId":"confirm_closing_deal_setup","x-cypress-action":"closings.deal_setup.confirm","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"side":{"type":"string","enum":["SELLER","BUYER"],"description":"The side you act for; left out, your own (Cypress staff must name one)"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/deal-setup/impact":{"get":{"tags":["Closings: the app's actions"],"summary":"Which issued documents a Deal Setup change would make wrong, and whose signatures it would void","description":"Before update_closing_deal_setup: the documents Cypress rendered from Deal Setup, the facts each prints, and which are signed or out for signature, so a change's cost (paper made again, signatures voided) is known first. `needsRollback` marks paper on a completed step: a change to what it printed is only reopened if a Cypress Manager decides so. Needs `closing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_deal_setup_impact","x-cypress-action":"closings.deal_setup.impact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/deal-setup/core-facts":{"get":{"tags":["Closings: the app's actions"],"summary":"The deal's core facts (names, addresses) that differ from the records they came from","description":"The core facts the closing copied when it opened (the parties' names and addresses, the vehicle) that now disagree with their source records, for instance an address the seller fixed in its profile since. refresh_deal_setup_core_facts brings them in. Needs `closing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"get_deal_setup_core_facts","x-cypress-action":"closings.deal_setup.core_facts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Closings: the app's actions"],"summary":"Fill the deal's missing core facts from your records, or repoint named ones","description":"Without `keys`: fills the core facts still empty from their source records, never overwriting one. With `keys`: repoints those facts at the current records (only your side's). Documents rendered afterwards print the new facts. Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"refresh_deal_setup_core_facts","x-cypress-action":"closings.deal_setup.refresh_core","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":50,"description":"The facts to repoint (get_deal_setup_core_facts)"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/document-checklist":{"get":{"tags":["Closings: the app's actions"],"summary":"The documents the organization's checklist asks for that this closing does not carry","description":"For a closing that predates the document checklist, or one opened before a slot was added: the slots the checklist would add, change or drop (sync_closing_checklist applies them). Needs `closing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_closing_checklist_gaps","x-cypress-action":"closings.checklist.gaps","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Closings: the app's actions"],"summary":"Add the checklist's missing document slots to a closing (Cypress may also change or drop them)","description":"Adds the slots the checklist asks for and the closing lacks (a step that already holds its paper is skipped). `update` and `remove`, which rewrite a running closing's terms, are Cypress's. Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"sync_closing_checklist","x-cypress-action":"closings.checklist.sync","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"apply":{"type":"array","items":{"type":"string","enum":["add","update","remove"]},"minItems":1,"maxItems":3,"description":"Left out: add only"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/steps/{stepKey}/execution":{"get":{"tags":["Closings: the app's actions"],"summary":"The documents that must be fully signed before a step can complete, and how to clear each","description":"For one step: the documents elsewhere in the closing that must be fully signed first, each with where its signed copy is filed, a download link, and the requirement Cypress could waive. Needs `closing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"get_closing_step_blockers","x-cypress-action":"closings.steps.blockers","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"stepKey","in":"path","required":true,"schema":{"type":"string","enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/steps/{stepKey}/documents":{"post":{"tags":["Closings: the app's actions"],"summary":"Upload a document (PDF or picture) to a step: it goes to review","description":"Files a document on a step (into one of its slots), replacing the slot's current one; the step goes to review. `signedCopy` files the ink-signed copy of the step's generated document and records who signed it (`wetFor`). On the Bill of Sale the seller may name who is paid and the bank account or lender. Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.UPDATED`. Since 1.5.0.","operationId":"upload_closing_document","x-cypress-action":"closings.documents.upload","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"stepKey","in":"path","required":true,"schema":{"type":"string","enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentBase64":{"type":"string","minLength":4,"maxLength":28000000,"description":"The file, base64 (at most 20 MB)"},"contentType":{"type":"string","pattern":"^(application\\/pdf|image\\/(jpeg|jpg|png|heic|heif|webp))$","description":"application/pdf, image/jpeg, image/png, image/heic or image/webp"},"fileName":{"type":"string","maxLength":200},"slotKey":{"type":"string","minLength":1,"maxLength":80,"description":"The slot; left out, the step's default"},"signedCopy":{"type":"boolean","description":"This is the signed paper copy of the step's generated document"},"wetFor":{"type":"array","items":{"type":"string","enum":["seller","buyer","external"]},"maxItems":3,"description":"With signedCopy: whose ink is on it (the seller when left out). `external` is the transporter who signs the gate pass at the yard: the seller files the countersigned pass, and the pickup waits for that signature"},"paymentRecipient":{"type":"string","enum":["SELLER","LENDER"],"description":"Bill of Sale only: who is paid"},"lenderId":{"type":"string","minLength":1,"maxLength":64},"bankAccountId":{"type":"string","minLength":1,"maxLength":64}},"required":["contentBase64","contentType"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/documents/{documentId}":{"get":{"tags":["Closings: the app's actions"],"summary":"One document of a closing, with a link to view it (valid for an hour)","description":"One of the closing's documents: its name, type, size, status, review and a link to the file valid for an hour. get_closing lists the documents. Needs `closing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"get_closing_document","x-cypress-action":"closings.documents.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The document (get_closing)"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Closings: the app's actions"],"summary":"Remove a document that was not accepted; one out for signature needs voidSignatures","description":"Removes a document not yet accepted (the seller's side or Cypress): the step waits for a document again. A document out for signature is only removed with `voidSignatures: true`, which kills its signing links first; one already signed by someone is never removed (file a replacement). Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.UPDATED`. Since 1.5.0.","operationId":"delete_closing_document","x-cypress-action":"closings.documents.delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"voidSignatures":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/steps/{stepKey}/generation":{"get":{"tags":["Closings: the app's actions"],"summary":"The templates a step's document can be made from, and what each would print blank","description":"For a step (and slot): the templates its document can be generated from, the fields each would print blank today, and who would sign. generate_closing_document makes it. Needs `closing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_closing_document_options","x-cypress-action":"closings.documents.options","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"stepKey","in":"path","required":true,"schema":{"type":"string","enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"}},{"name":"slotKey","in":"query","required":false,"schema":{"type":"string","maxLength":80}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/steps/{stepKey}/generate":{"post":{"tags":["Closings: the app's actions"],"summary":"Render a step's document from a template with the deal's facts and file it","description":"Renders the step's document (Bill of Sale, gate pass, delivery receipt, the seller's policy) from a template with Deal Setup's facts and files it as the slot's current document; the step goes to review. Over a document already out for signature it is refused unless `voidSignatures` (the old links die first). Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.DOCUMENT.GENERATED`. Since 1.5.0.","operationId":"generate_closing_document","x-cypress-action":"closings.documents.generate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"stepKey","in":"path","required":true,"schema":{"type":"string","enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"templateId":{"type":"string","minLength":1,"maxLength":64,"description":"get_closing_document_options"},"slotKey":{"type":"string","minLength":1,"maxLength":80},"overrides":{"type":"object","additionalProperties":{"type":"string","maxLength":2000},"description":"Values for the fields the template lets you override"},"voidSignatures":{"type":"boolean"}},"required":["templateId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/steps/{stepKey}/signatures":{"get":{"tags":["Closings: the app's actions"],"summary":"Who signs a step's document, in what order, and where each signature stands","description":"For a step's current document: before it is sent, the parties that would sign and the addresses on file; after, each signer's status and your own side's signing links. Needs `closing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"get_closing_signatures","x-cypress-action":"closings.signatures.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"stepKey","in":"path","required":true,"schema":{"type":"string","enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"}},{"name":"slotKey","in":"query","required":false,"schema":{"type":"string","maxLength":80}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Closings: the app's actions"],"summary":"Email each party its signing link for a step's document, in order","description":"Sends the step's current document out for e-signature: each party is emailed its link in the order the template set. An uploaded document chooses its route: `esign` to the parties named, `paper` (nobody is emailed; the slot waits for the signed copy) or `already-signed`. Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.UPDATED`. Since 1.5.0.","operationId":"send_closing_document_for_signature","x-cypress-action":"closings.signatures.send","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"stepKey","in":"path","required":true,"schema":{"type":"string","enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string","minLength":1,"maxLength":64,"description":"The slot's current document (refused if a newer one replaced it)"},"slotKey":{"type":"string","minLength":1,"maxLength":80},"contacts":{"type":"object","additionalProperties":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","maxLength":200,"format":"email"}}},"description":"Corrections by party key"},"route":{"type":"string","enum":["esign","paper","already-signed"],"description":"Uploaded documents only"},"parties":{"type":"array","items":{"type":"string","enum":["seller","buyer"]},"maxItems":2,"description":"Who signs, for esign on an upload"}},"required":["documentId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/documents/{documentId}/signatures/{party}/email":{"post":{"tags":["Closings: the app's actions"],"summary":"Point a signing request at a corrected email and send the link there","description":"When nothing has been reaching a signer: repoints their signing request at the corrected address and emails the link. Only the signer whose turn it is. The seller corrects its own signers' addresses; another party's (the buyer's, an outside signer's) only Cypress staff, since whoever holds a link can sign in that party's place (owner, 2026-11-01). resend_signing_link re-sends to the address on file. Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"correct_signer_email","x-cypress-action":"closings.signatures.correct_email","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"party","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"description":"The signing party's key (get_closing_signatures)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":200,"format":"email"}},"required":["email"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/commission-invoice":{"post":{"tags":["Closings: the app's actions"],"summary":"The seller's commission invoice for a closing, raised if it never was","description":"For the seller: the commission invoice of the closing's fee step, with its document. When the invoice was never raised it is raised now (and settled when Cypress's own record says it is paid). Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"get_commission_invoice","x-cypress-action":"closings.commission_invoice","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/commission-invoice/checkout":{"post":{"tags":["Closings: the app's actions"],"summary":"Stripe's payment form for the seller's commission invoice, for the person to pay in the app","description":"For the seller, in an app Cypress made (Grove): opens a Stripe payment (embedded Checkout) for the closing's commission invoice and answers the form's `clientSecret` with Stripe's `publishableKey`, so the app shows Stripe's own card form to the person, who pays there. Card details go to Stripe only, never to Cypress or the app. Paying stays a person's: an agent or an API key is refused, and so is any app Cypress did not make. Once paid, the fee step completes (CLOSING.STEP.COMPLETED, BILLING.UPDATED) as from Cypress's Pay Now. `saveCard` keeps the card for the organization's next commissions, charged when Deal Setup is confirmed. Refused while the commission is not invoiced yet, already paid, or on the organization's cycle bill. Since 1.11.0. Needs `closing:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.11.0.","operationId":"start_commission_payment","x-cypress-action":"closings.commission_invoice.checkout","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"saveCard":{"type":"boolean","description":"Keep the card for the organization's next commissions (default false)"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/cancel":{"post":{"tags":["Closings: Cypress staff"],"summary":"Cancel a closing in progress, with who is responsible and what becomes of the vehicle","description":"Cancels a closing in progress: the vehicle goes back to inventory (approved), or is archived as sold elsewhere or removed; both sides are told. Records the reason, who is responsible and Cypress's decision toward them. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.CANCELLED`. Since 1.5.0.","operationId":"cancel_closing","x-cypress-action":"closings.cancel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cancelReason":{"type":"string","minLength":1,"maxLength":2000},"cancelCulpritRole":{"type":"string","enum":["SELLER","BUYER","NONE"]},"vehicleDisposition":{"type":"string","enum":["RETURN_TO_INVENTORY","SOLD_ELSEWHERE","DEAL_FELL_THROUGH","REMOVED"]},"decision":{"type":"string","enum":["NO_ACTION","WARNING","PENALTY_FEE","ESCALATE_REVIEW"]},"cancelNote":{"type":"string","maxLength":2000}},"required":["cancelReason","cancelCulpritRole","vehicleDisposition"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/commission-scheme":{"patch":{"tags":["Closings: Cypress staff"],"summary":"Change the commission scheme a deal carries, until its fee is invoiced","description":"Corrects the commission scheme snapshotted on the deal at acceptance, until the fee step invoices it; after that it is refused (issue a credit note and rebill). Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"correct_closing_commission","x-cypress-action":"closings.commission_scheme.set","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commissionSchemeId":{"type":"string","minLength":1,"maxLength":64},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["commissionSchemeId","reason"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/off-platform":{"post":{"tags":["Closings: Cypress staff"],"summary":"Attest the steps that happened outside Cypress; all of them close the deal and the vehicle is sold","description":"Records steps of a sale completed outside Cypress, each attested by you with the reason; steps left out stay open. Attesting them all closes the closing and marks the vehicle sold. An unpaid commission is settled in the same call (`commission`). Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.COMPLETED`. Since 1.5.0.","operationId":"record_off_platform_closing","x-cypress-action":"closings.off_platform","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000},"attestedSteps":{"type":"array","items":{"type":"string","enum":["BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"]},"minItems":1},"commission":{"type":"object","properties":{"amountCents":{"type":"integer","exclusiveMinimum":0},"reference":{"type":"string","minLength":1,"maxLength":200},"paidAt":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"method":{"type":"string","enum":["wire","bank_deposit","check","other"]},"note":{"type":"string","maxLength":1000}},"required":["amountCents","reference","paidAt","method"],"description":"How the commission was paid, when it is not settled yet"}},"required":["reason","attestedSteps"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/fee/regenerate":{"post":{"tags":["Closings: Cypress staff"],"summary":"Re-run the fee step's invoicing when it failed","description":"For a fee step still pending with no invoice: raises the commission invoice. Safe to repeat: it never raises a second one. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"regenerate_closing_fee","x-cypress-action":"closings.fee.regenerate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/requirements/{requirementId}":{"patch":{"tags":["Closings: Cypress staff"],"summary":"Waive (or restore) one required document on one closing","description":"Waives a required document on this closing only, with the reason (so its step can complete without it), or restores it. Both directions are audited. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"waive_closing_requirement","x-cypress-action":"closings.requirements.waive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"requirementId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"get_closing `requirements[].id`"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"waive":{"type":"boolean"},"reason":{"type":"string","minLength":3,"maxLength":500,"description":"Required to waive"}},"required":["waive"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/rollback":{"post":{"tags":["Closings: Cypress staff"],"summary":"Reopen a closing from a step: that step pending again, every later one locked","description":"Rolls the closing back: the step named is pending again and every later step locked; the seller is told to redo it. Never to the fee step. Also how a closing is restarted on the current flow. Since 1.9.0 a first-party app acting for Cypress staff (Grove) may run it too, holding `closing:write`, on a closing of the organization it acts for (as seller or buyer). Cypress staff: a CM token, or a first-party app acting for Cypress staff holding `closing:write`, on a record of the organization it acts for. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.UPDATED`. Since 1.5.0.","operationId":"rollback_closing","x-cypress-action":"closings.rollback","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"toStepKey":{"type":"string","enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step to reopen"},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["toStepKey","reason"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/steps/{stepKey}/staff-actions":{"post":{"tags":["Closings: Cypress staff"],"summary":"Cypress's step actions: approve or reject an uploaded Bill of Sale, accept it signed offline, confirm a step or a payment","description":"The staff step actions of Post-Sale: approve an uploaded Bill of Sale (who is paid, and how the buyer countersigns) and send it on, reject it with the reason, accept one already signed by both offline, confirm a step by hand (with how you know), confirm a payment on an older closing. The parties' own step actions are mark_closing_step. Since 1.9.0 a first-party app acting for Cypress staff (Grove) may run `confirm` and `confirm_payment`, holding `closing:write`, on a closing of the organization it acts for; the Bill of Sale review takes a CM token. Cypress staff: a CM token, or a first-party app acting for Cypress staff holding `closing:write`, on a record of the organization it acts for. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.STEP.COMPLETED`. Since 1.5.0.","operationId":"run_closing_staff_action","x-cypress-action":"closings.steps.staff_action","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"stepKey","in":"path","required":true,"schema":{"type":"string","enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["approve_bos","reject_bos","accept_bos_offline","confirm","confirm_payment"]},"paymentRecipient":{"type":"string","enum":["SELLER","LENDER"]},"lenderId":{"type":"string","minLength":1,"maxLength":64},"signatureRoute":{"type":"string","enum":["esign","paper"],"description":"approve_bos: how the buyer countersigns"},"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"reject_bos: why"},"note":{"type":"string","maxLength":500},"reference":{"type":"string","maxLength":200},"amount":{"type":"string","maxLength":40}},"required":["action"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/incidents/{incidentId}/status":{"post":{"tags":["Closings: Cypress staff"],"summary":"Take an incident in hand, resolve it or dismiss it","description":"Moves an incident on: in progress, resolved or dismissed (with a note); the reporter is told. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.UPDATED`. Since 1.5.0.","operationId":"set_closing_incident_status","x-cypress-action":"closings.incidents.status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"incidentId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["IN_PROGRESS","RESOLVED","DISMISSED"]},"resolvedNote":{"type":"string","maxLength":2000}},"required":["status"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/documents/{documentId}/analyze":{"post":{"tags":["Closings: Cypress staff"],"summary":"Run Aspen's document analysis on a closing document","description":"Runs Aspen's analysis of one closing document again (the VIN, the parties, the amounts and signatures it finds, and what looks wrong) and answers it. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"analyze_closing_document","x-cypress-action":"closings.documents.analyze","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closings/{id}/documents/{documentId}/review":{"post":{"tags":["Closings: Cypress staff"],"summary":"Accept a document in review, or reject it with the reason so it is filed again","description":"Accepts a document in review (its step then waits for its action), or rejects it with the reason: the step returns to pending so the party files it again. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `CLOSING.UPDATED`. Since 1.5.0.","operationId":"review_closing_document","x-cypress-action":"closings.documents.review","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The closing's id (list_closings)"}},{"name":"documentId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["accept","reject"]},"reason":{"type":"string","minLength":1,"maxLength":2000,"description":"Required to reject"}},"required":["action"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closing-checklist":{"get":{"tags":["Closings: Cypress staff"],"summary":"The documents closings require: Cypress's base list, or an organization's own copy","description":"The closing document checklist: with `orgId`, the one that organization's closings snapshot (its own copy, or the base); without, Cypress's base list. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_closing_checklist","x-cypress-action":"closing_checklist.get","parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The organization; left out, the base list"},"description":"The organization; left out, the base list"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Closings: Cypress staff"],"summary":"Add one required document to the base checklist or an organization's copy","description":"Adds one document slot to a step of the base checklist (no `orgId`) or of an organization's own copy. Closings already open are not touched (sync_closing_checklist brings one up to date). Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"add_closing_checklist_item","x-cypress-action":"closing_checklist.items.add","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":["string","null"],"minLength":1,"maxLength":64},"stepKey":{"type":"string","enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"},"slotKey":{"type":"string","minLength":1,"maxLength":80,"pattern":"^[a-z0-9-]+$","description":"lowercase letters, digits and dashes"},"name":{"type":"string","minLength":1,"maxLength":120},"kind":{"type":["string","null"],"enum":["BILL_OF_SALE","GATE_PASS","DELIVERY_RECEIPT","SELLER_POLICY"]},"templateId":{"type":["string","null"],"minLength":1,"maxLength":64},"required":{"type":"boolean"},"executedByStepKey":{"type":["string","null"],"enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"}},"required":["stepKey","slotKey","name"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closing-checklist/customize":{"post":{"tags":["Closings: Cypress staff"],"summary":"Copy the base checklist for an organization to personalize, or revert it to the base","description":"`customize` copies the base checklist into the organization's own, to personalize; `revert` archives its copy so the base applies again. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"customize_closing_checklist","x-cypress-action":"closing_checklist.customize","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"string","minLength":1,"maxLength":64},"action":{"type":"string","enum":["customize","revert"]}},"required":["orgId","action"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/closing-checklist/{id}":{"patch":{"tags":["Closings: Cypress staff"],"summary":"Rename a checklist document, move it, make it optional or required, reorder or archive it","description":"Changes one checklist item; only what is sent changes. Closings already open keep their snapshot. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"change_closing_checklist_item","x-cypress-action":"closing_checklist.items.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The checklist item"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"stepKey":{"type":"string","enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"},"kind":{"type":["string","null"],"enum":["BILL_OF_SALE","GATE_PASS","DELIVERY_RECEIPT","SELLER_POLICY"]},"templateId":{"type":["string","null"],"minLength":1,"maxLength":64},"required":{"type":"boolean"},"executedByStepKey":{"type":["string","null"],"enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"},"sortOrder":{"type":"integer","minimum":0,"maximum":999},"isArchived":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Closings: Cypress staff"],"summary":"Take a document off a checklist (its slot key stays reserved)","description":"Archives one checklist item; closings already open keep their snapshot. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"archive_closing_checklist_item","x-cypress-action":"closing_checklist.items.archive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The checklist item"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/document-templates":{"get":{"tags":["Document templates: the app's actions"],"summary":"Your organization's closing document templates and Cypress's defaults","description":"The templates your closings can generate from (Bill of Sale, gate pass, delivery receipt, your policy): your own and Cypress's defaults, each with whether you may edit it and its published version. Cypress staff list the base templates alone with `scope: platform`. Needs `documents:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_document_templates","x-cypress-action":"document_templates.list","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["platform"],"description":"Cypress staff: the base templates only"},"description":"Cypress staff: the base templates only"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Document templates: the app's actions"],"summary":"A new template, blank or copied from a Cypress default (a draft)","description":"Creates a template of a kind, blank or as a copy of a Cypress default (`cloneFromId`) to personalize. It starts as a draft: nothing generates from it until publish_document_template. Cypress staff create base templates with `scope: PLATFORM`. Needs `documents:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"create_document_template","x-cypress-action":"document_templates.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["BILL_OF_SALE","GATE_PASS","DELIVERY_RECEIPT","SELLER_POLICY"]},"name":{"type":"string","minLength":1,"maxLength":120},"cloneFromId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"A Cypress default to copy"},"scope":{"type":"string","enum":["ORG","PLATFORM"],"description":"PLATFORM: a base template (Cypress staff)"}},"required":["kind","name"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/document-templates/{id}":{"get":{"tags":["Document templates: the app's actions"],"summary":"A template's draft and published layout, and every field it may bind","description":"One template as the designer opens it: its draft (or published) layout, its versions, and the universe of fields a layout may bind (the deal's facts, the parties, the vehicle). Needs `documents:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_document_template","x-cypress-action":"document_templates.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The template"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Document templates: the app's actions"],"summary":"Rename a template or save its draft layout (never the published version)","description":"Saves the template's draft: its name, description or layout (`definition`, the designer's canvas as get_document_template answers it). A draft may be half-finished; publish_document_template checks it. Needs `documents:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"save_document_template_draft","x-cypress-action":"document_templates.save_draft","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"],"maxLength":2000},"definition":{"description":"The canvas definition"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Document templates: the app's actions"],"summary":"Archive a template: closings stop generating from it","description":"Archives one of your templates; documents already generated from it keep their version. Needs `documents:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"archive_document_template","x-cypress-action":"document_templates.archive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/document-templates/{id}/background":{"post":{"tags":["Document templates: the app's actions"],"summary":"Upload a PDF (1 to 50 pages) the template draws onto, in its draft","description":"Sets the draft's background: a PDF of your own letterhead or form (at most 25 MB, 1 to 50 pages) that the template's fields are drawn onto. Needs `documents:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"set_document_template_background","x-cypress-action":"document_templates.background.set","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentBase64":{"type":"string","minLength":4,"maxLength":35000000,"description":"The file, base64 (at most 25 MB)"},"contentType":{"type":"string","pattern":"^application\\/pdf$","description":"application/pdf"},"fileName":{"type":"string","maxLength":200}},"required":["contentBase64","contentType"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Document templates: the app's actions"],"summary":"Back to blank pages, in the draft","description":"Removes the draft's background PDF, so the template draws onto blank pages again; the published version keeps its background until the next publish. Needs `documents:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"remove_document_template_background","x-cypress-action":"document_templates.background.remove","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/document-templates/{id}/checklist-slot":{"get":{"tags":["Document templates: the app's actions"],"summary":"The closing step a template's document is required at, if any","description":"Where the template is used: the closing step (and checklist slot) it fills, whether it is required, the step that waits for it to be signed, and whether it is the default Bill of Sale. Needs `documents:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_document_template_step","x-cypress-action":"document_templates.step.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Closings: Cypress staff"],"summary":"Make a template the document a closing step requires, or clear it","description":"Assigns the template to a closing step (its checklist slot is created or moved), sets whether it is required and which step waits for its signatures, makes it the organization's default Bill of Sale, or clears the assignment (`stepKey: null`). Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"assign_document_template_step","x-cypress-action":"document_templates.step.set","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"stepKey":{"type":["string","null"],"enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"},"defaultBos":{"type":"boolean"},"required":{"type":"boolean"},"executedByStepKey":{"type":["string","null"],"enum":["FEE","BOS","BUYER_SIGN","PAYMENT","CONFIRM_FUNDS","GATE_PASS","TITLE","TITLE_RECEIPT","PICKUP"],"description":"The step, by its key (get_closing lists the closing's steps)"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/document-templates/{id}/publish":{"post":{"tags":["Document templates: the app's actions"],"summary":"Make the draft the live version that closings generate from","description":"Publishes the draft: refused while any field is bound to something that cannot fill it. Every published version is kept; documents already generated keep theirs. Your policy (SELLER_POLICY) is what buyers then accept. Needs `documents:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"publish_document_template","x-cypress-action":"document_templates.publish","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/document-templates/{id}/versions":{"get":{"tags":["Document templates: the app's actions"],"summary":"Every published version of a template, newest first","description":"The template's published versions (each immutable), with when and by whom. restore_document_template_version puts one back on the draft. Needs `documents:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_document_template_versions","x-cypress-action":"document_templates.versions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/document-templates/{id}/versions/{versionId}/restore":{"post":{"tags":["Document templates: the app's actions"],"summary":"Copy an earlier version's layout onto the draft (it is not published)","description":"Copies an earlier published version's layout into the draft; nothing goes live until publish_document_template. Needs `documents:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"restore_document_template_version","x-cypress-action":"document_templates.restore","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"list_document_template_versions"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/document-templates/images":{"get":{"tags":["Document templates: the app's actions"],"summary":"Your organization's pictures for documents, and the company logo slot","description":"The pictures a template may place: the company logo (resolved per organization when a document is made) and the pictures your organization uploaded. Needs `documents:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_document_images","x-cypress-action":"document_templates.images.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Document templates: the app's actions"],"summary":"Upload a PNG or JPEG your templates can place","description":"Adds a picture (PNG or JPEG, at most 8 MB) to the organization's documents; list_document_images lists it. Needs `documents:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"upload_document_image","x-cypress-action":"document_templates.images.upload","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentBase64":{"type":"string","minLength":4,"maxLength":11200000,"description":"The file, base64 (at most 8 MB)"},"contentType":{"type":"string","pattern":"^image\\/(png|jpeg)$","description":"image/png or image/jpeg"},"fileName":{"type":"string","maxLength":200}},"required":["contentBase64","contentType"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/storefront":{"get":{"tags":["Storefront and share links: the app's actions"],"summary":"Your public storefront: on or off, its address, title, headline, colors, pictures","description":"The organization's storefront page: whether it is published, its address (/s/<slug>), title, headline, accent color, banner and logo (links valid for an hour), whether the organization holds the storefront channel, and how many vehicles put_fleet_on_storefront would add. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_storefront","x-cypress-action":"storefront.get","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Storefront and share links: the app's actions"],"summary":"Publish or take down your storefront, or change its title, headline and color","description":"Changes the storefront; only what is sent changes. `storefrontEnabled: false` takes the page down; when that would leave vehicles reachable nowhere it is refused unless `republishStorefrontOnly`. The banner and logo are set by set_storefront_banner and set_storefront_logo; here `null` only clears them. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"update_storefront","x-cypress-action":"storefront.update","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"storefrontEnabled":{"type":"boolean"},"storefrontTitle":{"type":["string","null"],"maxLength":120,"description":"null: the organization's name"},"storefrontHeadline":{"type":["string","null"],"maxLength":2000},"storefrontAccentColor":{"type":["string","null"],"pattern":"^#[0-9a-fA-F]{6}$"},"storefrontBannerUrl":{"type":"null","description":"null clears the banner"},"logoUrl":{"type":"null","description":"null clears the logo"},"republishStorefrontOnly":{"type":"boolean","description":"Confirms taking it down although some vehicles were only there"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/storefront/banner":{"post":{"tags":["Storefront and share links: the app's actions"],"summary":"Upload the picture across the top of your storefront","description":"Sets the storefront's banner picture and answers a link to it valid for an hour. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"set_storefront_banner","x-cypress-action":"storefront.banner","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentBase64":{"type":"string","minLength":4,"maxLength":14000000,"description":"The file, base64 (at most 10 MB)"},"contentType":{"type":"string","pattern":"^image\\/(jpeg|png|webp)$","description":"image/jpeg, image/png or image/webp"},"fileName":{"type":"string","maxLength":200}},"required":["contentBase64","contentType"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/storefront/logo":{"post":{"tags":["Storefront and share links: the app's actions"],"summary":"Upload the organization's logo (the storefront and your documents use it)","description":"Sets the organization's logo, shown on the storefront and printed where a document template places the company logo; answers a link valid for an hour. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"set_storefront_logo","x-cypress-action":"storefront.logo","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contentBase64":{"type":"string","minLength":4,"maxLength":14000000,"description":"The file, base64 (at most 10 MB)"},"contentType":{"type":"string","pattern":"^image\\/(jpeg|png|webp)$","description":"image/jpeg, image/png or image/webp"},"fileName":{"type":"string","maxLength":200}},"required":["contentBase64","contentType"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/storefront/backfill":{"post":{"tags":["Storefront and share links: the app's actions"],"summary":"Show every vehicle eligible for the storefront on it, in one go","description":"Shows on the storefront every vehicle that can be there and is not yet (get_storefront says how many). Answers how many were added. set_vehicles_on_storefront picks vehicles one by one. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"put_fleet_on_storefront","x-cypress-action":"storefront.backfill","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/share-links/{linkId}/revoke":{"post":{"tags":["Storefront and share links: the app's actions"],"summary":"Revoke one of a vehicle's share links: whoever holds it no longer sees the vehicle","description":"Revokes one share link (Direct Links); the vehicle's other links keep working. When it was the last way to the vehicle, the vehicle's marketplace visibility changes and the answer says to what. revoke_share_links stops every link of the vehicles named. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"revoke_vehicle_share_link","x-cypress-action":"vehicles.share_links.revoke","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"linkId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The share link (list_vehicle_share_links)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/share-links/{linkId}/reactivate":{"post":{"tags":["Storefront and share links: the app's actions"],"summary":"Reactivate a revoked share link (an expired one needs a new expiry)","description":"Turns a revoked share link back on; one past its expiry needs `expiresAt` (a later date, or null for none). A deleted link cannot come back. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"reactivate_vehicle_share_link","x-cypress-action":"vehicles.share_links.reactivate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"linkId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expiresAt":{"type":["string","null"],"format":"date-time"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/share-links/{linkId}":{"delete":{"tags":["Storefront and share links: the app's actions"],"summary":"Delete one share link (it is revoked first; its past visits stay in the market history)","description":"Deletes a share link from the vehicle's list; it stops admitting anyone at once. Its past visits still show in get_vehicle_market_history. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"delete_vehicle_share_link","x-cypress-action":"vehicles.share_links.delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"linkId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/on-market":{"get":{"tags":["Storefront and share links: the app's actions"],"summary":"Your approved, live, held, under-offer, accepted and recently sold vehicles, with views, saves and offers","description":"The Seller Hub's grid: each vehicle from approved to sold, with its days on market, its views, saves and offers and their trend, what needs attention (no views, long on market, open offers), its offer rules and Sakura's latest read. Sort by price, views, days or status. Needs `listings`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_vehicles_on_market","x-cypress-action":"vehicles.on_market","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Comma-separated: APPROVED, LISTED, ON_HOLD, UNDER_OFFER, OFFER_ACCEPTED, SOLD"},"description":"Comma-separated: APPROVED, LISTED, ON_HOLD, UNDER_OFFER, OFFER_ACCEPTED, SOLD"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["price","views","days","status"]}},{"name":"dir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"1-based (1 when left out)"},"description":"1-based (1 when left out)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/sakura-read":{"post":{"tags":["Storefront and share links: the app's actions"],"summary":"A fresh Sakura read of one of your vehicles: hold, reprice or sell, and why","description":"Sakura reads one of your vehicles again (in the sell plan's context when the fleet has one) and answers the read the Seller Hub shows: its advice, confidence and reasoning. Needs `insights:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"refresh_vehicle_sakura_read","x-cypress-action":"vehicles.sakura_read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/dealer-request":{"get":{"tags":["Organization and settings: the app's actions"],"summary":"An individual's latest request to become a dealer, and the business checklist it needs","description":"Settings › Become a dealer: the latest request (PENDING, APPROVED, DECLINED with Cypress's reason) and the business checklist Cypress approves it on (the W-9 and the dealer license, uploaded in Settings › Documents and reviewed by Cypress; a billing method). Since 1.9.0. Needs `organization:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.9.0.","operationId":"get_dealer_request","x-cypress-action":"organization.dealer_request.get","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Organization and settings: the app's actions"],"summary":"An individual asks Cypress to make its account a business","description":"Gives the business (its legal name, EIN, address) and asks Cypress to make this individual's account a business. Cypress approves it once the business checklist is done; the same organization becomes the business, its cars, offers and sales kept. One request waits at a time; the email must be confirmed first. Since 1.9.0. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.9.0.","operationId":"request_dealer_account","x-cypress-action":"organization.dealer_request.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessName":{"type":"string","minLength":2,"maxLength":120,"description":"The business's legal name"},"taxId":{"type":["string","null"],"maxLength":20,"description":"Its EIN"},"address":{"type":["string","null"],"maxLength":200},"city":{"type":["string","null"],"maxLength":80},"state":{"type":["string","null"],"maxLength":2,"description":"Two letters"},"zip":{"type":["string","null"],"maxLength":10},"phone":{"type":["string","null"],"maxLength":40},"website":{"type":["string","null"],"maxLength":200}},"required":["businessName","taxId","address","city","state","zip","phone","website"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/profile":{"get":{"tags":["Organization and settings: the app's actions"],"summary":"The organization's name, address, tax id and primary contact, its Cypress Manager, and what Cypress may do for it","description":"Settings › Organization: the name, website, phone, tax id, address and primary contact, and the three delegation switches (Cypress may act on your behalf, decide review offers, make buyer offers). `accountManager` is the organization's Cypress Manager, the person at Cypress who looks after it: `{ id, name, email }`, or null when none is assigned (since 1.9.0). get_organization says what the credential may do; this is who the organization is. Needs `organization:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"get_organization_profile","x-cypress-action":"organization.profile.get","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Organization and settings: the app's actions"],"summary":"Change the organization's name, address, tax id or primary contact (only the fields sent)","description":"Settings › Organization's Save, as an admin of the organization makes it: only the fields sent change, null clears one. What Cypress may do on your behalf is not here (set_cypress_delegation, a person's). Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"update_organization_profile","x-cypress-action":"organization.profile.update","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120,"description":"The organization's name"},"website":{"type":["string","null"],"maxLength":500},"phone":{"type":["string","null"],"maxLength":30},"taxId":{"type":["string","null"],"maxLength":50,"description":"EIN or tax id"},"address":{"type":["string","null"],"maxLength":200},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"zip":{"type":["string","null"],"maxLength":20},"country":{"type":["string","null"],"maxLength":100},"primaryContactName":{"type":["string","null"],"maxLength":100},"primaryContactEmail":{"type":["string","null"],"maxLength":200,"format":"email"},"primaryContactPhone":{"type":["string","null"],"maxLength":30}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/delegation":{"patch":{"tags":["Organization and settings: the app's actions"],"summary":"Consent: whether Cypress may act on your behalf, decide review offers, make buyer offers","description":"The delegation switches of Settings › Organization: consent an admin gives or takes back, audited as before and after. Since 1.9.0 it takes an end date (`expiresAt`): from that moment the switches read as off everywhere, and get_organization says so (`delegation.expiresAt`, `expired`); null clears it. A switch granted again after its end date passed, with no new one, is granted without an end date. Your organization's admins only. A person's act through an app acting for them: an API key acts as no one, an agent never consents, and Cypress staff never grant themselves. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"set_cypress_delegation","x-cypress-action":"organization.delegation.set","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"allowCypressActOnBehalf":{"type":"boolean","description":"Cypress may onboard and manage vehicles for you"},"allowCMReviewOfferDecisions":{"type":"boolean","description":"Cypress may accept or decline offers that need review"},"allowCMBuyerOffers":{"type":"boolean","description":"Cypress may make offers as your buyer"},"expiresAt":{"type":["string","null"],"format":"date-time","description":"When the switches end (ISO 8601, in the future); null for no end date. Since 1.9.0"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/onboarding":{"get":{"tags":["Organization and settings: the app's actions"],"summary":"The organization's status and, while provisional, the onboarding items still open","description":"The \"finish onboarding\" banner: the organization's status, and while it is PROVISIONAL the checklist items (W-9, dealer license, bank account and the like) and which are still pending. get_organization gives the reason each refused capability is refused. Needs `organization:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_onboarding_status","x-cypress-action":"organization.onboarding.get","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/members/invitations":{"post":{"tags":["Members: the app's actions"],"summary":"Invite a person as Fleet Manager or Billing Admin (they get an email to set a password)","description":"Settings › Team's Invite, an admin's: the person joins at once (an existing Cypress user is added; a new one gets an account) and receives an email to set their password. Only Fleet Manager or Billing Admin: making someone an admin is change_member_role. A person's act: it changes who can act for the organization. Needs `members:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `MEMBER.UPDATED`. Since 1.5.0.","operationId":"invite_member","x-cypress-action":"members.invite","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["FLEET_MANAGER","BILLING_ADMIN"]},"firstName":{"type":"string","minLength":1,"maxLength":50},"lastName":{"type":"string","minLength":1,"maxLength":50}},"required":["email","role"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/members/{userId}/role":{"put":{"tags":["Members: the app's actions"],"summary":"Make a member an Admin, Fleet Manager or Billing Admin (never your own role, never an agent's)","description":"Settings › Team's role menu, an admin's: the member's role in Cypress and at sign-in changes. Your own role is refused, and so is an agent's (its access is its connection's). A person's act: it changes who can act for the organization. Needs `members:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `MEMBER.UPDATED`. Since 1.5.0.","operationId":"change_member_role","x-cypress-action":"members.change_role","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The member (list_members gives the ids)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["ADMIN","FLEET_MANAGER","BILLING_ADMIN"]}},"required":["role"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/members/{userId}":{"delete":{"tags":["Members: the app's actions"],"summary":"Take a person out of the organization (never yourself, never the last admin, never an agent)","description":"Settings › Team's Remove, an admin's: the membership ends and the person can no longer sign in to the organization. Yourself, the last active admin and an agent (disconnect its app instead) are refused. Needs `members:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `MEMBER.UPDATED`. Since 1.5.0.","operationId":"remove_member","x-cypress-action":"members.remove","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The member"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/locations":{"get":{"tags":["Organization and settings: the app's actions"],"summary":"The lots and yards vehicles are picked up from, active first","description":"Settings › Locations: each lot with its address, contact, hours, pickup notice, optional PO number (poNumber) and, since 1.9.0, its `aliases` (the other names files use for it); archived ones last (isActive false). Needs `organization:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_locations","x-cypress-action":"locations.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Organization and settings: the app's actions"],"summary":"Add a lot or yard (names are unique in the organization)","description":"Settings › Locations' Add: a new pickup or storage location with its name and address. A name already in use is refused (CONFLICT). Answers the location. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"create_location","x-cypress-action":"locations.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"zip":{"type":["string","null"],"pattern":"^\\d{5}$"},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"minLength":2,"maxLength":2,"description":"Two-letter state code"},"fullAddress":{"type":["string","null"],"maxLength":500},"contactName":{"type":["string","null"],"maxLength":120},"contactPhone":{"type":["string","null"],"maxLength":40},"contactEmail":{"type":["string","null"],"maxLength":200},"hours":{"type":["string","null"],"maxLength":200,"description":"When the lot is open, as people write it"},"advanceNoticeNote":{"type":["string","null"],"maxLength":300,"description":"How much notice a pickup needs"},"poNumber":{"type":["string","null"],"maxLength":64,"description":"Optional purchase order number your organization issued to Cypress for this location. Trimmed; an empty string or null clears it. Since 1.7.0"},"notes":{"type":["string","null"],"maxLength":1000},"aliases":{"type":["array","null"],"items":{"type":"string","maxLength":64},"maxItems":20,"description":"Other names your files and feeds use for this location (\"HOU-2\"), up to 20: an import row or a push naming one is put at this location. Replaces the list; null or [] clears it. A name another location already answers to is refused (CONFLICT). A person sets them. Since 1.9.0"}},"required":["name"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/locations/{locationId}":{"patch":{"tags":["Organization and settings: the app's actions"],"summary":"Change a location's details (address, contact, PO number, aliases), or bring an archived one back (isActive)","description":"Settings › Locations' Edit: only the fields sent change. `isActive: true` restores an archived location. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"update_location","x-cypress-action":"locations.update","parameters":[{"name":"locationId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"zip":{"type":["string","null"],"pattern":"^\\d{5}$"},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"minLength":2,"maxLength":2,"description":"Two-letter state code"},"fullAddress":{"type":["string","null"],"maxLength":500},"contactName":{"type":["string","null"],"maxLength":120},"contactPhone":{"type":["string","null"],"maxLength":40},"contactEmail":{"type":["string","null"],"maxLength":200},"hours":{"type":["string","null"],"maxLength":200,"description":"When the lot is open, as people write it"},"advanceNoticeNote":{"type":["string","null"],"maxLength":300,"description":"How much notice a pickup needs"},"poNumber":{"type":["string","null"],"maxLength":64,"description":"Optional purchase order number your organization issued to Cypress for this location. Trimmed; an empty string or null clears it. Since 1.7.0"},"notes":{"type":["string","null"],"maxLength":1000},"aliases":{"type":["array","null"],"items":{"type":"string","maxLength":64},"maxItems":20,"description":"Other names your files and feeds use for this location (\"HOU-2\"), up to 20: an import row or a push naming one is put at this location. Replaces the list; null or [] clears it. A name another location already answers to is refused (CONFLICT). A person sets them. Since 1.9.0"},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Organization and settings: the app's actions"],"summary":"Archive a location (kept for history; update_location brings it back)","description":"Settings › Locations' Remove: the location is archived, never deleted. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"archive_location","x-cypress-action":"locations.archive","parameters":[{"name":"locationId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/lenders":{"get":{"tags":["Organization and settings: the app's actions"],"summary":"The lenders that hold liens on the organization's vehicles, with their payoff details","description":"Settings › Lenders: each lender with its contact and payoff details (account and routing numbers included), active first. Needs `banking:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"list_lenders","x-cypress-action":"lenders.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Organization and settings: the app's actions"],"summary":"Add a lender and where its payoffs go","description":"Settings › Lenders' Add. Payoff details direct money at a closing, so this is a person's act (an app acting for them): an API key and an agent are refused. Needs `banking:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `BANKING.UPDATED`. Since 1.5.0.","operationId":"create_lender","x-cypress-action":"lenders.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"lenderType":{"type":"string","enum":["BANK","CREDIT_UNION","FINANCE_CO","OTHER"],"description":"BANK when left out"},"contactName":{"type":["string","null"],"maxLength":120},"contactEmail":{"type":["string","null"],"maxLength":200,"format":"email"},"contactPhone":{"type":["string","null"],"maxLength":30},"address":{"type":["string","null"],"maxLength":200},"city":{"type":["string","null"],"maxLength":80},"state":{"type":["string","null"],"maxLength":80},"zip":{"type":["string","null"],"maxLength":20},"country":{"type":"string","maxLength":2,"description":"ISO country code (US when left out)"},"bankName":{"type":["string","null"],"maxLength":120},"routingNumber":{"type":["string","null"],"maxLength":9,"pattern":"^\\d{0,9}$","description":"ABA routing number, up to 9 digits"},"accountNumber":{"type":["string","null"],"maxLength":20},"accountType":{"type":["string","null"],"enum":["CHECKING","SAVINGS"]},"payoffPhone":{"type":["string","null"],"maxLength":30},"payoffEmail":{"type":["string","null"],"maxLength":200,"format":"email"},"payoffAddress":{"type":["string","null"],"maxLength":200},"notes":{"type":["string","null"],"maxLength":1000},"isActive":{"type":"boolean"}},"required":["name"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/lenders/{id}":{"patch":{"tags":["Organization and settings: the app's actions"],"summary":"Change a lender's contact or payoff details (only the fields sent)","description":"Settings › Lenders' Edit. A person's act, as create_lender. Needs `banking:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `BANKING.UPDATED`. Since 1.5.0.","operationId":"update_lender","x-cypress-action":"lenders.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"lenderType":{"type":"string","enum":["BANK","CREDIT_UNION","FINANCE_CO","OTHER"]},"contactName":{"type":["string","null"],"maxLength":120},"contactEmail":{"type":["string","null"],"maxLength":200,"format":"email"},"contactPhone":{"type":["string","null"],"maxLength":30},"address":{"type":["string","null"],"maxLength":200},"city":{"type":["string","null"],"maxLength":80},"state":{"type":["string","null"],"maxLength":80},"zip":{"type":["string","null"],"maxLength":20},"country":{"type":"string","maxLength":2,"description":"ISO country code (US when left out)"},"bankName":{"type":["string","null"],"maxLength":120},"routingNumber":{"type":["string","null"],"maxLength":9,"pattern":"^\\d{0,9}$","description":"ABA routing number, up to 9 digits"},"accountNumber":{"type":["string","null"],"maxLength":20},"accountType":{"type":["string","null"],"enum":["CHECKING","SAVINGS"]},"payoffPhone":{"type":["string","null"],"maxLength":30},"payoffEmail":{"type":["string","null"],"maxLength":200,"format":"email"},"payoffAddress":{"type":["string","null"],"maxLength":200},"notes":{"type":["string","null"],"maxLength":1000},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Organization and settings: the app's actions"],"summary":"Archive a lender (kept for history; update_lender with isActive brings it back)","description":"Settings › Lenders' Remove: the lender is archived, never deleted. Needs `banking:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `BANKING.UPDATED`. Since 1.5.0.","operationId":"archive_lender","x-cypress-action":"lenders.archive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/bank-accounts":{"get":{"tags":["Organization and settings: the app's actions"],"summary":"The accounts buyers and Cypress pay the organization into, with their numbers","description":"Settings › Bank accounts: each account with its bank, routing and account numbers, SWIFT, check and remittance instructions, active first. Needs `banking:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"list_bank_accounts","x-cypress-action":"bank_accounts.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Organization and settings: the app's actions"],"summary":"Add an account the organization is paid into","description":"Settings › Bank accounts' Add. Where buyers send money: a person's act (an app acting for them); an API key and an agent are refused. Needs `banking:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `BANKING.UPDATED`. Since 1.5.0.","operationId":"create_bank_account","x-cypress-action":"bank_accounts.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accountLabel":{"type":"string","minLength":1,"maxLength":120,"description":"Your name for it"},"bankName":{"type":["string","null"],"maxLength":120},"routingNumber":{"type":["string","null"],"maxLength":9,"pattern":"^\\d{0,9}$","description":"ABA routing number, up to 9 digits"},"accountNumber":{"type":["string","null"],"maxLength":20},"accountType":{"type":["string","null"],"enum":["CHECKING","SAVINGS"]},"swiftBic":{"type":["string","null"],"maxLength":20},"bankReferenceAddress":{"type":["string","null"],"maxLength":500},"checkInstructions":{"type":["string","null"],"maxLength":2000},"remittanceRequirements":{"type":["string","null"],"maxLength":1000},"contactName":{"type":["string","null"],"maxLength":120},"contactEmail":{"type":["string","null"],"maxLength":200,"format":"email"},"contactPhone":{"type":["string","null"],"maxLength":30},"notes":{"type":["string","null"],"maxLength":1000},"isActive":{"type":"boolean"}},"required":["accountLabel"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/bank-accounts/{id}":{"patch":{"tags":["Organization and settings: the app's actions"],"summary":"Change a bank account's details (only the fields sent)","description":"Settings › Bank accounts' Edit. A person's act, as create_bank_account. Needs `banking:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `BANKING.UPDATED`. Since 1.5.0.","operationId":"update_bank_account","x-cypress-action":"bank_accounts.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"accountLabel":{"type":"string","minLength":1,"maxLength":120},"bankName":{"type":["string","null"],"maxLength":120},"routingNumber":{"type":["string","null"],"maxLength":9,"pattern":"^\\d{0,9}$","description":"ABA routing number, up to 9 digits"},"accountNumber":{"type":["string","null"],"maxLength":20},"accountType":{"type":["string","null"],"enum":["CHECKING","SAVINGS"]},"swiftBic":{"type":["string","null"],"maxLength":20},"bankReferenceAddress":{"type":["string","null"],"maxLength":500},"checkInstructions":{"type":["string","null"],"maxLength":2000},"remittanceRequirements":{"type":["string","null"],"maxLength":1000},"contactName":{"type":["string","null"],"maxLength":120},"contactEmail":{"type":["string","null"],"maxLength":200,"format":"email"},"contactPhone":{"type":["string","null"],"maxLength":30},"notes":{"type":["string","null"],"maxLength":1000},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Organization and settings: the app's actions"],"summary":"Archive a bank account (kept for history; update_bank_account with isActive brings it back)","description":"Settings › Bank accounts' Remove: the account is archived, never deleted. Needs `banking:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `BANKING.UPDATED`. Since 1.5.0.","operationId":"archive_bank_account","x-cypress-action":"bank_accounts.archive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/transporters":{"get":{"tags":["Organization and settings: the app's actions"],"summary":"The haulers a closing sheet picks from","description":"Settings › Title & transport: the organization's saved haulers (active ones), which a closing's transport step picks from. Needs `organization:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_transporters","x-cypress-action":"transporters.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Organization and settings: the app's actions"],"summary":"Save a hauler for later closings","description":"Settings › Title & transport's Add hauler: a transport company your closings can name for a pickup, with its contact. Answers the hauler. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"create_transporter","x-cypress-action":"transporters.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"companyName":{"type":["string","null"],"maxLength":200},"phone":{"type":["string","null"],"maxLength":40},"email":{"type":["string","null"],"maxLength":200,"format":"email"}},"required":["name"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/transporters/{id}":{"patch":{"tags":["Organization and settings: the app's actions"],"summary":"Change a saved hauler (closings that already copied it keep their copy)","description":"Settings › Title & transport's Edit hauler: changes a transport company's name or contact; only the fields sent change. Answers the hauler. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"update_transporter","x-cypress-action":"transporters.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"companyName":{"type":["string","null"],"maxLength":200},"phone":{"type":["string","null"],"maxLength":40},"email":{"type":["string","null"],"maxLength":200,"format":"email"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Organization and settings: the app's actions"],"summary":"Archive a saved hauler (never deleted)","description":"Settings › Title & transport's Remove hauler. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"archive_transporter","x-cypress-action":"transporters.archive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/title-addresses":{"get":{"tags":["Organization and settings: the app's actions"],"summary":"The addresses a closing sheet mails titles to","description":"Settings › Title & transport: the organization's saved title-mailing addresses (active ones). Needs `organization:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_title_addresses","x-cypress-action":"title_addresses.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Organization and settings: the app's actions"],"summary":"Save where titles are mailed","description":"Settings › Title & transport's Add address: where titles are mailed for your closings, with its name and full address. Answers the address. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"create_title_address","x-cypress-action":"title_addresses.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"name":{"type":"string","minLength":1,"maxLength":200,"description":"Who receives the title"},"address":{"type":["string","null"],"maxLength":200},"city":{"type":["string","null"],"maxLength":120},"state":{"type":["string","null"],"maxLength":40},"zip":{"type":["string","null"],"maxLength":20}},"required":["label","name"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/title-addresses/{id}":{"patch":{"tags":["Organization and settings: the app's actions"],"summary":"Change a saved address (closings that already copied it keep their copy)","description":"Settings › Title & transport's Edit address: changes a title mailing address; only the fields sent change. Answers the address. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"update_title_address","x-cypress-action":"title_addresses.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"name":{"type":"string","minLength":1,"maxLength":200},"address":{"type":["string","null"],"maxLength":200},"city":{"type":["string","null"],"maxLength":120},"state":{"type":["string","null"],"maxLength":40},"zip":{"type":["string","null"],"maxLength":20}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Organization and settings: the app's actions"],"summary":"Archive a saved address (never deleted)","description":"Settings › Title & transport's Remove address. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"archive_title_address","x-cypress-action":"title_addresses.archive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/custom-fields":{"get":{"tags":["Organization and settings: the app's actions"],"summary":"The fields your document templates bind as `custom.seller.<key>` or `custom.buyer.<key>`","description":"The document designer's custom fields: each with its key, label, type, side (SELLER or BUYER), default and when it is required. Needs `organization:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_custom_fields","x-cypress-action":"custom_fields.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Organization and settings: the app's actions"],"summary":"Add a field your document templates can bind (its key never changes)","description":"The document designer's New field. The key is permanent: templates reference it. Re-adding an archived key brings it back with the new details. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"create_custom_field","x-cypress-action":"custom_fields.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":60,"pattern":"^[a-zA-Z][a-zA-Z0-9_]*$"},"label":{"type":"string","minLength":1,"maxLength":120},"type":{"type":"string","enum":["TEXT","NUMBER","CURRENCY","DATE"],"description":"TEXT when left out"},"scope":{"type":"string","enum":["SELLER","BUYER"],"description":"Whose side of the sheet it is on"},"defaultValue":{"type":["string","null"],"maxLength":4000},"requiredAt":{"type":["string","null"],"maxLength":40,"description":"The closing step it is required by"},"sortOrder":{"type":"integer","minimum":0,"maximum":9999}},"required":["key","label","scope"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/custom-fields/{id}":{"patch":{"tags":["Organization and settings: the app's actions"],"summary":"Change a custom field's label, default, requirement or order (never its key)","description":"The document designer's Edit field: changes a custom field's label, type or options, as your document templates fill it; only the fields sent change. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"update_custom_field","x-cypress-action":"custom_fields.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"defaultValue":{"type":["string","null"],"maxLength":4000},"requiredAt":{"type":["string","null"],"maxLength":40},"sortOrder":{"type":"integer","minimum":0,"maximum":9999}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Organization and settings: the app's actions"],"summary":"Archive a custom field (sheets that carry it keep their values)","description":"The document designer's Remove field: archived, never deleted; create_custom_field with the same key brings it back. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"archive_custom_field","x-cypress-action":"custom_fields.archive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/documents":{"get":{"tags":["Organization and settings: the app's actions"],"summary":"The W-9, dealer licenses and other documents, every card with its history and review","description":"Settings › Documents: each document card (W-9, dealer license, other) with every version, Cypress's review (status, reason) and a link valid for an hour. Needs `organization:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"list_org_documents","x-cypress-action":"org_documents.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Organization and settings: the app's actions"],"summary":"Upload a W-9, a dealer license or another document (a new card, or a new version of one)","description":"Settings › Documents' Upload: PDF, JPEG, PNG or WEBP up to 20 MB. `slotId` replaces that card's document (Cypress reviews it again); without it a new card opens. A W-9 is an attestation: a person's act. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"upload_org_document","x-cypress-action":"org_documents.upload","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentType":{"type":"string","enum":["W9","DEALER_LICENSE","OTHER"]},"slotId":{"type":"string","minLength":1,"maxLength":64,"description":"The card to replace (list_org_documents); a new card when left out"},"contentBase64":{"type":"string","minLength":4,"maxLength":28000000,"description":"The file, base64 (at most 20 MB)"},"contentType":{"type":"string","enum":["application/pdf","image/jpeg","image/png","image/webp"]},"fileName":{"type":"string","maxLength":200}},"required":["documentType","contentBase64","contentType"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/organization/documents/slots/{slotId}":{"delete":{"tags":["Organization and settings: the app's actions"],"summary":"Remove one of the organization's document cards (an admin's; a W-9 is replaced, never removed)","description":"Settings › Documents' Remove, e.g. the license of a state the dealer left. Its history is kept (SUPERSEDED). Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"remove_org_document","x-cypress-action":"org_documents.remove","parameters":[{"name":"slotId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/seller-terms":{"get":{"tags":["Organization and settings: the app's actions"],"summary":"The organization's seller terms: every version, and which is in force","description":"Settings › Seller terms: the terms buyers see on your vehicles, each version with who wrote it, and whether they are active. Needs `organization:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_seller_terms","x-cypress-action":"seller_terms.get","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Organization and settings: the app's actions"],"summary":"Save new seller terms (a new version) and switch them on or off","description":"Settings › Seller terms' Save, an admin's: a changed text is a new version; `active` puts the terms in force for buyers or takes them out. Terms are a legal text buyers act on: a person's act. Needs `organization:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"set_seller_terms","x-cypress-action":"seller_terms.set","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"body":{"type":"string","maxLength":4000},"active":{"type":"boolean"}},"required":["title","body","active"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/labels":{"get":{"tags":["Vehicles: the app's actions"],"summary":"Your organization's labels and Cypress's global ones","description":"Settings › Labels: every label a vehicle can carry, yours (ORG) and Cypress's (GLOBAL), with its category and color. The ids add_vehicle_labels and edit_labels_on_vehicles take. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_labels","x-cypress-action":"labels.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Vehicles: the app's actions"],"summary":"Create one of your organization's labels","description":"Settings › Labels' New label. Answers the label; put it on vehicles with add_vehicle_labels. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"create_label","x-cypress-action":"labels.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"slug":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9-]+$","description":"lowercase-with-dashes"},"category":{"type":"string","enum":["CATEGORY","BRAND","VEHICLE_TYPE","MILEAGE","AGE","CONDITION","LOCATION","CUSTOM"]},"color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"#RRGGBB"}},"required":["name","slug","category"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pricing-rules":{"get":{"tags":["Vehicles: the app's actions"],"summary":"Your organization's pricing rules and Cypress's global ones, in the order they are tried","description":"Settings › Pricing rules: each rule's conditions, outcome (approve and list, reject, manual review), how it applies and its thresholds. apply_pricing_rule shows which one a vehicle meets. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_pricing_rules","x-cypress-action":"pricing_rules.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Vehicles: the app's actions"],"summary":"A rule that approves and lists, rejects, or sends to review the vehicles it matches","description":"Settings › Pricing rules' New rule. It decides what reaches the market and the offer thresholds against the floor, so it is a person's act. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"create_pricing_rule","x-cypress-action":"pricing_rules.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000},"conditions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["LABEL","MAKE","VEHICLE_TYPE","MILEAGE","YEAR","CONDITION_SCORE","LOCATION","FLOOR_VS_VALUATION","TIME_IN_STATUS"]},"operator":{"type":"string","enum":["EQ","NOT_EQ","IN","NOT_IN","GT","GTE","LT","LTE","BETWEEN"]},"value":{"description":"A value, a list (IN, NOT_IN) or [low, high] (BETWEEN)"},"logicGroup":{"type":"string","maxLength":40}},"required":["type","operator","value"]},"minItems":1,"maxItems":20},"matchAll":{"type":"boolean","description":"Every condition (true, the default) or any"},"outcome":{"type":"string","enum":["APPROVE_AND_LIST","AUTO_REJECT","REQUIRE_MANUAL_REVIEW"]},"applyBehavior":{"type":"string","enum":["AUTO","NOTIFY_CM"],"description":"NOTIFY_CM when left out"},"rejectionReason":{"type":"string","maxLength":2000},"targetMarkupPct":{"type":"number","minimum":0,"maximum":200},"acceptBelowTargetPct":{"type":"number","minimum":0,"maximum":100},"denyAboveFloorPct":{"type":"number","minimum":0,"maximum":100},"priority":{"type":"integer"},"isActive":{"type":"boolean"}},"required":["name","conditions","outcome"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pricing-rules/{id}":{"patch":{"tags":["Vehicles: the app's actions"],"summary":"Change one of your organization's pricing rules: switch it on or off, how it applies, its conditions and figures","description":"Settings › Pricing rules' edit, an admin's or a fleet manager's: changes the fields sent on one of your organization's own rules (Cypress's global rules are not yours to change: 404). null clears a text or a figure. `isActive` false stops the rule without losing it; `applyBehavior` AUTO applies its outcome at once, NOTIFY_CM suggests it to Cypress. Vehicles it already priced keep their prices. Answers the rule and `changedFields`; a dry run answers the rule as it would be. A rule decides what reaches the market, so it is a person's act. Since 1.9.0. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Emits `ORGANIZATION.UPDATED`. Since 1.9.0.","operationId":"update_pricing_rule","x-cypress-action":"pricing_rules.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":["string","null"],"maxLength":2000},"conditions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["LABEL","MAKE","VEHICLE_TYPE","MILEAGE","YEAR","CONDITION_SCORE","LOCATION","FLOOR_VS_VALUATION","TIME_IN_STATUS"]},"operator":{"type":"string","enum":["EQ","NOT_EQ","IN","NOT_IN","GT","GTE","LT","LTE","BETWEEN"]},"value":{"description":"A value, a list (IN, NOT_IN) or [low, high] (BETWEEN)"},"logicGroup":{"type":"string","maxLength":40}},"required":["type","operator","value"]},"minItems":1,"maxItems":20,"description":"Replaces every condition"},"matchAll":{"type":"boolean","description":"Every condition (true) or any"},"outcome":{"type":"string","enum":["APPROVE_AND_LIST","AUTO_REJECT","REQUIRE_MANUAL_REVIEW"]},"applyBehavior":{"type":"string","enum":["AUTO","NOTIFY_CM"]},"rejectionReason":{"type":["string","null"],"maxLength":2000},"targetMarkupPct":{"type":["number","null"],"minimum":0,"maximum":200,"description":"The target price as % over the floor"},"acceptBelowTargetPct":{"type":["number","null"],"minimum":0,"maximum":100},"denyAboveFloorPct":{"type":["number","null"],"minimum":0,"maximum":100},"priority":{"type":"integer"},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/imports":{"post":{"tags":["Vehicles: the app's actions"],"summary":"The Import screen: create new VINs, update existing ones, stage archives (dry run first)","description":"The Import screen, row by row (a location name or one of a location's aliases puts the car at that saved location, since 1.9.0): a new VIN is created (decoded, valued), an existing one updated (a live vehicle's floor or location staged for Cypress), a `disposition` of SOLD_ELSEWHERE or ARCHIVE archived when the import runs (staged for Cypress to review when the vehicle has an open offer or a sale in progress). Run it with ?dryRun=true first: it answers what each row would do, the vehicles the file leaves out and the live deals an archive would touch. A real run answers the batch; get_import follows it. Each created vehicle is announced as VEHICLES.CREATED (source \"csv\"). Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Since 1.5.0.","operationId":"import_vehicles","x-cypress-action":"vehicles.import","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vehicles":{"type":"array","items":{"type":"object","properties":{"vin":{"type":"string","minLength":1,"maxLength":40,"description":"The VIN; an existing VIN updates that vehicle, a new one creates it"},"year":{"type":"integer"},"make":{"type":"string","maxLength":80},"model":{"type":"string","maxLength":120},"trim":{"type":"string","maxLength":120},"mileage":{"anyOf":[{"type":"number"},{"type":"string"}],"description":"Whole miles"},"conditionScore":{"type":"number","description":"1 (poor) to 5 (excellent)"},"condition":{"type":"string","maxLength":40,"description":"EXCELLENT, GOOD, FAIR, POOR, or 1 to 5"},"exteriorColor":{"type":"string","maxLength":60},"interiorColor":{"type":"string","maxLength":60},"purchasePrice":{"type":"number"},"purchaseDate":{"type":"string","maxLength":40,"description":"YYYY-MM-DD"},"acquisitionMethod":{"type":"string","maxLength":40,"description":"CASH, FINANCING, LEASE_BUYOUT, ESCROW or BALLOON"},"loanAmount":{"type":"number"},"monthlyPayment":{"type":"number"},"payoffDate":{"type":"string","maxLength":40,"description":"YYYY-MM-DD"},"remainingBalance":{"type":"number"},"downPayment":{"type":"number"},"interestRate":{"anyOf":[{"type":"number"},{"type":"string"}],"description":"Percent (6.5 or \"6.5%\")"},"loanTermMonths":{"anyOf":[{"type":"number"},{"type":"string"}]},"balloonAmount":{"type":"number"},"stockNumber":{"type":"string","maxLength":64},"locationCity":{"type":"string","maxLength":100},"locationState":{"type":"string","maxLength":100},"locationZip":{"type":"string","maxLength":20},"locationAddress":{"type":"string","maxLength":500},"locationName":{"type":"string","maxLength":200},"floorPrice":{"type":"number","description":"USD: the seller's floor (on a live vehicle the change is staged for Cypress)"},"previousRepairCost":{"type":"number"},"equipment":{"type":"string","maxLength":4000},"description":{"type":"string","maxLength":8000},"category":{"type":"string","enum":["PRIVATE","RENTAL","REPOSITION","FLEET","COMMERCIAL"]},"disposition":{"type":"string","maxLength":40,"description":"SOLD_ELSEWHERE or ARCHIVE on an existing vehicle: archived when the import runs, or staged for Cypress to review if it has an open offer or a sale in progress"},"thirdPartyReportUrl":{"type":"string","maxLength":2000,"description":"A third-party inspection report's link (a Manheim condition report): Cypress reads its grade, damages and photos; any other link is kept as a link only"}},"required":["vin"]},"minItems":1,"maxItems":5000,"description":"The rows, at most 5,000"},"fleetId":{"type":"string","minLength":1,"maxLength":64,"description":"Put the new vehicles in this fleet (list_fleets)"},"fleetName":{"type":"string","maxLength":120,"description":"Or in a new fleet of this name"},"archiveMissingVins":{"type":"array","items":{"type":"string","maxLength":17},"maxItems":5000,"description":"Vehicles the file leaves out to stage for archive (the dry run lists them)"},"applyModelTrimSplit":{"type":"boolean","description":"Lift trim text out of the model column (true when left out)"},"planningOnly":{"type":"boolean","description":"Planning import: the vehicles land on the plan's bench, not in Sell intake (needs Planning)"},"mode":{"type":"string","enum":["run","stage"],"description":"stage (since 1.9.0): hold the import for review instead of running it. Answers the staged batch (`id`, `totalRows`, `exceptionRows`); get_import reads its rows with their exceptions, decide_import_row settles each, apply_import runs it. run (the default) runs it now"}},"required":["vehicles"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"202":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Vehicles: the app's actions"],"summary":"The organization's recent import batches with their progress","description":"The Fleet page's import banner: the latest batches (5 by default, at most 20) with how many vehicles were created, failed, valued or skipped. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"list_imports","x-cypress-action":"imports.list","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20}},{"name":"fleetId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/imports/read":{"post":{"tags":["Vehicles: the app's actions"],"summary":"A CSV or Excel file read as the Import screen reads it: its columns matched and each row in the import's shape (nothing is saved)","description":"Send the file (`fileName` ending .csv, .tsv, .txt, .xlsx, .xlsm, .xls or .ods, and `content` in base64, about 6 MB at most). Columns are matched by the Import screen's own rules (the header, then the values). Answers each column's field (`columns`: `high` confidence when sure, `medium` for a guess, its `source` and a `sample` value, `kilometres` when its miles were converted), the headers left out (`ignored`), the fields a column can be (`fields`), the useful ones no column fills (`missing`: VIN, Mileage, Floor Price, Location), and the rows (`rows`, at most 5,000) in import_vehicles' shape: VINs cleaned, kilometres in miles, money and dates read the US way. Rows with no VIN are left out (`noVin`). When a match is wrong, send `mapping` (a field or null for each column, in the file's order) and read again. A file with no VIN column answers no rows and `missing: [\"VIN\"]`: say which column it is with `mapping`. Saves nothing: check the rows with import_vehicles and dryRun, then run or stage them. Since 1.9.0. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"read_import_file","x-cypress-action":"imports.read","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","maxLength":200,"description":"The file's name, with its extension"},"content":{"type":"string","maxLength":8000000,"description":"The file, base64"},"mapping":{"type":"array","items":{"type":["string","null"]},"maxItems":500,"description":"What each column is, in the file's order: one of `fields`, or null for not imported"}},"required":["fileName","content"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/imports/{batchId}":{"get":{"tags":["Vehicles: the app's actions"],"summary":"One import batch: its progress and every row's result","description":"One batch with its status (IMPORTING, VALUATING, COMPLETE), a progress percentage, and each VIN's import and valuation result with the vehicle it became. Since 1.9.0 a staged import (import_vehicles with mode stage) is read here too (`kind: \"STAGED\"`, status STAGED, APPLIED or DISCARDED): every row with what the dry run said of it, its `exceptions` (DUPLICATE_VIN, MILEAGE_DROP for an odometer 10 times lower than the car's, UNKNOWN_LOCATION, ALREADY_SOLD, ARCHIVE_LIVE_DEAL, and MISSING_LIVE_DEAL for a car the file leaves out while a buyer is involved), its decision and whether it is `settled`; `unsettledRows` counts what still needs a person, and `importBatchIds` the batches its apply started. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_import","x-cypress-action":"imports.get","parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/imports/{batchId}/rows/{rowId}":{"patch":{"tags":["Vehicles: the app's actions"],"summary":"Keep or skip a row of a staged import, map its location, or fix its odometer","description":"A person's decision on one row of a staged import (get_import lists the rows, `id`): `decision` KEEP (do what the row proposes, its exception accepted) or SKIP (leave it out), null to take it back; `locationId`, the saved location an unknown location name stands for (list_locations), with `rememberAlias: true` to save that name as the location's alias for the next file; `mileage`, a corrected odometer. A mapping settles UNKNOWN_LOCATION and a fix settles MILEAGE_DROP. A car the file leaves out takes a decision only: KEEP archives it if the import asked for it, SKIP leaves it. Only while the import is STAGED (409 after). Answers the row. Since 1.9.0. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"decide_import_row","x-cypress-action":"imports.rows.decide","parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"rowId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":["string","null"],"enum":["KEEP","SKIP"]},"locationId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"The saved location the row's location name stands for"},"rememberAlias":{"type":"boolean","description":"With locationId: also save the row's location name as that location's alias"},"mileage":{"type":["integer","null"],"minimum":0,"maximum":2000000,"description":"A corrected odometer"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/imports/{batchId}/apply":{"post":{"tags":["Vehicles: the app's actions"],"summary":"Run a staged import with its rows as decided","description":"Runs a staged import as the Import screen's import does, with the rows as decided: skipped rows are left out, a mapped location and a fixed odometer replace the file's, a left-out car is archived only if the import asked for it and its row was not skipped. Every row with an exception must be settled first (409 CONFLICT lists the rows), and two kept rows may not share a VIN. A dry run answers the import's own dry run of those rows and changes nothing. Answers the batches it started (`importBatchIds`; get_import follows each); told as VEHICLES.IMPORT.APPLIED. A person's act, as an import is. Since 1.9.0. Needs `vehicles`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Emits `VEHICLES.IMPORT.APPLIED`. Since 1.9.0.","operationId":"apply_import","x-cypress-action":"imports.apply","parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"202":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/appraisals":{"post":{"tags":["Vehicles: the app's actions"],"summary":"What a VIN is worth now, a suggested floor and target, and a sell-or-hold read (nothing is saved)","description":"Quick Appraisal: decodes the VIN, values it (wholesale, retail, trade-in, confidence), suggests a floor and a target, and when the specs allow it Cedar's sell-or-hold read. Saves nothing; to add the vehicle use create_vehicle. Each call values the VIN afresh. Needs `insights:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"appraise_vin","x-cypress-action":"vehicles.appraise","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vin":{"type":"string","minLength":17,"maxLength":17},"mileage":{"type":["integer","null"],"minimum":0},"conditionScore":{"type":["number","null"],"minimum":1,"maximum":5,"description":"1 (poor) to 5 (excellent)"},"locationState":{"type":["string","null"],"maxLength":2},"zip":{"type":["string","null"],"maxLength":10}},"required":["vin"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/valuations/estimate":{"post":{"tags":["Vehicles: the app's actions"],"summary":"What a car is worth to a dealer, how sure that is and what would make it surer, from a VIN or a year, make and model (nothing is saved)","description":"Values a car the way Cedar does, trying each source only when every one before it had nothing: Black Book looked up now (with a VIN, while the account has a valuation to spend; an individual's count, Cypress staff spend none), then Black Book's earlier values of this VIN or of similar cars on Cypress, then what similar cars sold for on Cypress, then a model's rough estimate; every other source that agrees with the value (`supportedBy`) makes it one level surer. Someone else's car is answered as a range, never its own figure. Answers the value (what a dealer would pay: low, middle and high, and retail when known), its source, its confidence (HIGH, GOOD, FAIR or ROUGH: the lower of what was given and the source, from Cypress's confidence table) with why, the better valuation to ask for, whether Black Book was looked up (and why not), and what similar cars sold for and are listed at on Cypress; and `curve`, the value over the next twelve months on Cypress's own depreciation curve for its class (car, SUV, truck, van), with what a month and the year of waiting cost (null without a value or a model year; since 1.10.0). Give the VIN, or the year, make and model (422 otherwise). Saves nothing; appraise_vin is the VIN-only Quick Appraisal. Since 1.9.0. Needs `insights:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"estimate_value","x-cypress-action":"vehicles.estimate","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"vin":{"type":["string","null"],"maxLength":20},"year":{"type":["integer","null"],"minimum":1981},"make":{"type":["string","null"],"maxLength":40},"model":{"type":["string","null"],"maxLength":60},"trim":{"type":["string","null"],"maxLength":60},"mileage":{"type":["integer","null"],"minimum":0,"description":"Miles on the odometer"},"condition":{"type":["string","null"],"enum":["EXCELLENT","GOOD","FAIR","POOR"]},"state":{"type":["string","null"],"minLength":2,"maxLength":2,"description":"Two-letter US state where the car is"},"zip":{"type":["string","null"],"maxLength":10},"lookUp":{"type":"boolean","description":"false: never look Black Book up now, only read what is known (no valuation spent)"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/invoices":{"get":{"tags":["Billing: the app's actions"],"summary":"The organization's commission invoices, newest first, with what was paid, credited and owed","description":"The Billing page's invoices: each with its number, status, amount, credits, payments (card, ACH or recorded by hand), credit notes and the vehicle sold. Paying is a person's, in the app. Needs `billing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"list_invoices","x-cypress-action":"billing.invoices.list","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"Comma-separated: PENDING, INVOICED, PAID, EXPIRED, ESCALATED, SETTLED, VOIDED (all when left out)"},"description":"Comma-separated: PENDING, INVOICED, PAID, EXPIRED, ESCALATED, SETTLED, VOIDED (all when left out)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The last invoice id of the previous page"},"description":"The last invoice id of the previous page"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many (50 when left out)"},"description":"At most this many (50 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/summary":{"get":{"tags":["Billing: the app's actions"],"summary":"Auto-pay on file, the ACH credit line and its use, the cycle, deferred and failed batches","description":"The top of the Billing page: how commissions are paid (ACH, card or neither), the credit limit and how much of it is used, days left in the cycle, deferred invoices, an ACH batch in flight or one that failed. Needs `billing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"get_billing_summary","x-cypress-action":"billing.summary","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/invoice-settings":{"get":{"tags":["Billing: the app's actions"],"summary":"The parts each commission invoice line prints, whether Deal Setup needs a PO, how a close splits into invoices, and a preview line","description":"Billing › Billing details › Invoice content: how each close splits your open commissions into invoices (on ACH or bank transfer), the parts each line prints in order, whether it is the house default, whether your side of Deal Setup needs a PO number before it can be confirmed, and the line as it would print for your latest sale. Set by Cypress; ask your account manager to change it. Needs `billing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.7.0.","operationId":"get_invoice_settings","x-cypress-action":"billing.invoice_settings.get","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/credit-ledger":{"get":{"tags":["Billing: the app's actions"],"summary":"Every movement of the organization's account credit, newest first (up to 200)","description":"The Billing page's Credits: each grant, withdrawal, credit carried forward from a credit note and credit spent on an invoice, with the balance after it and who made it. Needs `billing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"list_credit_movements","x-cypress-action":"billing.credit_ledger.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/credit-notes":{"get":{"tags":["Billing: the app's actions"],"summary":"The credit notes issued against your invoices, newest first (up to 100)","description":"Each credit note with its number, invoice, amount, how it was settled (credited forward, refunded) and its document. Needs `billing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"list_credit_notes","x-cypress-action":"billing.credit_notes.list","parameters":[{"name":"invoiceId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Only this invoice's"},"description":"Only this invoice's"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/bank-transfers":{"get":{"tags":["Billing: the app's actions"],"summary":"Money the organization sent by bank transfer that Cypress holds unapplied, with the open invoices it could pay","description":"For an organization paying by bank transfer: each transfer Cypress received and has not applied to an invoice (Cypress applies only whole invoices), with what arrived, what is still held, the memo, when it arrived, `kind` (SHORT: it does not cover the invoice it names or the oldest open one; OVER: more than that invoice; UNMATCHED: nothing is open), when Stripe sends it back, and the open invoices it could pay with their amounts (the one its memo names first). `status=short` keeps the SHORT ones. Read from Cypress's receipt log; the live balance is on the organization's Billing tab. Applying or recording the payment stays a person's at Cypress, in the app: `links.app` opens that screen. For the organization's admins and billing admins, and Cypress staff for the organization (a CM token or a first-party app acting for staff). Needs `billing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an API key (a person's act). Since 1.9.0.","operationId":"list_unapplied_bank_transfers","x-cypress-action":"billing.bank_transfers.list","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["unapplied","short"],"description":"unapplied (every one, the default) or short"},"description":"unapplied (every one, the default) or short"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/invoices/{id}/credit-offer":{"get":{"tags":["Billing: the app's actions"],"summary":"What an invoice still owes and how much of your account credit could settle it","description":"The two numbers the app reads before taking money: the outstanding amount and the credit that applies. Applying it is a person's, in the app. Needs `billing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"get_invoice_credit_offer","x-cypress-action":"billing.invoices.credit_offer","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/companies":{"get":{"tags":["Analytics: the app's actions"],"summary":"Your sales and purchases by company: units, money, prices against the floor","description":"Performance: every company you traded with, both directions, with units, money, average price and how prices sat against the floor. You see your own trades only. Needs `analytics:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_trading_book","x-cypress-action":"analytics.trading_book","parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["30d","90d","ytd","all"],"description":"30d, 90d, ytd or all (all when left out)"},"description":"30d, 90d, ytd or all (all when left out)"},{"name":"stage","in":"query","required":false,"schema":{"type":"string","enum":["recorded","offer-accepted","dd-complete"],"description":"When a sale counts: recorded, offer-accepted or dd-complete (dd-complete when left out)"},"description":"When a sale counts: recorded, offer-accepted or dd-complete (dd-complete when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/companies/{orgId}":{"get":{"tags":["Analytics: the app's actions"],"summary":"Your organization's performance report, as seller or as buyer","description":"The company performance report: KPIs, trend, counterparties and vehicles for the period. As buyer, figures derived from other sellers' floors are left out. Needs `analytics:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_company_report","x-cypress-action":"analytics.company_report","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Your organization's id (Cypress staff: any)"}},{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["seller","buyer"],"description":"seller (the default) or buyer"},"description":"seller (the default) or buyer"},{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["30d","90d","ytd","all"],"description":"30d, 90d, ytd or all (all when left out)"},"description":"30d, 90d, ytd or all (all when left out)"},{"name":"stage","in":"query","required":false,"schema":{"type":"string","enum":["recorded","offer-accepted","dd-complete"],"description":"When a sale counts: recorded, offer-accepted or dd-complete (dd-complete when left out)"},"description":"When a sale counts: recorded, offer-accepted or dd-complete (dd-complete when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/companies/{orgId}/insight":{"get":{"tags":["Analytics: the app's actions"],"summary":"Sakura's one-paragraph read of the performance report, and what to do next","description":"The insight card of the performance report: a profile label, a paragraph and a recommendation, written once a day. Needs `analytics:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_company_insight","x-cypress-action":"analytics.company_insight","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["seller","buyer"],"description":"seller (the default) or buyer"},"description":"seller (the default) or buyer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/accounts/{orgId}":{"get":{"tags":["Analytics: the app's actions"],"summary":"What an account buys and sells: yours, or a buyer that bought from you","description":"The buyer profile card: what the account buys (makes, segments, prices) and sells. Your own organization, or an account that has bought from you; any other answers NOT_FOUND. Needs `analytics:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_account_profile","x-cypress-action":"analytics.account_profile","parameters":[{"name":"orgId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/engagement":{"get":{"tags":["Analytics: the app's actions"],"summary":"What your stock attracts (as seller) or what your people browse (as buyer)","description":"Analytics › Engagement: views, saves, returns and offers on your stock, or your people's browsing, by vehicle and over time. Needs `analytics:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_my_engagement","x-cypress-action":"analytics.engagement","parameters":[{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["seller","buyer"],"description":"seller or buyer (seller first when you sell)"},"description":"seller or buyer (seller first when you sell)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/profile-insight":{"get":{"tags":["Analytics: the app's actions"],"summary":"Sakura's read on your organization: the Today card","description":"The Today card: a profile label, a paragraph and a recommendation about your organization as seller or buyer, written once a day. Needs `analytics:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"get_my_profile_insight","x-cypress-action":"analytics.profile_insight","parameters":[{"name":"role","in":"query","required":false,"schema":{"type":"string","enum":["seller","buyer"]}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/vehicles/{id}/suggested-buyers":{"get":{"tags":["Analytics: the app's actions"],"summary":"The buyer companies whose buying history fits one of your vehicles","description":"A vehicle's Leads tab: up to 8 buyer companies ranked by how well their purchases fit it, with why. Your own vehicles only. Needs `analytics:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"suggest_vehicle_buyers","x-cypress-action":"vehicles.suggested_buyers","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The vehicle's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/promotions/{id}/suggested-audience":{"get":{"tags":["Analytics: the app's actions"],"summary":"The buyer companies a promotion's vehicles fit best: a starting audience a person edits","description":"A promotion's suggested audience: up to 25 accounts ranked by how much of its list fits them. A campaign's cherry-pick starts from it; it never sends itself. Your own promotions only. Needs `marketing:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Since 1.5.0.","operationId":"suggest_promotion_audience","x-cypress-action":"promotions.suggested_audience","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The promotion"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mission-control/interest":{"get":{"tags":["Mission Control: the app's actions"],"summary":"The buyers who saved, returned to or opened your vehicles and have no deal on them","description":"Behind Mission Control's interest rows (\"3 buyers saved vehicles you have no deal on\"): each buyer with their name and address, and the vehicle. open_deal_from_interest turns one into a deal. Needs `mission-control:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Since 1.5.0.","operationId":"list_interest","x-cypress-action":"mission_control.interest","parameters":[{"name":"signal","in":"query","required":true,"schema":{"type":"string","enum":["saved","returned","opened"]}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mission-control/interest/adopt":{"post":{"tags":["Mission Control: the app's actions"],"summary":"Turn a buyer's interest in one of your vehicles into a deal at INTERESTED","description":"Mission Control's Open deal on an interest row: the buyer enters your book and a deal opens at INTERESTED on the vehicle; an open deal for the same buyer and vehicle is answered instead. A save is not a commitment: a person says yes. Needs `crm:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"open_deal_from_interest","x-cypress-action":"mission_control.interest.adopt","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string","minLength":1,"maxLength":64,"description":"The buyer (list_interest)"},"vehicleId":{"type":"string","minLength":1,"maxLength":64}},"required":["userId","vehicleId"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me":{"patch":{"tags":["Members: the app's actions"],"summary":"Change the first name, last name or phone of the person the token acts for","description":"Profile's Save: only the person's own name and phone. An API key acts as no one, so it is refused. Needs `members:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"update_my_profile","x-cypress-action":"me.profile.update","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":50},"lastName":{"type":"string","maxLength":50},"phone":{"type":["string","null"],"maxLength":30}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/me/activity":{"get":{"tags":["Members: the app's actions"],"summary":"The audit trail of the person (or agent) the token acts for, newest first","description":"Profile › Activity: what this person, or this agent, did in Cypress, page by page. Needs `members:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). Since 1.5.0.","operationId":"list_my_activity","x-cypress-action":"me.activity","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"description":"20 when left out"},"description":"20 when left out"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations":{"get":{"tags":["Cypress staff: organizations"],"summary":"The business organizations on Cypress, newest first, with their onboarding and channels","description":"Every business organization (dealers, fleets, buyers; private individuals are list_private_customers), newest first: status, profiles, primary contact, the onboarding checklist's progress, the delegation switches and the opt-in sales channels in force. Filter by status (several, comma-separated) or a name. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_customer_organizations","x-cypress-action":"staff.organizations.list","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":100,"description":"Part of the name"},"description":"Part of the name"},{"name":"status","in":"query","required":false,"schema":{"type":"string","maxLength":200,"description":"ONBOARDING, PROVISIONAL, ACTIVE, REJECTED, BLOCKED, DEACTIVATED or SUSPENDED; several comma-separated"},"description":"ONBOARDING, PROVISIONAL, ACTIVE, REJECTED, BLOCKED, DEACTIVATED or SUSPENDED; several comma-separated"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page, from 1 (1 when left out)"},"description":"Page, from 1 (1 when left out)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many (25 when left out)"},"description":"At most this many (25 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Cypress staff: organizations"],"summary":"Create a business organization in onboarding, with its first admin","description":"Creates the organization (ONBOARDING: nobody can sign in yet) and its admin, and tells the admin by email that the account is being set up; the sign-in email goes out when the organization is approved (change_organization_status with activate). Enters it in Cypress's CRM book. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"create_customer_organization","x-cypress-action":"staff.organizations.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":100},"slug":{"type":"string","minLength":2,"maxLength":60,"pattern":"^[a-z0-9-]+$","description":"Lowercase letters, digits and hyphens; unique"},"profiles":{"type":"array","items":{"type":"string","enum":["SELLER","BUYER"]},"minItems":1,"default":["SELLER"]},"adminFirstName":{"type":"string","minLength":1,"maxLength":50},"adminLastName":{"type":"string","minLength":1,"maxLength":50},"adminEmail":{"type":"string","maxLength":200,"format":"email"},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"country":{"type":"string","maxLength":100}},"required":["name","slug","adminFirstName","adminLastName","adminEmail"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}":{"get":{"tags":["Cypress staff: organizations"],"summary":"One organization as BackOffice shows it: details, members, products, billing and ACH","description":"The organization's record: details, status and its history (activated, suspended, rejected, blocked), profiles, the delegation switches, the products switched on, the account manager, billing details, ACH and the commission card on file (bank and last four only), credit use, and its members with their roles and whether their sign-in is set up. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_customer_organization","x-cypress-action":"staff.organizations.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Cypress staff: organizations"],"summary":"Name, address, contact and the account manager","description":"The organization's details as BackOffice edits them: name, website, phone, address, primary contact and its account manager (a Cypress staff member; null clears it). Only the fields sent change. The delegation switches are the organization's own consent: an admin of the organization gives it in the app, never Cypress through a token. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"update_customer_organization","x-cypress-action":"staff.organizations.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"website":{"type":["string","null"],"maxLength":500},"phone":{"type":["string","null"],"maxLength":30},"address":{"type":["string","null"],"maxLength":200},"city":{"type":["string","null"],"maxLength":100},"state":{"type":["string","null"],"maxLength":100},"zip":{"type":["string","null"],"maxLength":20},"country":{"type":["string","null"],"maxLength":100},"primaryContactName":{"type":["string","null"],"maxLength":100},"primaryContactEmail":{"type":["string","null"],"maxLength":200,"format":"email"},"primaryContactPhone":{"type":["string","null"],"maxLength":30},"accountManagerId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"A Cypress staff member (list_cypress_staff); null clears it"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/transitions":{"post":{"tags":["Cypress staff: organizations"],"summary":"Activate, suspend, reactivate, reject, block or unblock an organization","description":"The status buttons of the organization page. activate: an onboarding organization gets limited access (PROVISIONAL; its admins are activated and emailed their sign-in), and a PROVISIONAL one is marked fully onboarded (ACTIVE) once its checklist is complete (refused with what is missing). suspend and reactivate; reject (a reason); block (a reason) and unblock (notes). A step not open from the current status is refused with the reason. A registration application is answered with approve_organization_application or reject_organization_application. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"change_organization_status","x-cypress-action":"staff.organizations.transition","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["activate","suspend","reactivate","reject","block","unblock"]},"reason":{"type":"string","maxLength":1000,"description":"Why: required with reject and block; optional with suspend (500 at most)"},"notes":{"type":"string","maxLength":500,"description":"With unblock"}},"required":["action"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/profiles":{"put":{"tags":["Cypress staff: organizations"],"summary":"Seller, buyer, or both","description":"Sets the organization's profiles: SELLER (lists vehicles), BUYER (makes offers), or both. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"set_organization_profiles","x-cypress-action":"staff.organizations.profiles.set","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profiles":{"type":"array","items":{"type":"string","enum":["SELLER","BUYER"]},"minItems":1}},"required":["profiles"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/products/{product}":{"get":{"tags":["Cypress staff: organizations"],"summary":"Whether a product is on, who asked for it, and what switching it off keeps","description":"For Planning, Buy planning or Automations: whether it is on and since when, who at the organization asked for it, and what it holds that switching off keeps (plans, windows and planning-only vehicles; targets and periods; the organization's automations). Read it before switch_organization_product. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_organization_product","x-cypress-action":"staff.organizations.products.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"product","in":"path","required":true,"schema":{"type":"string","enum":["planning","buy_planning","automations"],"description":"planning (Sell planning), buy_planning, or automations (the organization's own)"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Cypress staff: organizations"],"summary":"Planning, Buy planning or Automations: on or off for one organization","description":"Switches a product on or off for the organization. Off hides and freezes it and deletes nothing (Planning hands the fleet's advice back to Cedar). The organization's API and MCP access to the product follows at once. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"switch_organization_product","x-cypress-action":"staff.organizations.products.set","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"product","in":"path","required":true,"schema":{"type":"string","enum":["planning","buy_planning","automations"],"description":"planning (Sell planning), buy_planning, or automations (the organization's own)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/activity":{"get":{"tags":["Cypress staff: organizations"],"summary":"The organization's audit trail, newest first","description":"Who did what in the organization and when: its own changes, its members' and its vehicles' (mode org), sign-in and account changes (mode user), or everything (all, the default). Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_organization_activity","x-cypress-action":"staff.organizations.activity","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["all","org","user"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page, from 1 (1 when left out)"},"description":"Page, from 1 (1 when left out)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"description":"At most this many (20 when left out)"},"description":"At most this many (20 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/application/approve":{"post":{"tags":["Cypress staff: organizations"],"summary":"Approve an organization's registration: limited access, and its admin is emailed","description":"The Pending queue's Approve: the registration is approved and the organization gets limited access (PROVISIONAL: it can sign in and work, not list or make offers until it is fully onboarded). Its admin is activated and emailed a sign-in link; the applicant is linked to Cypress's CRM book. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"approve_organization_application","x-cypress-action":"staff.organizations.application.approve","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/application/reject":{"post":{"tags":["Cypress staff: organizations"],"summary":"Reject an organization's registration: its admin is suspended and the applicant told why","description":"The Pending queue's Reject: the registration and the organization are REJECTED with the reason, the admin's sign-in is suspended and the applicant is emailed the reason. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"reject_organization_application","x-cypress-action":"staff.organizations.application.reject","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":10,"maxLength":2000,"description":"Why (10 characters at least); the applicant reads it"}},"required":["reason"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/checklist":{"get":{"tags":["Cypress staff: organizations"],"summary":"The onboarding checklist: each item, its phase and whether it is done","description":"The checklist an organization completes before it is fully onboarded: each item with its phase, whether it is required, done by whom and when, and notes. change_organization_status with activate needs the full set done. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_onboarding_checklist","x-cypress-action":"staff.organizations.checklist.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Cypress staff: organizations"],"summary":"Tick or untick one item of the onboarding checklist","description":"Marks one checklist item (by its key, from get_onboarding_checklist) done or not done, with notes. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"mark_onboarding_checklist_item","x-cypress-action":"staff.organizations.checklist.mark","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"itemKey":{"type":"string","minLength":1,"maxLength":80},"completed":{"type":"boolean"},"notes":{"type":["string","null"],"maxLength":500}},"required":["itemKey","completed"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Cypress staff: organizations"],"summary":"A custom item on one organization's onboarding checklist","description":"Adds a custom item to the organization's checklist, required or not. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"add_onboarding_checklist_item","x-cypress-action":"staff.organizations.checklist.add","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":120},"required":{"type":"boolean","default":false}},"required":["label"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/documents":{"get":{"tags":["Cypress staff: organizations"],"summary":"Its onboarding documents (W-9, dealer license, others), with links","description":"The organization's documents, current first: type, status (pending, under review, approved, rejected, superseded), the review and the AI analysis, each with a link valid for an hour. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_organization_documents","x-cypress-action":"staff.organizations.documents.list","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Cypress staff: organizations"],"summary":"Upload a W-9, dealer license or other document on an organization's behalf","description":"Cypress uploads a document for the organization, as the Documents tab does; it lands PENDING. `slotId` names the card it replaces (of the same type); left out, it opens a new card, except a W-9, which always replaces the organization's one W-9. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"upload_organization_document","x-cypress-action":"staff.organizations.documents.upload","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"documentType":{"type":"string","enum":["W9","DEALER_LICENSE","OTHER"]},"slotId":{"type":"string","minLength":1,"maxLength":64},"contentBase64":{"type":"string","minLength":4,"maxLength":28000000,"description":"The document, base64 (at most 20 MB)"},"contentType":{"type":"string","pattern":"^(application\\/pdf|image\\/(jpeg|png|webp))$","description":"application/pdf, image/jpeg, image/png or image/webp"},"fileName":{"type":"string","maxLength":200}},"required":["documentType","contentBase64","contentType"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/documents/{docId}":{"get":{"tags":["Cypress staff: organizations"],"summary":"One document with its review, its AI analysis and a link","description":"One document of the organization: type, status, who reviewed it and why it was rejected, the AI analysis, and a link valid for an hour. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_organization_document","x-cypress-action":"staff.organizations.documents.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"docId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/documents/{docId}/analyze":{"post":{"tags":["Cypress staff: organizations"],"summary":"Sapele reads a document and says whether it is complete and valid","description":"Sapele (Cypress's document AI) reads the document and answers whether it looks valid, its findings field by field and a recommendation (approve, reject, ask for clarification); the analysis is kept on the document. It decides nothing: review_organization_document does. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"analyze_organization_document","x-cypress-action":"staff.organizations.documents.analyze","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"docId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/documents/{docId}/review":{"post":{"tags":["Cypress staff: organizations"],"summary":"Approve, reject (with a reason) or put under review one document","description":"Cypress's decision on one onboarding document: approve, reject with the reason the organization reads, or mark it under review. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"review_organization_document","x-cypress-action":"staff.organizations.documents.review","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"docId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["approve","reject","under_review"]},"reason":{"type":"string","minLength":1,"maxLength":500,"description":"Why, with reject (required there)"}},"required":["action"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/document-slots/{slotId}":{"delete":{"tags":["Cypress staff: organizations"],"summary":"Take a document card off an organization (a W-9 is replaced, never removed)","description":"Removes one document card from the organization's Documents tab; its document is kept as superseded. A W-9 card cannot be removed: upload a new one instead. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"remove_organization_document_slot","x-cypress-action":"staff.organizations.documents.remove_slot","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"slotId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/members":{"post":{"tags":["Cypress staff: organizations"],"summary":"Add a person to an organization with a role; they are emailed a sign-in link","description":"Adds a person (new, or already on Cypress) to the organization as an admin, Fleet Manager or billing admin, and emails them a link to set their password. Cypress may make admins; refused when they are already a member. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `MEMBER.UPDATED`. Since 1.5.0.","operationId":"invite_organization_member","x-cypress-action":"staff.organizations.members.invite","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":200,"format":"email"},"role":{"type":"string","enum":["ADMIN","FLEET_MANAGER","BILLING_ADMIN"]},"firstName":{"type":"string","minLength":1,"maxLength":50},"lastName":{"type":"string","minLength":1,"maxLength":50}},"required":["email","role"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/members/{userId}/role":{"put":{"tags":["Cypress staff: organizations"],"summary":"Make a member an admin, a Fleet Manager or a billing admin","description":"Changes one person's role in the organization. Refused for an agent user (its access is the connected app's) and for a private individual's single account. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `MEMBER.UPDATED`. Since 1.5.0.","operationId":"change_organization_member_role","x-cypress-action":"staff.organizations.members.change_role","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["ADMIN","FLEET_MANAGER","BILLING_ADMIN"]}},"required":["role"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/members/{userId}":{"patch":{"tags":["Cypress staff: organizations"],"summary":"A member's first name, last name and phone","description":"Corrects a member's name and phone as the member panel does; null clears one. Their sign-in email is not changed here. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `MEMBER.UPDATED`. Since 1.5.0.","operationId":"update_organization_member_profile","x-cypress-action":"staff.organizations.members.update_profile","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":["string","null"],"maxLength":50},"lastName":{"type":["string","null"],"maxLength":50},"phone":{"type":["string","null"],"maxLength":30}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Cypress staff: organizations"],"summary":"Take a person out of an organization (restore_organization_member brings them back)","description":"Revokes one person's membership: they lose access to the organization at once. Refused for the last admin of a business (transfer it first), for yourself and for an agent user. Their account and their other memberships stay. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `MEMBER.UPDATED`. Since 1.5.0.","operationId":"revoke_organization_member","x-cypress-action":"staff.organizations.members.revoke","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/members/{userId}/restore":{"post":{"tags":["Cypress staff: organizations"],"summary":"Give a revoked member their access back, with their old role","description":"Restores a revoked membership with the role it had. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `MEMBER.UPDATED`. Since 1.5.0.","operationId":"restore_organization_member","x-cypress-action":"staff.organizations.members.restore","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/members/{userId}/password-reset":{"post":{"tags":["Cypress staff: organizations"],"summary":"Send a member the password-reset email (to their own address)","description":"Sends the member the sign-in provider's password-reset email, at the address they sign in with. Nothing about the password passes through Cypress or the caller. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"send_member_password_reset","x-cypress-action":"staff.organizations.members.password_reset","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/billing":{"patch":{"tags":["Cypress staff: organizations"],"summary":"Tax id, tax exemption, billing emails and billing address","description":"The billing details Cypress invoices against. A new billing email is also set on the organization's Stripe customer (where ACH mandates and receipts go). Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"update_organization_billing_details","x-cypress-action":"staff.organizations.billing.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"taxId":{"type":["string","null"],"maxLength":50},"taxExempt":{"type":"boolean"},"billingEmail":{"type":["string","null"],"maxLength":200,"format":"email"},"billingEmailCc":{"type":"array","items":{"type":"string","maxLength":200,"format":"email"},"maxItems":5,"description":"Up to five more addresses every billing email also goes to (since 1.7.0)"},"billingAddress":{"type":["string","null"],"maxLength":200},"billingCity":{"type":["string","null"],"maxLength":100},"billingState":{"type":["string","null"],"maxLength":100},"billingZip":{"type":["string","null"],"maxLength":20},"billingCountry":{"type":["string","null"],"maxLength":100}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/invoice-settings":{"get":{"tags":["Cypress staff: organizations"],"summary":"The parts each commission invoice line prints, whether Deal Setup needs a PO, how a close splits into invoices, and a preview line","description":"Admin › Organizations › Billing › Invoice content and How they pay › Invoices at each close: how a close splits into invoices (grouping, with the fields it can group by), the parts each line prints in order (vehicle, VIN, Unit #, location, PO number, the organization's own Deal Setup fields…), whether it is the house default, whether the seller must enter a PO before confirming Deal Setup, every part available, and the line as it would print for the organization's latest sale. Cypress staff only: a CM token. Since 1.7.0.","operationId":"get_organization_invoice_settings","x-cypress-action":"staff.organizations.invoices.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Cypress staff: organizations"],"summary":"Set the parts each invoice line prints (in order), require a PO on every deal, or how a close splits into invoices","description":"The Invoice content Edit. `invoiceLineParts` lists the parts in order: `vehicle`, `vin`, `unit`, `plate`, `location`, `po`, `saleDate`, `salePrice`, or `custom:<key>` for one of the organization's seller Deal Setup fields; an empty list goes back to the house default (vehicle, VIN, Unit #, location, PO). `poRequired: true` stops the seller confirming Deal Setup without a PO number. `invoiceGrouping` (ACH and bank transfer; a per-sale organization always gets one invoice per sale): `ALL_OPEN` one invoice per close with every open commission (the default), `PER_VEHICLE` one per sale, or `BY_FIELD` one per value of `invoiceGroupField` (`location`, `po`, `state`, `fleet` or `custom:<key>`), sales without a value sharing one. On ACH each invoice is its own debit. Applies to invoices issued from now on; an invoice already issued keeps what it printed. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.7.0.","operationId":"update_organization_invoice_settings","x-cypress-action":"staff.organizations.invoices.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"invoiceLineParts":{"type":"array","items":{"type":"string","minLength":1,"maxLength":80},"maxItems":12,"description":"The parts, in order; [] for the house default"},"poRequired":{"type":"boolean"},"invoiceGrouping":{"type":"string","enum":["ALL_OPEN","BY_FIELD","PER_VEHICLE"],"description":"How each close splits the open commissions into invoices"},"invoiceGroupField":{"type":["string","null"],"minLength":1,"maxLength":80,"description":"BY_FIELD only: location, po, state, fleet or custom:<key>"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/ach/batches":{"get":{"tags":["Cypress staff: organizations"],"summary":"The organization's last 20 ACH conciliations, with their invoices","description":"Each ACH conciliation of the organization (newest first): its total, status, Stripe payment, and the invoices it paid with their vehicles. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_organization_ach_batches","x-cypress-action":"staff.organizations.ach.batches","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/customers":{"get":{"tags":["Cypress staff: organizations"],"summary":"The private individuals on Cypress, newest first","description":"The people (not businesses) with a Cypress account: name, email, phone, city, status, whether their email is confirmed and their profile complete, the storefront they came through (`origin` a slug, or marketplace), how many storefronts they follow, and whether a request to become a dealer waits (`dealerRequestPending`; `dealerRequest=pending` lists only those, since 1.9.0). Personal data: Cypress staff only. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_private_customers","x-cypress-action":"staff.customers.list","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":100,"description":"Part of the name or email"},"description":"Part of the name or email"},{"name":"status","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"origin","in":"query","required":false,"schema":{"type":"string","maxLength":80,"description":"A storefront's slug, or marketplace for those who came with none"},"description":"A storefront's slug, or marketplace for those who came with none"},{"name":"dealerRequest","in":"query","required":false,"schema":{"type":"string","enum":["pending"],"description":"pending: only those whose request to become a dealer waits for Cypress (1.9.0)"},"description":"pending: only those whose request to become a dealer waits for Cypress (1.9.0)"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page, from 1 (1 when left out)"},"description":"Page, from 1 (1 when left out)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/customers/{id}":{"get":{"tags":["Cypress staff: organizations"],"summary":"One private individual's account","description":"One private individual's account as BackOffice shows it: their details, where they came from, what they follow. To suspend or revoke it, use change_organization_status or revoke_organization_member on its id. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_private_customer","x-cypress-action":"staff.customers.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer's account (organization) id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/customers/{id}/resend-confirmation":{"post":{"tags":["Cypress staff: organizations"],"summary":"Send the confirm-your-email message again, with a fresh link","description":"For a customer whose email is not confirmed yet: a new confirmation link is emailed (the old one stops working). Refused when the address is already confirmed. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"resend_customer_confirmation","x-cypress-action":"staff.customers.resend_confirmation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/team":{"get":{"tags":["Cypress staff: organizations"],"summary":"Cypress's own people: Cypress Managers and admins","description":"The members of Cypress itself, with their role and status: the people an account manager, a default account manager or a reviewer can be. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_cypress_staff","x-cypress-action":"staff.team.list","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":100}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page, from 1 (1 when left out)"},"description":"Page, from 1 (1 when left out)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/team/{userId}":{"get":{"tags":["Cypress staff: organizations"],"summary":"One Cypress staff member and their role","description":"One member of Cypress: name, email, phone, role and status. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_cypress_staff_member","x-cypress-action":"staff.team.get","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/team/{userId}/activity":{"get":{"tags":["Cypress staff: organizations"],"summary":"A staff member's actions across every organization, newest first","description":"The audit entries a Cypress staff member authored, in any organization, newest first. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_cypress_staff_activity","x-cypress-action":"staff.team.activity","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page, from 1 (1 when left out)"},"description":"Page, from 1 (1 when left out)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/platform/default-account-manager":{"get":{"tags":["Cypress staff: organizations"],"summary":"Who at Cypress gets the copy of notifications for organizations with no account manager","description":"The default account manager (copied on the notifications of every organization that has no account manager of its own) and the staff who could be it. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_default_account_manager","x-cypress-action":"staff.platform.default_account_manager.get","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Cypress staff: organizations"],"summary":"Choose (or clear) the default account manager","description":"Sets the Cypress staff member copied on the notifications of every organization with no account manager; null clears it. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"set_default_account_manager","x-cypress-action":"staff.platform.default_account_manager.set","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"A Cypress staff member (list_cypress_staff); null clears it"}},"required":["userId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/platform/account-rules":{"get":{"tags":["Cypress staff: organizations"],"summary":"What every individual and every business may do, and how much","description":"The account rules for each kind of account: the features (which Cypress edits here, and where the others are switched), the caps, the defaults in code, Cypress's edits and the result. Cypress staff only: a CM token. Since 1.9.0.","operationId":"get_account_rules","x-cypress-action":"staff.platform.account_rules.get","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Cypress staff: organizations"],"summary":"Edit the defaults for every individual and every business","description":"Replaces Cypress's edits to the account rules, whole: for each kind, features switched on or off and caps (null is no cap). A key left out is the code's default. One organization's own overrides stay as they are. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"set_account_rules","x-cypress-action":"staff.platform.account_rules.set","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"INDIVIDUAL":{"type":"object","properties":{"features":{"type":"object","properties":{"team":{"type":"boolean"},"apps":{"type":"boolean"},"apiKeys":{"type":"boolean"},"valuations":{"type":"boolean"},"listings":{"type":"boolean"},"pricingRules":{"type":"boolean"},"campaigns":{"type":"boolean"}},"description":"On (true) or off (false); a feature left out follows the level below"},"caps":{"type":"object","properties":{"listings":{"type":["integer","null"],"minimum":0},"valuations":{"type":["integer","null"],"minimum":0},"teamMembers":{"type":["integer","null"],"minimum":0},"campaignEmailsPerMonth":{"type":["integer","null"],"minimum":0},"cedarAnswersPerDay":{"type":["integer","null"],"minimum":0}},"description":"A number, or null for no cap; a cap left out follows the level below"}}},"BUSINESS":{"type":"object","properties":{"features":{"type":"object","properties":{"team":{"type":"boolean"},"apps":{"type":"boolean"},"apiKeys":{"type":"boolean"},"valuations":{"type":"boolean"},"listings":{"type":"boolean"},"pricingRules":{"type":"boolean"},"campaigns":{"type":"boolean"}},"description":"On (true) or off (false); a feature left out follows the level below"},"caps":{"type":"object","properties":{"listings":{"type":["integer","null"],"minimum":0},"valuations":{"type":["integer","null"],"minimum":0},"teamMembers":{"type":["integer","null"],"minimum":0},"campaignEmailsPerMonth":{"type":["integer","null"],"minimum":0},"cedarAnswersPerDay":{"type":["integer","null"],"minimum":0}},"description":"A number, or null for no cap; a cap left out follows the level below"}}}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/account-rules":{"get":{"tags":["Cypress staff: organizations"],"summary":"Its kind's rules, its own overrides, the result and what it used","description":"The account rules as they hold for one organization: its kind, its kind's rules (the defaults with Cypress's edits), its own overrides, the result, and what it used of its caps (valuations, listings, team seats, campaign emails this month). Cypress staff only: a CM token. Since 1.9.0.","operationId":"get_organization_account_rules","x-cypress-action":"staff.organizations.account_rules.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Cypress staff: organizations"],"summary":"Override its kind's rules for this one organization","description":"Replaces the organization's own overrides, whole: features switched on or off and caps (null is no cap). A key left out follows its kind's rules. Its API and MCP access follows at once. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.9.0.","operationId":"set_organization_account_rules","x-cypress-action":"staff.organizations.account_rules.set","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"features":{"type":"object","properties":{"team":{"type":"boolean"},"apps":{"type":"boolean"},"apiKeys":{"type":"boolean"},"valuations":{"type":"boolean"},"listings":{"type":"boolean"},"pricingRules":{"type":"boolean"},"campaigns":{"type":"boolean"}},"description":"On (true) or off (false); a feature left out follows the level below"},"caps":{"type":"object","properties":{"listings":{"type":["integer","null"],"minimum":0},"valuations":{"type":["integer","null"],"minimum":0},"teamMembers":{"type":["integer","null"],"minimum":0},"campaignEmailsPerMonth":{"type":["integer","null"],"minimum":0},"cedarAnswersPerDay":{"type":["integer","null"],"minimum":0}},"description":"A number, or null for no cap; a cap left out follows the level below"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/organizations/{id}/dealer-request":{"get":{"tags":["Cypress staff: organizations"],"summary":"The latest dealer request and the business checklist it needs","description":"The latest request (its business, status, Cypress's reason when declined) and the business checklist (W-9, dealer license, billing) that must be done before it is approved. Cypress staff only: a CM token. Since 1.9.0.","operationId":"get_organization_dealer_request","x-cypress-action":"staff.organizations.dealer_request.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Cypress staff: organizations"],"summary":"Approve (the checklist done): the individual becomes a business; or decline, with a reason the person reads","description":"Approve: the same organization becomes a business (no longer an individual, named as the business, a business record in the CRM, the business account rules), its cars, offers and sales kept; refused until the business checklist is done. Decline: it stays an individual, told why, and may ask again. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.9.0.","operationId":"decide_dealer_request","x-cypress-action":"staff.organizations.dealer_request.decide","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["APPROVE","DECLINE"]},"reason":{"type":"string","maxLength":2000,"description":"Why, when declining: the person is told"}},"required":["decision"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/update-requests":{"get":{"tags":["Cypress staff: review queues"],"summary":"The review queue: sellers' floor-price, location and archive requests","description":"What sellers asked Cypress to approve (newest first, at most 500): a new floor or target price, a new pickup location, or taking a vehicle out (archive, sold elsewhere). Each with the vehicle, the organization, before and after, who asked and who decided. With the Cypress-Organization header and no orgId, that organization's only. Counts per status and kind come with it. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_update_requests","x-cypress-action":"staff.update_requests.list","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["PENDING","APPROVED","REJECTED"]}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["PRICE","LOCATION","ARCHIVE"]}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Only this organization's"},"description":"Only this organization's"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/update-requests/stats":{"get":{"tags":["Cypress staff: review queues"],"summary":"Open update requests, open archive requests, and archive decisions due","description":"The BackOffice badges: open update requests, the archive requests among them (a vehicle stays listed until one is decided), and Post-Sale archives still waiting for Cypress's decision toward the seller. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_review_queue_counts","x-cypress-action":"staff.update_requests.stats","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/update-requests/{id}":{"get":{"tags":["Cypress staff: review queues"],"summary":"One update request with its vehicle","description":"One request: its kind, what it asks (before and after), the vehicle, who asked, and the decision if there is one. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_update_request","x-cypress-action":"staff.update_requests.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/update-requests/{id}/impact":{"get":{"tags":["Cypress staff: review queues"],"summary":"The open offers a price change would decline, leave in review, or now qualify","description":"Before approve_price_update: the vehicle's open offers, each placed where the new prices put it (below the new floor: declined if you name it; at or above the new target: you may accept one; between: review). For a location or archive request every open offer ends. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_update_request_impact","x-cypress-action":"staff.update_requests.impact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/update-requests/{id}/reject":{"post":{"tags":["Cypress staff: review queues"],"summary":"Turn a request down; the seller is told, and a paused listing resumes","description":"Rejects an open request of any kind, with notes the seller reads. A listing an archive request had paused is live again; an archive request's rejection reaches the seller's webhooks as VEHICLES.DISPOSITION.RESOLVED. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.DISPOSITION.RESOLVED`. Since 1.5.0.","operationId":"reject_update_request","x-cypress-action":"staff.update_requests.reject","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/update-requests/{id}/approve-price":{"post":{"tags":["Cypress staff: review queues"],"summary":"Apply a seller's new prices; decline, keep or accept the open offers as you say","description":"Applies the requested floor and target (the offer rules and the listing's price follow). The offers named in autoRejectOfferIds are declined; each offer in qualifyingDecisions is accepted (one at most: the vehicle goes Under Offer or Offer Accepted), sent to review or left. Every buyer with an open offer is told the price changed, never where the floor sits. Read get_update_request_impact first. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.UPDATED`. Since 1.5.0.","operationId":"approve_price_update","x-cypress-action":"staff.update_requests.approve_price","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","maxLength":2000},"autoRejectOfferIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":200,"default":[],"description":"Open offers to decline: those below the new floor"},"qualifyingDecisions":{"type":"object","additionalProperties":{"type":"string","enum":["accept","review","leave"]},"description":"By offer id, for offers at or above the new target; accept one at most"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/update-requests/{id}/approve-location":{"post":{"tags":["Cypress staff: review queues"],"summary":"Apply a seller's new pickup location; every open offer is withdrawn and its buyer told","description":"Moves the vehicle to the requested pickup location. Every open offer on it is withdrawn (the buyer offered for the old place) and its buyer told they may offer again; the seller is told how many. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"approve_location_update","x-cypress-action":"staff.update_requests.approve_location","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/update-requests/{id}/approve-archive":{"post":{"tags":["Cypress staff: review queues"],"summary":"Archive the vehicle as the seller asked: offers withdrawn, a closing in progress cancelled","description":"Archives the vehicle with the full cleanup (its listing ends, open offers are withdrawn and their buyers told, a closing in progress is cancelled), recording who is responsible and, for a vehicle in Post-Sale (required there), Cypress's decision toward them. Reaches the seller's webhooks as VEHICLES.DISPOSITION.RESOLVED. roll_back_archive undoes the archive but revives no offer or closing. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `VEHICLES.DISPOSITION.RESOLVED`. Since 1.5.0.","operationId":"approve_archive_request","x-cypress-action":"staff.update_requests.approve_archive","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"type":"string","maxLength":2000},"reason":{"type":"string","maxLength":2000},"responsibleParty":{"type":"string","enum":["SELLER","BUYER","CYPRESS"],"description":"Who is responsible (SELLER when left out)"},"decision":{"type":"string","enum":["NO_ACTION","WARNING","PENALTY_FEE","ESCALATE_REVIEW"],"description":"Toward the responsible party: required for a vehicle in Post-Sale"},"decisionNotes":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/archives":{"get":{"tags":["Cypress staff: review queues"],"summary":"Every archive record with its vehicle, disposition and Cypress's decision","description":"The archived vehicles (newest first, at most 500): how each left (sold elsewhere, archived, deal fell through, removed), the phase it left from, who is responsible, Cypress's decision toward them and whether it was rolled back. With the Cypress-Organization header and no orgId, that organization's only. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_archived_vehicles","x-cypress-action":"staff.archives.list","parameters":[{"name":"disposition","in":"query","required":false,"schema":{"type":"string","enum":["SOLD_ELSEWHERE","ARCHIVED","DEAL_FELL_THROUGH","REMOVED","RETURN_TO_INVENTORY"]}},{"name":"decision","in":"query","required":false,"schema":{"type":"string","enum":["PENDING","NO_ACTION","WARNING","PENALTY_FEE","ESCALATE_REVIEW"]}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Only this organization's"},"description":"Only this organization's"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/archives/{id}/decision":{"post":{"tags":["Cypress staff: review queues"],"summary":"No action, a warning, a penalty fee or an escalation, toward whoever is responsible","description":"Records Cypress's decision toward the party responsible for an archived vehicle (by its archive record's id, from list_archived_vehicles), with notes. It records the decision; a penalty fee is billed separately. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"record_archive_decision","x-cypress-action":"staff.archives.decide","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The archive record"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["NO_ACTION","WARNING","PENALTY_FEE","ESCALATE_REVIEW"]},"notes":{"type":"string","maxLength":2000}},"required":["decision"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/archives/{id}/rollback":{"post":{"tags":["Cypress staff: review queues"],"summary":"Put an archived vehicle back where it was; its offers and closing stay ended","description":"Returns an archived vehicle to the status it had (Approved, back in inventory, when it left from Post-Sale or was under offer elsewhere), keeps the archive record as history, and tells the seller. Offers withdrawn and a closing cancelled by the archive are not revived. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"roll_back_archive","x-cypress-action":"staff.archives.rollback","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The archive record"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":2000}},"required":["reason"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/label-applications":{"get":{"tags":["Cypress staff: review queues"],"summary":"Labels a rule wants on a vehicle, waiting for Cypress to approve","description":"The label applications a label rule set to notify Cypress (instead of applying itself) has proposed: the vehicle and the label, newest first. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_pending_label_applications","x-cypress-action":"staff.label_applications.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/label-applications/{id}/decision":{"post":{"tags":["Cypress staff: review queues"],"summary":"Put the proposed label on the vehicle, or dismiss it","description":"APPROVE puts the label on the vehicle (logged as the rule's); DISMISS drops the proposal. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"decide_label_application","x-cypress-action":"staff.label_applications.decide","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["APPROVE","DISMISS"]}},"required":["action"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/labels":{"get":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"Cypress's labels and every organization's, with how many vehicles carry each","description":"All vehicle labels, global ones first: name, slug, category, color, scope and organization, whether active and system-derived, and how many vehicles carry it. forFlow=1 lists only what an automation may put on or take off (with flowOrganizationId, an organization's automation: the global labels and that organization's). Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_platform_labels","x-cypress-action":"staff.labels.list","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["GLOBAL","ORG"]}},{"name":"organizationId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Only this organization's own labels"},"description":"Only this organization's own labels"},{"name":"forFlow","in":"query","required":false,"schema":{"type":"string","enum":["1"]}},{"name":"flowOrganizationId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"A new vehicle label, for every organization or for one","description":"Creates a vehicle label: GLOBAL (every organization may use it) or ORG (one organization's). Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"create_platform_label","x-cypress-action":"staff.labels.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"slug":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9-]+$"},"category":{"type":"string","enum":["CATEGORY","BRAND","VEHICLE_TYPE","MILEAGE","AGE","CONDITION","LOCATION","CUSTOM"]},"color":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$","description":"#RRGGBB"},"scope":{"type":"string","enum":["GLOBAL","ORG"],"description":"GLOBAL: every organization; ORG: the one named in organizationId","default":"ORG"},"organizationId":{"type":"string","minLength":1,"maxLength":64},"isSystemDerived":{"type":"boolean","default":false,"description":"Put on and taken off by Cypress itself; automations may not use it"}},"required":["name","slug","category"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/labels/{id}":{"patch":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"Rename, recolor, recategorize or switch off a label","description":"Changes a label's name, slug, category or color, or switches it off (isActive false). The vehicles carrying it keep it. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"update_platform_label","x-cypress-action":"staff.labels.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"slug":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[a-z0-9-]+$"},"color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}$"},"category":{"type":"string","enum":["CATEGORY","BRAND","VEHICLE_TYPE","MILEAGE","AGE","CONDITION","LOCATION","CUSTOM"]},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"Delete a label no vehicle carries; one in use is switched off instead","description":"Deletes the label when no vehicle carries it; when some do, it is switched off instead and they keep it. Answers which happened. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"delete_platform_label","x-cypress-action":"staff.labels.delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/label-rules":{"get":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"The rules that put labels on vehicles by themselves","description":"The label assignment rules: the label, the conditions (make, mileage, year, condition, location, floor against valuation, time in status…), whether all or any must hold, the priority, and whether the rule applies the label or asks Cypress first (list_pending_label_applications). Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_label_rules","x-cypress-action":"staff.label_rules.list","parameters":[{"name":"labelId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["GLOBAL","ORG"]}},{"name":"isActive","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"A rule that puts a label on the vehicles that meet its conditions","description":"Creates a label rule: when a vehicle meets the conditions (all, or any with matchAll false), the label goes on (AUTO) or Cypress is asked first (NOTIFY_CM). GLOBAL for every organization, or ORG for one. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"create_label_rule","x-cypress-action":"staff.label_rules.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"labelId":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","maxLength":120},"conditions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["LABEL","MAKE","VEHICLE_TYPE","MILEAGE","YEAR","CONDITION_SCORE","LOCATION","FLOOR_VS_VALUATION","TIME_IN_STATUS"]},"operator":{"type":"string","enum":["EQ","NOT_EQ","IN","NOT_IN","GT","GTE","LT","LTE","BETWEEN"]},"value":{"description":"A value, a list (IN, NOT_IN) or a [low, high] pair (BETWEEN)"},"logicGroup":{"type":"string","maxLength":40}},"required":["type","operator","value"]},"minItems":1,"maxItems":30},"matchAll":{"type":"boolean","default":true},"priority":{"type":"integer","default":0},"applyBehavior":{"type":"string","enum":["AUTO","NOTIFY_CM"],"default":"AUTO"},"scope":{"type":"string","enum":["GLOBAL","ORG"],"description":"GLOBAL: every organization; ORG: the one named in organizationId","default":"ORG"},"organizationId":{"type":"string","minLength":1,"maxLength":64},"isActive":{"type":"boolean","default":true}},"required":["labelId","conditions"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/pricing-rules":{"get":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"Cypress's pricing rules and the organizations' own","description":"The listing pricing rules apply_pricing_rule runs: conditions, outcome (approve and list, reject to draft, leave for review), the price figures they set, priority and whether active. With organizationId (or the Cypress-Organization header): the global rules and that organization's. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_platform_pricing_rules","x-cypress-action":"staff.pricing_rules.list","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["GLOBAL","ORG"]}},{"name":"organizationId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"isActive","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"A rule that approves and lists, rejects, or holds for review the vehicles that meet it","description":"Creates a pricing rule, GLOBAL or for one organization: when a vehicle in review meets the conditions, the outcome applies (at once with AUTO, or as a suggestion to Cypress with NOTIFY_CM), with the target as a markup over the floor and the offer thresholds it sets. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"create_platform_pricing_rule","x-cypress-action":"staff.pricing_rules.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":1000},"scope":{"type":"string","enum":["GLOBAL","ORG"],"description":"GLOBAL: every organization; ORG: the one named in organizationId","default":"ORG"},"organizationId":{"type":"string","minLength":1,"maxLength":64},"conditions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["LABEL","MAKE","VEHICLE_TYPE","MILEAGE","YEAR","CONDITION_SCORE","LOCATION","FLOOR_VS_VALUATION","TIME_IN_STATUS"]},"operator":{"type":"string","enum":["EQ","NOT_EQ","IN","NOT_IN","GT","GTE","LT","LTE","BETWEEN"]},"value":{"description":"A value, a list (IN, NOT_IN) or a [low, high] pair (BETWEEN)"},"logicGroup":{"type":"string","maxLength":40}},"required":["type","operator","value"]},"minItems":1,"maxItems":30},"matchAll":{"type":"boolean","default":true},"outcome":{"type":"string","enum":["APPROVE_AND_LIST","AUTO_REJECT","REQUIRE_MANUAL_REVIEW"]},"applyBehavior":{"type":"string","enum":["AUTO","NOTIFY_CM"],"default":"NOTIFY_CM"},"rejectionReason":{"type":"string","maxLength":1000,"description":"With AUTO_REJECT: what the seller reads"},"targetMarkupPct":{"type":"number","minimum":0,"maximum":200,"description":"The target price as % over the floor"},"acceptBelowTargetPct":{"type":"number","minimum":0,"maximum":100},"denyAboveFloorPct":{"type":"number","minimum":0,"maximum":100},"priority":{"type":"integer","default":0},"isActive":{"type":"boolean","default":true}},"required":["name","conditions","outcome"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/pricing-rules/{id}":{"patch":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"Change a pricing rule's conditions, outcome, figures, priority or switch it off","description":"Changes the fields sent; null clears a figure. The vehicles already priced by it keep their prices. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"update_platform_pricing_rule","x-cypress-action":"staff.pricing_rules.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"],"maxLength":1000},"conditions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["LABEL","MAKE","VEHICLE_TYPE","MILEAGE","YEAR","CONDITION_SCORE","LOCATION","FLOOR_VS_VALUATION","TIME_IN_STATUS"]},"operator":{"type":"string","enum":["EQ","NOT_EQ","IN","NOT_IN","GT","GTE","LT","LTE","BETWEEN"]},"value":{"description":"A value, a list (IN, NOT_IN) or a [low, high] pair (BETWEEN)"},"logicGroup":{"type":"string","maxLength":40}},"required":["type","operator","value"]},"minItems":1,"maxItems":30},"matchAll":{"type":"boolean"},"outcome":{"type":"string","enum":["APPROVE_AND_LIST","AUTO_REJECT","REQUIRE_MANUAL_REVIEW"]},"applyBehavior":{"type":"string","enum":["AUTO","NOTIFY_CM"]},"rejectionReason":{"type":["string","null"],"maxLength":1000},"targetMarkupPct":{"type":["number","null"],"minimum":0,"maximum":200},"acceptBelowTargetPct":{"type":["number","null"],"minimum":0,"maximum":100},"denyAboveFloorPct":{"type":["number","null"],"minimum":0,"maximum":100},"priority":{"type":"integer"},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"Delete a pricing rule","description":"Deletes the rule; vehicles it priced keep their prices. To stop it for a while, update_platform_pricing_rule with isActive false. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"delete_platform_pricing_rule","x-cypress-action":"staff.pricing_rules.delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/channels":{"get":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"The platform's channels and the organizations' grants, with their commission","description":"The sales channels (marketplace, promotions, share links, storefront): the platform's master rows and each organization's grant or override, whether enabled, and the commission scheme each charges. With orgId (or the Cypress-Organization header): the platform's and that organization's. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_sales_channels","x-cypress-action":"staff.channels.list","parameters":[{"name":"orgId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"An organization's own grant of a channel, with its commission scheme","description":"Creates the organization's row for a channel type with an active commission scheme (refused when it has one: update_sales_channel). Granting share links (P2P_LINK) makes a default share link for every vehicle it has on the market, in the background. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"grant_sales_channel","x-cypress-action":"staff.channels.grant","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["MARKETPLACE","PROMOTION","P2P_LINK","STOREFRONT"]},"organizationId":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"},"commissionSchemeId":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","maxLength":120},"isEnabled":{"type":"boolean","default":true}},"required":["type","organizationId","commissionSchemeId"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/channels/{id}":{"patch":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"Enable or disable a channel, rename it or change its commission","description":"Changes a channel row (the platform's master switch, or one organization's grant). Disabling share links or the storefront would strand vehicles visible only there: the call is refused with how many, until republishLinkOnly (share links) or republishStorefrontOnly (storefront) is true, which puts them back on the public marketplace and tells their sellers. A platform row changes every organization. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `ORGANIZATION.UPDATED`. Since 1.5.0.","operationId":"update_sales_channel","x-cypress-action":"staff.channels.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"commissionSchemeId":{"type":"string","minLength":1,"maxLength":64},"isEnabled":{"type":"boolean"},"settings":{"type":"object","additionalProperties":{}},"republishLinkOnly":{"type":"boolean","description":"Confirms that vehicles visible only through share links go public"},"republishStorefrontOnly":{"type":"boolean","description":"Confirms that vehicles visible only on the storefront go public"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/commission-schemes":{"get":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"What Cypress charges per sale on each channel","description":"Every commission scheme: its code, name, amount in cents and whether it is active. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_commission_schemes","x-cypress-action":"staff.commission_schemes.list","responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"A new commission amount, created switched off","description":"Creates a commission scheme (switched off until update_commission_scheme switches it on): a code that never changes, a name and the amount per sale in cents. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"create_commission_scheme","x-cypress-action":"staff.commission_schemes.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":60},"name":{"type":"string","minLength":1,"maxLength":120},"amountCents":{"type":"integer","minimum":0}},"required":["code","name","amountCents"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/commission-schemes/{id}":{"patch":{"tags":["Cypress staff: labels, pricing rules and channels"],"summary":"Change a scheme's name or amount, or switch it on or off","description":"Changes what a scheme charges from the next sale on, its name, or whether it is active (a self-serve share-link scheme needs an amount before it is switched on). Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"update_commission_scheme","x-cypress-action":"staff.commission_schemes.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"amountCents":{"type":"integer","minimum":0},"isActive":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/automations":{"get":{"tags":["Cypress staff: the Automation Hub"],"summary":"Cypress's automations and every organization's, with their review state","description":"Every automation in the Hub: Cypress's own (GLOBAL, with the organizations they run for) and each organization's (ORG, with where its draft stands: submitted is \"Awaiting review\"). Each with its trigger, last run, chain links (Run automation), and who made and changed it. An organization reads its own with list_automations. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_hub_automations","x-cypress-action":"staff.automations.list","parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["GLOBAL","ORG"]}},{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["ONBOARDING","PRE_LISTING","LISTING","POST_SALE","MAINTENANCE","RELATIONSHIP"]}},{"name":"isActive","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Cypress staff: the Automation Hub"],"summary":"A Cypress automation (GLOBAL) or one for an organization (ORG), with its first draft","description":"Creates an automation with its first draft; nothing runs until publish_automation. GLOBAL is Cypress's, for every organization or those in targetOrgIds; ORG belongs to organizationId (the Cypress-Organization header's when left out). Operation and Planning stages need the organization's Planning product. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"create_hub_automation","x-cypress-action":"staff.automations.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":1000},"category":{"type":"string","enum":["ONBOARDING","PRE_LISTING","LISTING","POST_SALE","MAINTENANCE","RELATIONSHIP"]},"scope":{"type":"string","enum":["GLOBAL","ORG"],"default":"ORG"},"stages":{"type":"array","items":{"type":"string","enum":["OPERATION","PLANNING","REMARKETING","POST_SALE"]},"minItems":1,"description":"The stages it works in (Operation and Planning need the organization's Planning product)"},"organizationId":{"type":"string","minLength":1,"maxLength":64,"description":"With ORG: whose it is"},"targetOrgIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":500,"description":"\"Runs for\" (a Cypress automation only): the organizations it runs for; empty means every one"},"nodes":{"type":"array","items":{"type":"object","additionalProperties":{}},"maxItems":200,"description":"The canvas nodes, as get_hub_automation answers them","default":[]},"edges":{"type":"array","items":{"type":"object","additionalProperties":{}},"maxItems":400,"description":"The canvas edges, as get_hub_automation answers them","default":[]}},"required":["name","category"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/automations/{id}":{"get":{"tags":["Cypress staff: the Automation Hub"],"summary":"One automation with its versions and their graphs","description":"One automation, Cypress's or an organization's: its settings, the organizations it runs for, and its versions (draft, published, archived) with their graphs and review stamps. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_hub_automation","x-cypress-action":"staff.automations.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Cypress staff: the Automation Hub"],"summary":"Name, category, stages, priority, who it runs for, or switch it on or off","description":"Changes an automation's settings (not its graph: save_hub_automation_draft): name, description, category, stages, its priority among automations on the same trigger (lower runs first), the organizations a Cypress automation runs for, and isActive (switching it off stops its runs; switching on runs the published version). Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"update_hub_automation","x-cypress-action":"staff.automations.update","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":1000},"category":{"type":"string","enum":["ONBOARDING","PRE_LISTING","LISTING","POST_SALE","MAINTENANCE","RELATIONSHIP"]},"isActive":{"type":"boolean"},"priority":{"type":"integer","minimum":0,"maximum":9999},"stages":{"type":"array","items":{"type":"string","enum":["OPERATION","PLANNING","REMARKETING","POST_SALE"]},"minItems":1,"description":"The stages it works in (Operation and Planning need the organization's Planning product)"},"targetOrgIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":500,"description":"\"Runs for\" (a Cypress automation only): the organizations it runs for; empty means every one"}}}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Cypress staff: the Automation Hub"],"summary":"Delete an automation never published (with its dry runs)","description":"Deletes an automation that was never published, with its dry runs. One that has run on real records is refused: switch it off instead (update_hub_automation with isActive false) and its runs stay as its history. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"delete_hub_automation","x-cypress-action":"staff.automations.delete","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/automations/{id}/draft":{"put":{"tags":["Cypress staff: the Automation Hub"],"summary":"Save the graph as the draft (a new draft when there is none)","description":"Saves the nodes and edges as the automation's draft, as the canvas's Save does; a draft may be half-wired. The published version keeps running until publish_automation. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"save_hub_automation_draft","x-cypress-action":"staff.automations.save_draft","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","additionalProperties":{}},"maxItems":200,"description":"The canvas nodes, as get_hub_automation answers them"},"edges":{"type":"array","items":{"type":"object","additionalProperties":{}},"maxItems":400,"description":"The canvas edges, as get_hub_automation answers them"}},"required":["nodes","edges"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/automations/{id}/publish":{"post":{"tags":["Cypress staff: the Automation Hub"],"summary":"Publish the draft: it replaces the published version and runs (for an organization's, this approves it)","description":"Checks the draft as publishing must (wiring, batch lanes, chains, labels, stages, channels: the errors come back named) and makes it the published version; the one before is archived. For an organization's automation this is Cypress's approval: it runs as the organization's account admin and the organization is told (AUTOMATION.PUBLISHED). It runs while the automation is switched on. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `AUTOMATION.PUBLISHED`. Since 1.5.0.","operationId":"publish_automation","x-cypress-action":"staff.automations.publish","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/automations/{id}/send-back":{"post":{"tags":["Cypress staff: the Automation Hub"],"summary":"Answer a submitted draft with what to change","description":"Cypress's other answer to an organization's submitted draft: it goes back to the organization with your note, and the organization is told (AUTOMATION.SENT_BACK). Refused when nothing is waiting. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Emits `AUTOMATION.SENT_BACK`. Since 1.5.0.","operationId":"send_back_automation","x-cypress-action":"staff.automations.send_back","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","minLength":1,"maxLength":2000,"description":"What to change; the organization reads it"}},"required":["note"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/automations/{id}/run":{"post":{"tags":["Cypress staff: the Automation Hub"],"summary":"Run the published version on chosen vehicles (or as its trigger would), for real or as a dry run","description":"Queues runs of the published version: on each vehicle named, or once as its trigger would. A dry run (dryRun, or ?dryRun=true) writes nothing and may run while the automation is switched off; a real run needs it on, and does what its steps do (labels, statuses, messages). A Cypress automation that runs for chosen organizations refuses vehicles of others, naming them. Read the runs with list_hub_automation_runs. Cypress staff only: a CM token. `?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing. Since 1.5.0.","operationId":"run_hub_automation","x-cypress-action":"staff.automations.run","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` meets every rule and answers `{ dryRun: true, would }`, writing nothing."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","default":false},"triggerType":{"type":"string","enum":["ENTITY_CREATED","ENTITY_UPDATED","ENTITY_TIME_ELAPSED","MANUAL","SCHEDULE","FLOW_CALLED"],"default":"MANUAL"},"vehicleIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":500,"description":"The vehicles to run it on; left out, it runs once as its trigger would"}}}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"202":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/automations/{id}/duplicate":{"post":{"tags":["Cypress staff: the Automation Hub"],"summary":"A new draft automation copying another's latest graph","description":"Makes \"Copy of …\": a new automation whose draft is the source's latest graph, switched off and unpublished. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"duplicate_hub_automation","x-cypress-action":"staff.automations.duplicate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/automations/{id}/versions/{versionId}/restore":{"post":{"tags":["Cypress staff: the Automation Hub"],"summary":"Make an earlier version's graph the draft again","description":"A new draft with the graph of the version named (the current draft is set aside); publish_automation puts it live. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.5.0.","operationId":"restore_automation_version","x-cypress-action":"staff.automations.restore_version","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"versionId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/automations/runs":{"get":{"tags":["Cypress staff: the Automation Hub"],"summary":"Runs across the Hub, newest first, with the last day's numbers","description":"Runs of any automation (filter by automation, status, trigger, vehicle, dates): status, what they did, a wait in progress, the vehicle; with the last 24 hours' counts. Cypress staff only: a CM token. Since 1.5.0.","operationId":"list_hub_automation_runs","x-cypress-action":"staff.automations.runs.list","parameters":[{"name":"flowId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"Only this automation's"},"description":"Only this automation's"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["RUNNING","SUCCESS","PARTIAL","FAILED","DRY_RUN"]}},{"name":"triggerType","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"vehicleId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"At most this many (50 when left out)"},"description":"At most this many (50 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/automations/runs/{runId}":{"get":{"tags":["Cypress staff: the Automation Hub"],"summary":"One run with its steps and its vehicle","description":"One run: its automation and version, trigger, status, each step with what it did or why it stopped, and the vehicle. Cypress staff only: a CM token. Since 1.5.0.","operationId":"get_hub_automation_run","x-cypress-action":"staff.automations.runs.get","parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/platform-activity/overview":{"get":{"tags":["Cypress staff: platform activity"],"summary":"Active users by side (daily, weekly, in the period), who did the work, and the path from first visit to purchase","description":"Platform activity's Overview for a period: active people per line (everyone, buyers, sellers, consumers, Cypress staff) as a weekday daily average, a weekly average and the period's total, each against the period before; twelve full weeks of weekly active buyers and sellers; who did the work (the org's own people, Cypress, agents, not recorded); and the buyer path from vehicle page visitors to purchases. `comparable` is false while visits were recorded in one period and approximated in the other (no change is given then). Demo and showcase organizations are left out. Cypress staff only: a CM token. Since 1.6.0.","operationId":"get_platform_activity_overview","x-cypress-action":"staff.activity.overview","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7","30","90","quarter"],"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"},"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/platform-activity/funnel":{"get":{"tags":["Cypress staff: platform activity"],"summary":"The buyer and seller funnels and email reach, for a period","description":"The buyer funnel (vehicle page visitors, signed in and viewed, made an offer, had one accepted, completed a purchase: people), the seller funnel (seller organizations with activity, that uploaded, listed, received offers, accepted one, completed a sale) and campaign email reach (delivered, opened, clicked, opened the vehicle page, made an offer), with the period before for email. Cypress staff only: a CM token. Since 1.6.0.","operationId":"get_platform_activity_funnel","x-cypress-action":"staff.activity.funnel","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7","30","90","quarter"],"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"},"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/platform-activity/sides/{side}":{"get":{"tags":["Cypress staff: platform activity"],"summary":"One side: every action on the list, post-sale by stage, and the most active organizations","description":"For buyers or sellers: active people and organizations against the period before; every action of the side (signed in, viewed, offers, counters, acceptances, uploads, listings, post-sale, completed) with people, organizations and who did it; the six post-sale stages counted deal by deal (passed, median days, waiting now); and the ten most active organizations. Cypress staff only: a CM token. Since 1.6.0.","operationId":"get_platform_activity_side","x-cypress-action":"staff.activity.side","parameters":[{"name":"side","in":"path","required":true,"schema":{"type":"string","enum":["buyers","sellers"]}},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7","30","90","quarter"],"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"},"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/platform-activity/orgs":{"get":{"tags":["Cypress staff: platform activity"],"summary":"Every customer organization and person active in the period or the one before","description":"Each customer organization active in the period or the one before: its active people of its members, days active, work actions and their change, sales and purchases, who did the work, whether Cypress does most of it, whether it uses its own agents, whether its people went quiet, and when it was last active. Also each person (the organizations' own people only, never Cypress staff or agents) with days active, sign-ins and work. Use get_platform_activity_org for one organization person by person. Cypress staff only: a CM token. Since 1.6.0.","operationId":"list_platform_activity_orgs","x-cypress-action":"staff.activity.orgs.list","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7","30","90","quarter"],"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"},"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/platform-activity/orgs/{id}":{"get":{"tags":["Cypress staff: platform activity"],"summary":"One customer organization, person by person, and who else worked on it","description":"One customer organization: active people of its members, days with activity, work actions and sales against the period before, its work by who did it (uploads, listings, offers, counters, acceptances, post-sale steps), the Cypress managers and agents who also worked on the account, and each of its people with their days active, sign-ins, work and what they did. Not found for a demo or non-customer organization. Cypress staff only: a CM token. Since 1.6.0.","operationId":"get_platform_activity_org","x-cypress-action":"staff.activity.orgs.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The customer organization's Cypress id"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7","30","90","quarter"],"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"},"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/platform-activity/team":{"get":{"tags":["Cypress staff: platform activity"],"summary":"What Cypress managers did for customers and for Cypress, how, and the agents on customers' accounts","description":"Cypress managers active, work for customers (by organization and kind of work) and Cypress's own work (by kind, with who did most), the customers Cypress mostly runs, each manager (sign-ins, days active, work for customers and own, organizations, how they did it: by hand, bulk and imports, with Cedar, their own agent; the AI share counts only work whose \"how\" is recorded) and the agents that worked on customers' accounts. Cypress staff only: a CM token. Since 1.6.0.","operationId":"get_platform_activity_team","x-cypress-action":"staff.activity.team","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7","30","90","quarter"],"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"},"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/platform-activity/team/{userId}":{"get":{"tags":["Cypress staff: platform activity"],"summary":"One Cypress manager: for whom, how, their days and recent actions","description":"One Cypress manager: sign-ins and days active, work for customers (by organization and kind) and Cypress's own work against the period before, how it was done, their share of the team's own work, their actions day by day, and their recent actions (the last 30 days at most). Not found for someone who is not on the Cypress team. Cypress staff only: a CM token. Since 1.6.0.","operationId":"get_platform_activity_manager","x-cypress-action":"staff.activity.team.get","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The manager's Cypress user id (get_platform_activity_team lists them)"}},{"name":"period","in":"query","required":false,"schema":{"type":"string","enum":["7","30","90","quarter"],"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"},"description":"7, 30 or 90 days, or the quarter so far: whole UTC days ending yesterday, against as many days before (30 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/staff/platform-activity/coming-back":{"get":{"tags":["Cypress staff: platform activity"],"summary":"People or organizations by the month they were first active, and who returns","description":"Cohorts by the calendar month people (or organizations) were first active, with the share active each month after (months 0 to 6, the current month marked as running); back the month after and still active after three months (months that are over only); who came back after a break and who went quiet in the last full month; each month split into returning, new and back after a break; and month 1 and month 3 by side. Not the GMV retention of selling organizations. Cypress staff only: a CM token. Since 1.6.0.","operationId":"get_platform_activity_coming_back","x-cypress-action":"staff.activity.coming_back","parameters":[{"name":"unit","in":"query","required":false,"schema":{"type":"string","enum":["people","orgs"],"description":"people (the default) or orgs"},"description":"people (the default) or orgs"},{"name":"side","in":"query","required":false,"schema":{"type":"string","enum":["everyone","buyers","sellers","consumers"],"description":"Everyone when left out"},"description":"Everyone when left out"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-quality/benchmark-runs":{"post":{"tags":["Agent quality"],"summary":"Send one benchmark run of your agent: the setting, the summary and every question with its answer and marks","description":"Records a benchmark run of the app's agent in the organization of the token (a sandbox, usually): the setting (label, model, thinking), when it ran, the gates and whether it passed them, the summary (items, median and slowest-tenth time, shares right, faithful and useful) and each question (at most 300) with its answer (at most 4,000 characters), its marks and its time. Sending the same `agent` and `externalId` again replaces the run and its questions. Answers 201 `{ id, replaced: false }` when it is new, 200 `{ id, replaced: true }` when it replaced one. Cypress staff read it on the Cedar quality page. Needs `agent-quality:write` on a first-party app's token (an app Cypress made, such as Grove), for the organization its connection is to. An API key, a partner app, an agent's token and a CM token are refused (403 POLICY_DENIED). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"record_agent_benchmark_run","x-cypress-action":"agent_quality.benchmark_runs.record","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":200,"description":"The app's own id for it: sending it again updates it, never a second one"},"agent":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,59}$","description":"Which agent, as the app names it: \"grove-cedar\""},"label":{"type":"string","minLength":1,"maxLength":120,"description":"The setting's name: \"flash, no thinking\""},"model":{"type":"string","minLength":1,"maxLength":100},"thinking":{"type":"string","minLength":1,"maxLength":40,"description":"The thinking setting: \"off\", \"low\", \"high\", or a budget"},"configVersion":{"type":["string","null"],"maxLength":100},"startedAt":{"type":"string","format":"date-time"},"finishedAt":{"type":"string","format":"date-time"},"gates":{"type":["array","null"],"items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"What the gate checks: \"right\", \"slowest tenth\""},"passed":{"type":"boolean"},"value":{"type":["number","null"],"description":"What the run scored"},"threshold":{"type":["number","null"],"description":"What it had to reach"},"detail":{"type":["string","null"],"maxLength":300}},"required":["name","passed"]},"maxItems":30,"description":"The gates the run had to pass"},"passed":{"type":["boolean","null"],"description":"Whether it passed every gate"},"summary":{"type":"object","properties":{"items":{"type":"integer","minimum":0,"maximum":300},"medianMs":{"type":"integer","minimum":0},"p90Ms":{"type":"integer","minimum":0,"description":"Where the slowest tenth starts, in milliseconds"},"right":{"type":"number","minimum":0,"maximum":1,"description":"Share of answers judged right, 0 to 1"},"faithful":{"type":"number","minimum":0,"maximum":1},"useful":{"type":"number","minimum":0,"maximum":1},"judgment":{"type":["number","null"],"minimum":0,"maximum":1,"description":"The judgment questions' share right, when the run has them"},"thinkingTokens":{"type":["integer","null"],"minimum":0}},"required":["items","medianMs","p90Ms","right","faithful","useful"]},"items":{"type":"array","items":{"type":"object","properties":{"questionKey":{"type":"string","minLength":1,"maxLength":120,"description":"The question's stable key in the app's benchmark set"},"side":{"type":"string","enum":["seller","buyer"]},"kind":{"type":"string","enum":["lookup","judgment","action"]},"question":{"type":"string","minLength":1,"maxLength":2000},"answer":{"type":"string","maxLength":4000},"ms":{"type":"integer","minimum":0,"maximum":3600000,"description":"How long the answer took, in milliseconds"},"marks":{"type":"object","properties":{"faithful":{"type":["number","null"],"minimum":0,"maximum":1},"correct":{"type":["number","null"],"minimum":0,"maximum":1},"useful":{"type":["number","null"],"minimum":0,"maximum":1},"expected":{"type":["number","null"],"minimum":0,"maximum":1},"speed":{"type":["number","null"],"minimum":0,"maximum":1}},"description":"The judge's marks, each 0 to 1 or null: faithful to what it read, correct, useful, as expected, fast enough"},"errors":{"type":"array","items":{"type":"string","maxLength":500},"maxItems":20,"default":[]},"traceId":{"type":["string","null"],"maxLength":200}},"required":["questionKey","side","kind","question","answer","ms","marks"]},"minItems":1,"maxItems":300}},"required":["externalId","agent","label","model","thinking","startedAt","finishedAt","summary","items"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"replaced":{"type":"boolean"}},"required":["id","replaced"]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Agent quality"],"summary":"Every organization's agent benchmark runs, newest first, with their summaries","description":"The benchmark runs first-party apps sent, newest first: the organization, the setting (label, model, thinking), when, the summary (items, median and slowest-tenth time, shares right, faithful, useful, judgment) and the gates. Filter by agent, setting label or organization (the one the Cypress-Organization header names when left out, else every one). Cypress staff only: a CM token. Since 1.9.0.","operationId":"list_agent_benchmark_runs","x-cypress-action":"agent_quality.benchmark_runs.list","parameters":[{"name":"agent","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,59}$","description":"Which agent, as the app names it: \"grove-cedar\""},"description":"Which agent, as the app names it: \"grove-cedar\""},{"name":"label","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"One organization's runs"},"description":"One organization's runs"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"At most this many (50 when left out)"},"description":"At most this many (50 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}}},"required":["runs"]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-quality/audit-items":{"post":{"tags":["Agent quality"],"summary":"Send your agent's flagged answers (at most 100) for Cypress staff to review","description":"Puts answers of the app's agent up for review in the organization of the token: each with its question, answer, what it read (in plain words), why it was flagged (`flags`), the model and when it answered. Keyed by `agent` and `externalId`: sending one again only adds flags it did not have; one already decided is never reopened or changed. Answers `{ created, updated, skipped }`. The verdicts come back through list_agent_verdicts. Needs `agent-quality:write` on a first-party app's token (an app Cypress made, such as Grove), for the organization its connection is to. An API key, a partner app, an agent's token and a CM token are refused (403 POLICY_DENIED). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"record_agent_audit_items","x-cypress-action":"agent_quality.audit_items.record","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":200,"description":"The app's own id for it: sending it again updates it, never a second one"},"agent":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,59}$","description":"Which agent, as the app names it: \"grove-cedar\""},"question":{"type":"string","minLength":1,"maxLength":2000},"answer":{"type":"string","maxLength":4000},"reads":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":200,"description":"What it read, in plain words: \"Open offers on the Camry\""},"detail":{"type":["string","null"],"maxLength":500},"n":{"type":["integer","null"],"minimum":0,"description":"How many records"}},"required":["label"]},"maxItems":50,"default":[],"description":"What the agent read to answer"},"flags":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9][a-z0-9:_-]{0,59}$"},"maxItems":20,"default":[],"description":"Why it is up for review: \"check:concise\", \"check:grounded\", \"check:no-claims\", \"corrected\", \"judge:low\", \"sampled\""},"model":{"type":"string","minLength":1,"maxLength":100},"answeredAt":{"type":"string","format":"date-time"},"link":{"type":["string","null"],"maxLength":1000,"format":"uri","description":"Where the answer is in the app (http or https)"}},"required":["externalId","agent","question","answer","model","answeredAt"]},"minItems":1,"maxItems":100}},"required":["items"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"created":{"type":"number"},"updated":{"type":"number"},"skipped":{"type":"number"}},"required":["created","updated","skipped"]},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Agent quality"],"summary":"The answers up for review (OPEN) or already decided, with counts by status","description":"Flagged answers of first-party apps' agents: the organization, the question and answer, what the agent read, the flags, the model and when; once decided, the verdict, the note, the two choices and who decided when. `status` OPEN (the default, newest first), DECIDED (every verdict, newest decision first) or one verdict; filter by organization (the one the Cypress-Organization header names when left out) and by flag. Answers `counts` by status and `facets` (open items by flag and by organization) for the same organization filter, and `nextCursor` for the next page. Cypress staff only: a CM token. Since 1.9.0.","operationId":"list_agent_audit_items","x-cypress-action":"agent_quality.audit_items.list","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["OPEN","DECIDED","RIGHT","WRONG","DISMISSED"]}},{"name":"orgId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"flag","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"description":"At most this many (50 when left out)"},"description":"At most this many (50 when left out)"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The previous answer's nextCursor"},"description":"The previous answer's nextCursor"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"]}},"nextCursor":{"type":["string","null"]}},"required":["items","nextCursor"]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-quality/verdicts":{"get":{"tags":["Agent quality"],"summary":"The verdicts Cypress staff gave on the organization's flagged answers, oldest first, after a time","description":"The audit items of the token's organization that Cypress staff decided after `since`, oldest first: the verdict (RIGHT, WRONG, DISMISSED), the note (with WRONG, what the right answer was), whether to teach the organization (`lessonForOrg`) and to add it to the benchmark set (`makeTestCase`), when and who. Pass the answer's `nextSince` as the next call's `since`; a page never splits verdicts that share a time, so nothing is skipped. A verdict is final: each item appears once. Needs `agent-quality:write` on a first-party app's token (an app Cypress made, such as Grove), for the organization its connection is to. An API key, a partner app, an agent's token and a CM token are refused (403 POLICY_DENIED). Since 1.9.0.","operationId":"list_agent_verdicts","x-cypress-action":"agent_quality.verdicts.list","parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time","description":"Verdicts given after this time (ISO 8601); every verdict when left out"},"description":"Verdicts given after this time (ISO 8601); every verdict when left out"},{"name":"agent","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{0,59}$","description":"Which agent, as the app names it: \"grove-cedar\""},"description":"Which agent, as the app names it: \"grove-cedar\""},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"description":"At most this many (100 when left out)"},"description":"At most this many (100 when left out)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"verdicts":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string"},"verdict":{"type":"string"}},"required":["externalId","verdict"]}},"nextSince":{"type":["string","null"]}},"required":["verdicts","nextSince"]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-quality/benchmark-runs/{id}":{"get":{"tags":["Agent quality"],"summary":"One benchmark run with every question: the answer, its marks, errors and time","description":"One benchmark run as list_agent_benchmark_runs answers it, with its questions in the order sent: the question, its side and kind, the answer, the judge's marks, the errors and the time it took. Cypress staff only: a CM token. Since 1.9.0.","operationId":"get_agent_benchmark_run","x-cypress-action":"agent_quality.benchmark_runs.get","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object","properties":{"run":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}},"required":["run"]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent-quality/audit-items/{id}/verdict":{"post":{"tags":["Agent quality"],"summary":"Right, wrong (with what the right answer was) or dismissed; optionally teach the organization or add it to the benchmark","description":"Decides one open audit item: RIGHT, WRONG (a `note` saying what the right answer was is required) or DISMISSED. `lessonForOrg` asks the app to teach the organization; `makeTestCase` to add the question to its benchmark set (neither applies to DISMISSED). A verdict is final: an item already decided is refused (409 CONFLICT). The app reads it back through list_agent_verdicts. Recorded in the organization's audit trail. Cypress staff only: a CM token. `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"decide_agent_audit_item","x-cypress-action":"agent_quality.audit_items.decide","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"type":"string","enum":["RIGHT","WRONG","DISMISSED"],"description":"RIGHT, WRONG (say what the right answer was in `note`) or DISMISSED (nothing to learn)"},"note":{"type":"string","maxLength":2000,"description":"Required with WRONG: what the right answer was"},"lessonForOrg":{"type":"boolean","description":"Teach the organization: the app makes it a lesson for that organization"},"makeTestCase":{"type":"boolean","description":"Add it to the app's benchmark set"}},"required":["verdict"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"}},"required":["id","status"]}},"required":["item"]},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/huddle/rooms":{"get":{"tags":["Huddle"],"summary":"The rooms you are in (the huddle, channels, direct messages, your room with Cedar, deal lanes), with unread counts, and the ones you may join","description":"Huddle's left rail: every room you are in, each with its unread count and its last message in one line, plus the open channels (and, for a Cypress Manager, the organization's huddle) you may join, and your Inbox's unread count. Use view=mine for every organization at once. Read a room with list_huddle_messages. Needs `huddle:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). Since 1.9.0.","operationId":"list_huddle_rooms","x-cypress-action":"huddle.rooms.list","parameters":[{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["org","mine"],"description":"org: the organization in view (yours; a CM token's Cypress-Organization). mine: every room you are in, in every organization. Default: org when there is one"},"description":"org: the organization in view (yours; a CM token's Cypress-Organization). mine: every room you are in, in every organization. Default: org when there is one"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Huddle"],"summary":"Open a channel in the organization in view: a name people can say, what it is for, private or open","description":"You own the channel and Cedar is in it from the start; the people you name join it too. The name becomes lowercase words joined by dashes (#titles); a name already taken is refused. A private channel is found and read only by the people in it. A CM token needs its Cypress-Organization: a channel belongs to one organization. Needs `huddle:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"create_huddle_channel","x-cypress-action":"huddle.channels.create","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"description":"2 to 40 letters, numbers or dashes once tidied (\"Titles in\" becomes #titles-in)"},"topic":{"type":["string","null"],"maxLength":200,"description":"What it is for, in a line"},"isPrivate":{"type":"boolean","description":"Only the people added find and read it"},"memberIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"maxItems":200,"description":"People and agents of the organization to add now"}},"required":["name"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/huddle/rooms/{roomId}":{"get":{"tags":["Huddle"],"summary":"One room: its name and topic, who is in it, whether you are in it or may join, and who you may add","description":"One room as you may use it: its title (\"Coastal huddle\", \"#titles\"), topic, members (people, Cypress staff, agents), whether you are a member or may join it, and in a channel you may add to, the organization's people you could add (add_huddle_members). A private channel you were not added to answers 403; someone else's room with Cedar, 404. Needs `huddle:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). Since 1.9.0.","operationId":"get_huddle_room","x-cypress-action":"huddle.rooms.get","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The room (list_huddle_rooms gives the ids)"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/huddle/rooms/{roomId}/messages":{"get":{"tags":["Huddle"],"summary":"A room's messages, oldest first (or one thread's replies): text, files, reactions, reply counts and Grove's cards in words","description":"The latest messages of a room (up to 100), oldest first; `before` (a time) pages back, `thread` (a message id) reads that message's replies. Each message has its author (a person, Cypress staff or an agent), its text, files (links that open for a member), reactions, its reply count, and when Grove posted a card (an offer, a closing, a task), the card and `cardSummary`, the card in words. An open room you may join reads before you join. Needs `huddle:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). Since 1.9.0.","operationId":"list_huddle_messages","x-cypress-action":"huddle.messages.list","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The room (list_huddle_rooms gives the ids)"}},{"name":"thread","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"A message id: read its thread's replies instead"},"description":"A message id: read its thread's replies instead"},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time","description":"Only messages sent before this time (ISO 8601): the next page back"},"description":"Only messages sent before this time (ISO 8601): the next page back"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"description":"How many (default 50, at most 100)"},"description":"How many (default 50, at most 100)"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Huddle"],"summary":"Post a message in a room you are in, or reply in a thread (parentId)","description":"Posts as you. Mentioning someone (@Sam, the first name, or the whole name without spaces when two share it) puts it in their Inbox; mentioning @Cedar gets Cedar's answer in the room; mentioning the organization's Cypress Manager adds them to the room. Join an open room first (join_huddle_room). Up to 4,000 characters. Needs `huddle:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"post_huddle_message","x-cypress-action":"huddle.messages.post","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The room (list_huddle_rooms gives the ids)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":4000},"parentId":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"A message of the room: post as a reply in its thread"}},"required":["body"]}}}},"responses":{"200":{"description":"With ?dryRun=true: what it would do","content":{"application/json":{"schema":{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}}}},"201":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/huddle/messages/{messageId}":{"patch":{"tags":["Huddle"],"summary":"Change the text of your own message, within a day of sending it","description":"Your own message only, within 24 hours, and never a card or a line the room wrote (someone joined). Mentions are read again from the new text. The room sees it marked \"edited\". Needs `huddle:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"edit_huddle_message","x-cypress-action":"huddle.messages.edit","parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The message"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","maxLength":4000}},"required":["body"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Huddle"],"summary":"Delete your own message: its text and files go for everyone; a line says it was deleted","description":"Your own message only. Its text, files and reactions go for everyone and cannot be brought back; the room keeps a \"Message deleted\" line where it was, and its thread stays. Needs `huddle:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"delete_huddle_message","x-cypress-action":"huddle.messages.delete","parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The message"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/huddle/messages/{messageId}/reactions":{"post":{"tags":["Huddle"],"summary":"Add your reaction to a message, or take it back (thumbs, check, heart, eye, question, spark)","description":"Toggles your reaction: added if you had not given it, taken back if you had (`added` says which). Anyone in the room. Six reactions, drawn as icons: thumbs, check, heart, eye, question, spark. Needs `huddle:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"react_to_huddle_message","x-cypress-action":"huddle.reactions.toggle","parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The message"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["thumbs","check","heart","eye","question","spark"]}},"required":["kind"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/huddle/messages/{messageId}/pin":{"post":{"tags":["Huddle"],"summary":"Pin a message or card to its conversation, or unpin it: anyone in the room, up to 50 pins per room","description":"Anyone in the room pins a message or a card (not a line the room wrote, not a deleted message), and anyone unpins it. A pin says so in the room (\"Dana pinned a message\"); an unpin is quiet. Pins show above the conversation in Cypress and Grove, oldest first; a room about one thing (a car, Reports) has its own card as its first pin. A room holds 50 pins. Needs `huddle:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"pin_huddle_message","x-cypress-action":"huddle.messages.pin","parameters":[{"name":"messageId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The message"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pinned":{"type":"boolean","description":"true pins it, false unpins it"}},"required":["pinned"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/huddle/rooms/{roomId}/pins":{"get":{"tags":["Huddle"],"summary":"The messages and cards pinned to a conversation, oldest pin first","description":"What the room's people pinned to it, oldest pin first: each a message as list_huddle_messages gives it (cards with `cardSummary`), with `pinned` (when, and who pinned it). A room about one thing (a car, Reports) has its own card as its first pin unless someone unpinned it. Only for someone in the room. Needs `huddle:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). Since 1.9.0.","operationId":"list_huddle_pins","x-cypress-action":"huddle.pins.list","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The room (list_huddle_rooms gives the ids)"}}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/huddle/rooms/{roomId}/join":{"post":{"tags":["Huddle"],"summary":"Join your organization's huddle or an open channel (a Cypress Manager: any customer organization's); the room hears you joined","description":"A person joins their own organization's huddle or an open channel; a Cypress Manager may join any customer organization's huddle or open channel at any time, and the room reads \"<name> from Cypress joined\". A private channel is by invitation only (someone in it adds you). Already a member: nothing changes. Needs `huddle:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"join_huddle_room","x-cypress-action":"huddle.rooms.join","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The room (list_huddle_rooms gives the ids)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/huddle/direct":{"post":{"tags":["Huddle"],"summary":"Open a private conversation with one person of the organization (one of its people, or its Cypress Manager)","description":"One private room per pair, made the first time and the same room after that (`created` says which). Never with an agent (an agent has its own room with each person). Every message in it reaches the other person's Inbox. Then post in it with post_huddle_message; list_huddle_rooms lists it as kind DIRECT, named for the other person. Needs `huddle:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"open_huddle_direct","x-cypress-action":"huddle.direct.open","parameters":[{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"personId":{"type":"string","minLength":1,"maxLength":64,"description":"The person to write to (get_huddle_room or list_members give the ids)"}},"required":["personId"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/huddle/rooms/{roomId}/members":{"post":{"tags":["Huddle"],"summary":"Add people or agents of the organization to a channel (in a private one, its owner or an admin)","description":"Anyone in an open channel may add the organization's people and agents; in a private channel, its owner or the organization's admins. The channel reads who added whom. get_huddle_room lists who you may add. Needs `huddle:write`; takes an API key, a Connect Cypress token or a CM token acting for the organization. Not for an agent's token (403 PEOPLE_ONLY). Not for an API key (a person's act). `?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met. Since 1.9.0.","operationId":"add_huddle_members","x-cypress-action":"huddle.members.add","parameters":[{"name":"roomId","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":64,"description":"The room (list_huddle_rooms gives the ids)"}},{"name":"dryRun","in":"query","schema":{"type":"boolean"},"description":"`?dryRun=true` checks the caller, the input and the record and answers `{ dryRun: true, simulated: true, would }` without running it: a rule met only when it runs is not met."},{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200},"description":"A retry with the same key and body gets the first answer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"personIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":50}},"required":["personIds"]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"oneOf":[{"type":"object"},{"type":"object","properties":{"dryRun":{"type":"boolean","const":true},"simulated":{"type":"boolean"},"would":{}},"required":["dryRun"]}]}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/huddle/inbox":{"get":{"tags":["Huddle"],"summary":"What needs you, newest first: direct messages, mentions, offers, matches, closings, tasks handed to you, what Cedar needs","description":"The same notices Grove and Cypress show in the Inbox, newest first (up to 60), each with its kind (OFFER, MATCH, CEDAR, CLOSING, TEAM, DIRECT), title, words, whether it is read, and where it opens (`href` in Cypress for a room or thread, else `grove`). Needs `huddle:read`; takes an API key, a Connect Cypress token or a CM token acting for the organization. An agent's token may run it. Not for an API key (a person's act). Since 1.9.0.","operationId":"list_huddle_inbox","x-cypress-action":"huddle.inbox.list","parameters":[{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["org","mine"],"description":"org: the organization in view (yours; a CM token's Cypress-Organization). mine: every room you are in, in every organization. Default: org when there is one"},"description":"org: the organization in view (yours; a CM token's Cypress-Organization). mine: every room you are in, in every organization. Default: org when there is one"}],"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, malformed, or revoked credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"code ORG_NOT_ACTIVE, SCOPE_MISSING, a product the organization lacks, PEOPLE_ONLY (an agent, or a person's act), POLICY_DENIED (a rule, or a staff action without a CM token), BELOW_FLOOR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found (another organization's record answers the same)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"code CONFLICT: the record is not in a state that allows it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed, or code INVALID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}