{ "openapi": "3.1.0", "info": { "title": "Ridekick API", "version": "2026-10-13", "description": "A buyer's own requests and offers, read with the buyer's signed-in Ridekick session or with the access token a buyer gave an assistant she approved. No API key is accepted." }, "paths": { "/api/v1/deal-sets": { "get": { "operationId": "list-deal-sets", "summary": "The signed-in buyer's requests, one summary each.", "description": "Each entry has a `kind`, a closed set: `deal_set` or `single`. A client MUST skip an entry whose `kind` it does not know. A `single` entry's `id` is a price-check id, not a deal-set id. `GET /api/v1/deal-sets/{id}` does not accept it and answers its normal 404. To read everything, call with `since=1970-01-01T00:00:00Z`, then repeat with `since` set to the `Ridekick-As-Of` you got, until `Ridekick-More` is `false`. An entry can appear on more than one page. Keep one entry per id and `kind`. `section` is where the buyer's page places the request: `ready` is a request the dealership finished and sent an offer for, `in_progress` is one still active (it may already hold a written price), `inactive` is one off the page. Whether a written price exists is `lowestWrittenOtdCents` (not null), whatever the section. On a `since` call, an assistant whose buyer was granted it also gets a `changes` object on each entry, saying WHAT changed: `hasWrittenPrice` (a state: the request has a price in writing; it does not say when it became written), `newReplies` (`none`, `new` with a count and the time we received the most recent one, or `could_not_check`; never what a reply said) and `ended` (a state, never a time). Anyone else gets exactly the entry described above. A plain call never has `changes`. A plain call (no `since`) returns the buyer's ACTIVE requests: the grid requests that have not ended (up to 12) and the newest 25 requests to one dealership that are not inactive. `Ridekick-More` is `true` only when an active request was left out. Ended (inactive) requests, including a request whose price is not in writing, come only by paging with `since`.", "x-ridekick-availability": "available", "x-ridekick-principals": [ "buyer_session", "delegated_agent" ], "x-ridekick-rate-limit": { "class": "read", "limit": 120, "windowSeconds": 60 }, "x-ridekick-deadline-ms": 8000, "x-ridekick-deadline-cancels-read": true, "x-ridekick-rollout-flag": "API_V1_DEAL_SETS", "x-ridekick-list-bounds": { "maxItems": 4, "itemDeadlineMs": 4000 }, "security": [ { "oauth2": [ "offers:read" ] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "description": "Optional. An ISO 8601 time with a time zone, for example `2026-10-06T17:00:00Z`. Only requests with activity after that time are returned. This is a poll: it does not notify you. To read everything, start with `1970-01-01T00:00:00Z`. A value that is not in this form is refused with `invalid_request`, never answered with an empty list.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } }, "Ridekick-As-Of": { "description": "Sent only when `since` was sent. The time to pass as `since` on your next call. It is set slightly before this read began, so an entry can come back twice but is never skipped.", "schema": { "type": "string", "format": "date-time" } }, "Ridekick-More": { "description": "Sent on every successful list answer. On a plain call `true` means an ACTIVE request was left out (ended ones are never counted: they come only with `since`). On a `since` page it means more entries remain. If that cannot be told, it is `true`. Keep reading until it is `false`.", "schema": { "type": "string", "enum": [ "true", "false" ] } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "description": "Which kind of entry this is: `deal_set` or `single`. A client MUST skip an entry whose kind it does not know.", "type": "string", "const": "deal_set" }, "dealSetId": { "type": "string" }, "href": { "description": "Our website's path for this set.", "x-ridekick-display-text": true, "type": "string" }, "car": { "type": "object", "properties": { "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "make": { "type": "string" }, "model": { "type": "string" }, "trim": { "description": "A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exteriorColor": { "description": "A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "interiorColor": { "description": "A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "drivetrain": { "description": "A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "powertrain": { "description": "A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "year", "make", "model", "trim", "exteriorColor", "interiorColor", "drivetrain", "powertrain" ] }, "buyerZip": { "description": "The buyer's own search ZIP (the same value as the results' `search.buyerZip`), returned only to the buyer's own session. Null for an AI assistant acting for the buyer.", "x-ridekick-pii": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dealerCount": { "description": "How many dealerships the search found for this set. Null for an AI assistant acting for the buyer (the count is third-party listing data). Counts of dealers who wrote back stay.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "summary": { "type": "object", "properties": { "written": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "waiting": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "differentCar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ended": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "endedWithPrice": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "closedWithPrice": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "written", "waiting", "differentCar", "ended", "endedWithPrice", "closedWithPrice" ] }, "lowestWrittenOtdCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lowestWrittenDistanceMiles": { "description": "Distance from the buyer ZIP in miles (third-party listing data). It is the hero row's distance, so before that dealership is unlocked or chosen it is the LOWER BOUND of the distance band (0, 10, 25, 50 or 100), not the distance; after, the exact distance. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "needsYou": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "chosenLabels": { "description": "The dealers the buyer has chosen, as labels. For a connected assistant (a delegated agent) each is a description of the car (colour, year, model, trim, miles to the nearest 100, listed price), never the dealership's name; the buyer's own session sees the name once she has chosen. Display text: its words may change, and two entries can read the same.", "x-ridekick-display-text": true, "type": "array", "items": { "type": "string" } }, "section": { "description": "Where the buyer's page places the request: `ready` = the dealership finished and sent an offer, `in_progress` = still active (it may already hold a written price), `inactive` = off the page. Whether a written price exists is `lowestWrittenOtdCents` (not null), whatever the section.", "type": "string", "enum": [ "ready", "in_progress", "inactive" ] }, "memberIds": { "type": "array", "items": { "type": "string" } }, "latestActivityAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changes": { "description": "What changed on this request since `since`. Only on a `since` call, and only for an account that was granted it.", "type": "object", "properties": { "hasWrittenPrice": { "description": "True when this request has a price in writing. A STATE, not an event: it does not say when the price became written, and it can be true on a request that was already written before `since`.", "type": "boolean" }, "newReplies": { "description": "Dealership replies on this request after `since`: `none`, `new` (a count and a time) or `could_not_check` (the request could not be read just now; it is NOT the same as none).", "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "none" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "new" }, "count": { "description": "How many dealership replies arrived after `since`. A number only: never what a reply said.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "latestAt": { "description": "When the most recent of them arrived (a time with a time zone, our own receipt time).", "type": "string" } }, "required": [ "status", "count", "latestAt" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "could_not_check" } }, "required": [ "status" ] } ] }, "ended": { "description": "True when this request has ended. A STATE, not an event: it carries no time and does not mean it ended after `since`.", "type": "boolean" } }, "required": [ "hasWrittenPrice", "newReplies", "ended" ] } }, "required": [ "kind", "dealSetId", "href", "car", "buyerZip", "dealerCount", "summary", "lowestWrittenOtdCents", "lowestWrittenDistanceMiles", "needsYou", "chosenLabels", "section", "memberIds", "latestActivityAt" ] }, { "type": "object", "properties": { "kind": { "description": "Which kind of entry this is: `deal_set` or `single`. A client MUST skip an entry whose kind it does not know.", "type": "string", "const": "single" }, "id": { "description": "This request's own id. It is a PRICE-CHECK id, not a deal-set id: GET /api/v1/deal-sets/{id} does not accept it.", "type": "string" }, "car": { "type": "object", "properties": { "year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "make": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trim": { "description": "A trim read from the listing, not from the buyer's own choice. Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "year", "make", "model", "trim" ] }, "dealerLabel": { "description": "The dealership. For a connected assistant (a delegated agent) it is a description of the car (year, model, trim), never the dealership's name; for the buyer's own session it is the name, or null when the buyer has not seen it yet. Display text: its words may change.", "x-ridekick-display-text": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "section": { "description": "Where the buyer's page places the request: `ready` = the dealership finished and sent an offer, `in_progress` = still active (it may already hold a written price), `inactive` = off the page. Whether a written price exists is `lowestWrittenOtdCents` (not null), whatever the section.", "type": "string", "enum": [ "ready", "in_progress", "inactive" ] }, "lowestWrittenOtdCents": { "description": "The dealer's written out-the-door price in integer US cents, only when it is in writing; null otherwise. Same meaning as on a deal-set entry.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "needsYou": { "description": "1 when the dealer asked the buyer something and is waiting, else 0.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "latestActivityAt": { "description": "The newest time this request changed (a time with a time zone), or null when none is known.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changes": { "description": "What changed on this request since `since`. Only on a `since` call, and only for an account that was granted it.", "type": "object", "properties": { "hasWrittenPrice": { "description": "True when this request has a price in writing. A STATE, not an event: it does not say when the price became written, and it can be true on a request that was already written before `since`.", "type": "boolean" }, "newReplies": { "description": "Dealership replies on this request after `since`: `none`, `new` (a count and a time) or `could_not_check` (the request could not be read just now; it is NOT the same as none).", "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "none" } }, "required": [ "status" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "new" }, "count": { "description": "How many dealership replies arrived after `since`. A number only: never what a reply said.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "latestAt": { "description": "When the most recent of them arrived (a time with a time zone, our own receipt time).", "type": "string" } }, "required": [ "status", "count", "latestAt" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "could_not_check" } }, "required": [ "status" ] } ] }, "ended": { "description": "True when this request has ended. A STATE, not an event: it carries no time and does not mean it ended after `since`.", "type": "boolean" } }, "required": [ "hasWrittenPrice", "newReplies", "ended" ] } }, "required": [ "kind", "id", "car", "dealerLabel", "section", "lowestWrittenOtdCents", "needsYou", "latestActivityAt" ] } ] } } } } } } }, "400": { "description": "`invalid_request`: The request body or a header failed validation. An out-of-range value is refused, not adjusted: what you asked is never silently changed.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_request" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } }, "401": { "description": "`unauthenticated`: Signed out, or the credential was not accepted: an access token that is not valid, or an Authorization header that is not a Ridekick access token.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } }, "WWW-Authenticate": { "description": "A bearer challenge: `Bearer error=\"invalid_token\"`, or `Bearer error=\"insufficient_scope\", scope=\"\"`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } }, "403": { "description": "`insufficient_scope`: The credential does not include the scope this endpoint needs. The WWW-Authenticate header names the required scope.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } }, "WWW-Authenticate": { "description": "A bearer challenge: `Bearer error=\"invalid_token\"`, or `Bearer error=\"insufficient_scope\", scope=\"\"`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "insufficient_scope" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } }, "404": { "description": "`not_found`: No such resource, or not yours. Also answered while the endpoint is not turned on for you. Never 403: whether another buyer's resource exists is not disclosed.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } }, "429": { "description": "`rate_limited`: Too many requests from this principal in the window.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } }, "500": { "description": "`internal`: Something failed on our side. The response carries no data.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } }, "503": { "description": "`auth_unverifiable`: Sign-in could not be confirmed. This is not the same as signed out. `unavailable`: The service did not answer right now, so nothing was returned or sent. Try again in a moment, and wait the number of seconds in `Retry-After` when it is present.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } }, "Retry-After": { "description": "Seconds to wait before retrying. Present on `unavailable` when the service can say; when it is absent, back off.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "auth_unverifiable", "unavailable" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } } } } }, "/api/v1/deal-sets/{id}": { "get": { "operationId": "get-deal-set", "summary": "One request's ranked results.", "x-ridekick-availability": "available", "x-ridekick-principals": [ "buyer_session", "delegated_agent" ], "x-ridekick-rate-limit": { "class": "read", "limit": 120, "windowSeconds": 60 }, "x-ridekick-deadline-ms": 8000, "x-ridekick-deadline-cancels-read": true, "x-ridekick-rollout-flag": "API_V1_DEAL_SETS", "x-ridekick-list-bounds": null, "security": [ { "oauth2": [ "offers:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The request's id, its `dealSetId` (a uuid). Anything else is `not_found`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "dealSetId": { "type": "string" }, "car": { "type": "object", "properties": { "year": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "make": { "type": "string" }, "model": { "type": "string" }, "trim": { "description": "A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exteriorColor": { "description": "A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "interiorColor": { "description": "A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "drivetrain": { "description": "A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "powertrain": { "description": "A configuration value the posted configuration may hold without the buyer choosing it (a default, an auto-fill, a pasted link). Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "year", "make", "model", "trim", "exteriorColor", "interiorColor", "drivetrain", "powertrain" ] }, "search": { "type": "object", "properties": { "buyerZip": { "description": "The buyer's own search ZIP, returned only to the buyer's own session. Null for an AI assistant acting for the buyer.", "x-ridekick-pii": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "radiusMiles": { "description": "The search radius in miles around the buyer's ZIP: 100 on the site, 250 when the buyer chose Search further out, or the value an API caller requested. Null for an AI assistant acting for the buyer, or when unknown.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "buyerZip", "radiusMiles" ] }, "counts": { "type": "object", "properties": { "written": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "waiting": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "differentCar": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ended": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "endedWithPrice": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "closedWithPrice": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "description": "How many dealerships the search found for this set. Null for an AI assistant acting for the buyer (the count is third-party listing data). Counts of dealers who wrote back stay.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "needsYou": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "written", "waiting", "differentCar", "ended", "endedWithPrice", "closedWithPrice", "total", "needsYou" ] }, "headerLine": { "description": "One-line summary of the set, for display. Null for an AI assistant acting for the buyer: the line states how many dealers the set holds, which is third-party listing data.", "x-ridekick-display-text": true, "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hero": { "anyOf": [ { "type": "object", "properties": { "rowKey": { "type": "string" }, "label": { "description": "Display label for the lowest written price's row.", "x-ridekick-display-text": true, "type": "string" }, "otdCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sellingPriceCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "taxesAndFeesCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "listedAtCents": { "description": "The list price of the listing in integer cents (third-party listing data). It is the listed price, never an offer or a written price. Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "writtenAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "distanceMiles": { "description": "Distance from the buyer ZIP in miles (third-party listing data). Before the dealership is unlocked this is the LOWER BOUND of the distance band (0, 10, 25, 50 or 100), not the distance: read `distanceBand`. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "distanceBand": { "description": "The distance band as words: Under 10 miles, 10 to 25 miles, 25 to 50 miles, 50 to 100 miles or Over 100 miles (third-party listing data). Always the band, never an exact distance. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "trim": { "description": "A trim read from the listing, not from the buyer choice (third-party listing data). Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gapToNextCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "canChoose": { "description": "True once this row may be chosen: it has been unlocked (the dealer is no longer hidden), not yet chosen, a written price for the same car, not archived. See the versioning changelog for how this field changed meaning.", "type": "boolean" }, "canUnlock": { "description": "True while the dealer is STILL hidden on this row: a written price for the same car, not archived. False once the row has been unlocked (or chosen). See the versioning changelog for how this field relates to `canChoose`.", "type": "boolean" }, "chosen": { "type": "boolean" } }, "required": [ "rowKey", "label", "otdCents", "sellingPriceCents", "taxesAndFeesCents", "listedAtCents", "writtenAt", "distanceMiles", "distanceBand", "trim", "gapToNextCents", "canChoose", "canUnlock", "chosen" ] }, { "type": "null" } ] }, "ranked": { "type": "array", "items": { "type": "object", "properties": { "trim": { "description": "A trim read from the listing, not from the buyer choice (third-party listing data). Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rows": { "type": "array", "items": { "type": "object", "properties": { "rowKey": { "type": "string" }, "label": { "description": "Display label for the row. A connected assistant (a delegated agent) ALWAYS gets a description of the car: colour, year, model, trim, miles to the nearest 100 and the listed price, a part we do not have left out, never the dealership's name. Two rows can read the same: refer to a row by `rowKey`. Its words may change; never branch on it. The buyer's own session sees the label her page shows and the dealership's name once she has unlocked or chosen it.", "x-ridekick-display-text": true, "type": "string" }, "hidden": { "type": "boolean" }, "chosen": { "type": "boolean" }, "archived": { "type": "boolean" }, "state": { "type": "string", "enum": [ "written", "waiting", "different_car", "ended" ] }, "ended": { "anyOf": [ { "type": "string", "enum": [ "sold", "closed_with_price", "no_price", "timed_out" ] }, { "type": "null" } ] }, "statusLabel": { "description": "The row's status in words. Branch on `state` and `ended`, not on this.", "x-ridekick-display-text": true, "type": "string" }, "otdCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sellingPriceCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "listedAtCents": { "description": "The list price of the listing in integer cents (third-party listing data). It is the listed price, never an offer or a written price. Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "writtenAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gapToLowestCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "canChoose": { "description": "True once this row may be chosen: it has been unlocked (the dealer is no longer hidden), not yet chosen, a written price for the same car, not archived. See the versioning changelog for how this field changed meaning.", "type": "boolean" }, "canUnlock": { "description": "True while the dealer is STILL hidden on this row: a written price for the same car, not archived. False once the row has been unlocked (or chosen). See the versioning changelog for how this field relates to `canChoose`.", "type": "boolean" }, "quotedTrim": { "description": "A trim read from the listing, not from the buyer choice (third-party listing data). Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "distanceMiles": { "description": "Distance from the buyer ZIP in miles (third-party listing data). Before the dealership is unlocked this is the LOWER BOUND of the distance band (0, 10, 25, 50 or 100), not the distance: read `distanceBand`. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "distanceBand": { "description": "The distance band as words: Under 10 miles, 10 to 25 miles, 25 to 50 miles, 50 to 100 miles or Over 100 miles (third-party listing data). Always the band, never an exact distance. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceCheckHref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isVerifiedPartner": { "description": "True when this dealership is a Verified partner: it pays Ridekick a subscription and has agreed to honor its written price while the car is available, if the buyer qualifies for any rebates, incentives or financing in that price. Always present in answers to builders, and may be omitted from answers to hosted assistants; false means either that the dealership is not a partner or that its status is not shown for this row yet, so don't present false as \"not a partner\", and show the conditions above wherever you show true.", "type": "boolean" } }, "required": [ "rowKey", "label", "hidden", "chosen", "archived", "state", "ended", "statusLabel", "otdCents", "sellingPriceCents", "listedAtCents", "writtenAt", "gapToLowestCents", "canChoose", "canUnlock", "quotedTrim", "distanceMiles", "distanceBand", "priceCheckHref", "isVerifiedPartner" ] } } }, "required": [ "trim", "rows" ] } }, "needsYou": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "question" }, "rowKey": { "type": "string" }, "label": { "description": "Display label for the row the question is about.", "x-ridekick-display-text": true, "type": "string" }, "promptId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "type": "string" }, "heading": { "description": "Short heading for the question.", "x-ridekick-display-text": true, "type": "string" }, "question": { "description": "The dealer's question in words, or null. Null for an AI assistant acting for the buyer.", "x-ridekick-display-text": true, "x-ridekick-pii": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "answerMode": { "type": "string" }, "otdCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "kind", "rowKey", "label", "promptId", "category", "heading", "question", "answerMode", "otdCents" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "draft" }, "rowKey": { "type": "string" }, "label": { "description": "Display label for the row the draft is for.", "x-ridekick-display-text": true, "type": "string" }, "requestId": { "type": "string" }, "preview": { "description": "Opening of the reply waiting for the buyer, or null. Null for an AI assistant acting for the buyer.", "x-ridekick-display-text": true, "x-ridekick-pii": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "previewComplete": { "description": "True only when `preview` is the whole reply. False when `preview` shows only part of it, or is null.", "type": "boolean" } }, "required": [ "kind", "rowKey", "label", "requestId", "preview" ] } ] } }, "everyoneElse": { "type": "object", "properties": { "waiting": { "type": "array", "items": { "type": "object", "properties": { "rowKey": { "type": "string" }, "label": { "description": "Display label for the row. A connected assistant (a delegated agent) ALWAYS gets a description of the car: colour, year, model, trim, miles to the nearest 100 and the listed price, a part we do not have left out, never the dealership's name. Two rows can read the same: refer to a row by `rowKey`. Its words may change; never branch on it. The buyer's own session sees the label her page shows and the dealership's name once she has unlocked or chosen it.", "x-ridekick-display-text": true, "type": "string" }, "hidden": { "type": "boolean" }, "chosen": { "type": "boolean" }, "archived": { "type": "boolean" }, "state": { "type": "string", "enum": [ "written", "waiting", "different_car", "ended" ] }, "ended": { "anyOf": [ { "type": "string", "enum": [ "sold", "closed_with_price", "no_price", "timed_out" ] }, { "type": "null" } ] }, "statusLabel": { "description": "The row's status in words. Branch on `state` and `ended`, not on this.", "x-ridekick-display-text": true, "type": "string" }, "otdCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sellingPriceCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "listedAtCents": { "description": "The list price of the listing in integer cents (third-party listing data). It is the listed price, never an offer or a written price. Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "writtenAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gapToLowestCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "canChoose": { "description": "True once this row may be chosen: it has been unlocked (the dealer is no longer hidden), not yet chosen, a written price for the same car, not archived. See the versioning changelog for how this field changed meaning.", "type": "boolean" }, "canUnlock": { "description": "True while the dealer is STILL hidden on this row: a written price for the same car, not archived. False once the row has been unlocked (or chosen). See the versioning changelog for how this field relates to `canChoose`.", "type": "boolean" }, "quotedTrim": { "description": "A trim read from the listing, not from the buyer choice (third-party listing data). Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "distanceMiles": { "description": "Distance from the buyer ZIP in miles (third-party listing data). Before the dealership is unlocked this is the LOWER BOUND of the distance band (0, 10, 25, 50 or 100), not the distance: read `distanceBand`. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "distanceBand": { "description": "The distance band as words: Under 10 miles, 10 to 25 miles, 25 to 50 miles, 50 to 100 miles or Over 100 miles (third-party listing data). Always the band, never an exact distance. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceCheckHref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isVerifiedPartner": { "description": "True when this dealership is a Verified partner: it pays Ridekick a subscription and has agreed to honor its written price while the car is available, if the buyer qualifies for any rebates, incentives or financing in that price. Always present in answers to builders, and may be omitted from answers to hosted assistants; false means either that the dealership is not a partner or that its status is not shown for this row yet, so don't present false as \"not a partner\", and show the conditions above wherever you show true.", "type": "boolean" } }, "required": [ "rowKey", "label", "hidden", "chosen", "archived", "state", "ended", "statusLabel", "otdCents", "sellingPriceCents", "listedAtCents", "writtenAt", "gapToLowestCents", "canChoose", "canUnlock", "quotedTrim", "distanceMiles", "distanceBand", "priceCheckHref", "isVerifiedPartner" ] } }, "differentCar": { "type": "array", "items": { "type": "object", "properties": { "rowKey": { "type": "string" }, "label": { "description": "Display label for the row. A connected assistant (a delegated agent) ALWAYS gets a description of the car: colour, year, model, trim, miles to the nearest 100 and the listed price, a part we do not have left out, never the dealership's name. Two rows can read the same: refer to a row by `rowKey`. Its words may change; never branch on it. The buyer's own session sees the label her page shows and the dealership's name once she has unlocked or chosen it.", "x-ridekick-display-text": true, "type": "string" }, "hidden": { "type": "boolean" }, "chosen": { "type": "boolean" }, "archived": { "type": "boolean" }, "state": { "type": "string", "enum": [ "written", "waiting", "different_car", "ended" ] }, "ended": { "anyOf": [ { "type": "string", "enum": [ "sold", "closed_with_price", "no_price", "timed_out" ] }, { "type": "null" } ] }, "statusLabel": { "description": "The row's status in words. Branch on `state` and `ended`, not on this.", "x-ridekick-display-text": true, "type": "string" }, "otdCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sellingPriceCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "listedAtCents": { "description": "The list price of the listing in integer cents (third-party listing data). It is the listed price, never an offer or a written price. Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "writtenAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gapToLowestCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "canChoose": { "description": "True once this row may be chosen: it has been unlocked (the dealer is no longer hidden), not yet chosen, a written price for the same car, not archived. See the versioning changelog for how this field changed meaning.", "type": "boolean" }, "canUnlock": { "description": "True while the dealer is STILL hidden on this row: a written price for the same car, not archived. False once the row has been unlocked (or chosen). See the versioning changelog for how this field relates to `canChoose`.", "type": "boolean" }, "quotedTrim": { "description": "A trim read from the listing, not from the buyer choice (third-party listing data). Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "distanceMiles": { "description": "Distance from the buyer ZIP in miles (third-party listing data). Before the dealership is unlocked this is the LOWER BOUND of the distance band (0, 10, 25, 50 or 100), not the distance: read `distanceBand`. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "distanceBand": { "description": "The distance band as words: Under 10 miles, 10 to 25 miles, 25 to 50 miles, 50 to 100 miles or Over 100 miles (third-party listing data). Always the band, never an exact distance. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceCheckHref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isVerifiedPartner": { "description": "True when this dealership is a Verified partner: it pays Ridekick a subscription and has agreed to honor its written price while the car is available, if the buyer qualifies for any rebates, incentives or financing in that price. Always present in answers to builders, and may be omitted from answers to hosted assistants; false means either that the dealership is not a partner or that its status is not shown for this row yet, so don't present false as \"not a partner\", and show the conditions above wherever you show true.", "type": "boolean" } }, "required": [ "rowKey", "label", "hidden", "chosen", "archived", "state", "ended", "statusLabel", "otdCents", "sellingPriceCents", "listedAtCents", "writtenAt", "gapToLowestCents", "canChoose", "canUnlock", "quotedTrim", "distanceMiles", "distanceBand", "priceCheckHref", "isVerifiedPartner" ] } }, "ended": { "type": "array", "items": { "type": "object", "properties": { "rowKey": { "type": "string" }, "label": { "description": "Display label for the row. A connected assistant (a delegated agent) ALWAYS gets a description of the car: colour, year, model, trim, miles to the nearest 100 and the listed price, a part we do not have left out, never the dealership's name. Two rows can read the same: refer to a row by `rowKey`. Its words may change; never branch on it. The buyer's own session sees the label her page shows and the dealership's name once she has unlocked or chosen it.", "x-ridekick-display-text": true, "type": "string" }, "hidden": { "type": "boolean" }, "chosen": { "type": "boolean" }, "archived": { "type": "boolean" }, "state": { "type": "string", "enum": [ "written", "waiting", "different_car", "ended" ] }, "ended": { "anyOf": [ { "type": "string", "enum": [ "sold", "closed_with_price", "no_price", "timed_out" ] }, { "type": "null" } ] }, "statusLabel": { "description": "The row's status in words. Branch on `state` and `ended`, not on this.", "x-ridekick-display-text": true, "type": "string" }, "otdCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sellingPriceCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "listedAtCents": { "description": "The list price of the listing in integer cents (third-party listing data). It is the listed price, never an offer or a written price. Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "writtenAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gapToLowestCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "canChoose": { "description": "True once this row may be chosen: it has been unlocked (the dealer is no longer hidden), not yet chosen, a written price for the same car, not archived. See the versioning changelog for how this field changed meaning.", "type": "boolean" }, "canUnlock": { "description": "True while the dealer is STILL hidden on this row: a written price for the same car, not archived. False once the row has been unlocked (or chosen). See the versioning changelog for how this field relates to `canChoose`.", "type": "boolean" }, "quotedTrim": { "description": "A trim read from the listing, not from the buyer choice (third-party listing data). Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "distanceMiles": { "description": "Distance from the buyer ZIP in miles (third-party listing data). Before the dealership is unlocked this is the LOWER BOUND of the distance band (0, 10, 25, 50 or 100), not the distance: read `distanceBand`. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "distanceBand": { "description": "The distance band as words: Under 10 miles, 10 to 25 miles, 25 to 50 miles, 50 to 100 miles or Over 100 miles (third-party listing data). Always the band, never an exact distance. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceCheckHref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isVerifiedPartner": { "description": "True when this dealership is a Verified partner: it pays Ridekick a subscription and has agreed to honor its written price while the car is available, if the buyer qualifies for any rebates, incentives or financing in that price. Always present in answers to builders, and may be omitted from answers to hosted assistants; false means either that the dealership is not a partner or that its status is not shown for this row yet, so don't present false as \"not a partner\", and show the conditions above wherever you show true.", "type": "boolean" } }, "required": [ "rowKey", "label", "hidden", "chosen", "archived", "state", "ended", "statusLabel", "otdCents", "sellingPriceCents", "listedAtCents", "writtenAt", "gapToLowestCents", "canChoose", "canUnlock", "quotedTrim", "distanceMiles", "distanceBand", "priceCheckHref", "isVerifiedPartner" ] } }, "archived": { "type": "array", "items": { "type": "object", "properties": { "rowKey": { "type": "string" }, "label": { "description": "Display label for the row. A connected assistant (a delegated agent) ALWAYS gets a description of the car: colour, year, model, trim, miles to the nearest 100 and the listed price, a part we do not have left out, never the dealership's name. Two rows can read the same: refer to a row by `rowKey`. Its words may change; never branch on it. The buyer's own session sees the label her page shows and the dealership's name once she has unlocked or chosen it.", "x-ridekick-display-text": true, "type": "string" }, "hidden": { "type": "boolean" }, "chosen": { "type": "boolean" }, "archived": { "type": "boolean" }, "state": { "type": "string", "enum": [ "written", "waiting", "different_car", "ended" ] }, "ended": { "anyOf": [ { "type": "string", "enum": [ "sold", "closed_with_price", "no_price", "timed_out" ] }, { "type": "null" } ] }, "statusLabel": { "description": "The row's status in words. Branch on `state` and `ended`, not on this.", "x-ridekick-display-text": true, "type": "string" }, "otdCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sellingPriceCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "listedAtCents": { "description": "The list price of the listing in integer cents (third-party listing data). It is the listed price, never an offer or a written price. Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "writtenAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gapToLowestCents": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "canChoose": { "description": "True once this row may be chosen: it has been unlocked (the dealer is no longer hidden), not yet chosen, a written price for the same car, not archived. See the versioning changelog for how this field changed meaning.", "type": "boolean" }, "canUnlock": { "description": "True while the dealer is STILL hidden on this row: a written price for the same car, not archived. False once the row has been unlocked (or chosen). See the versioning changelog for how this field relates to `canChoose`.", "type": "boolean" }, "quotedTrim": { "description": "A trim read from the listing, not from the buyer choice (third-party listing data). Released to an AI assistant by the CEO's decision D37 (2026-10-08).", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "distanceMiles": { "description": "Distance from the buyer ZIP in miles (third-party listing data). Before the dealership is unlocked this is the LOWER BOUND of the distance band (0, 10, 25, 50 or 100), not the distance: read `distanceBand`. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "distanceBand": { "description": "The distance band as words: Under 10 miles, 10 to 25 miles, 25 to 50 miles, 50 to 100 miles or Over 100 miles (third-party listing data). Always the band, never an exact distance. Null for an AI assistant acting for the buyer.", "x-ridekick-withheld-from-agent": true, "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "priceCheckHref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isVerifiedPartner": { "description": "True when this dealership is a Verified partner: it pays Ridekick a subscription and has agreed to honor its written price while the car is available, if the buyer qualifies for any rebates, incentives or financing in that price. Always present in answers to builders, and may be omitted from answers to hosted assistants; false means either that the dealership is not a partner or that its status is not shown for this row yet, so don't present false as \"not a partner\", and show the conditions above wherever you show true.", "type": "boolean" } }, "required": [ "rowKey", "label", "hidden", "chosen", "archived", "state", "ended", "statusLabel", "otdCents", "sellingPriceCents", "listedAtCents", "writtenAt", "gapToLowestCents", "canChoose", "canUnlock", "quotedTrim", "distanceMiles", "distanceBand", "priceCheckHref", "isVerifiedPartner" ] } } }, "required": [ "waiting", "differentCar", "ended", "archived" ] } }, "required": [ "dealSetId", "car", "search", "counts", "headerLine", "hero", "ranked", "needsYou", "everyoneElse" ] } } } } } }, "401": { "description": "`unauthenticated`: Signed out, or the credential was not accepted: an access token that is not valid, or an Authorization header that is not a Ridekick access token.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } }, "WWW-Authenticate": { "description": "A bearer challenge: `Bearer error=\"invalid_token\"`, or `Bearer error=\"insufficient_scope\", scope=\"\"`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } }, "403": { "description": "`insufficient_scope`: The credential does not include the scope this endpoint needs. The WWW-Authenticate header names the required scope.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } }, "WWW-Authenticate": { "description": "A bearer challenge: `Bearer error=\"invalid_token\"`, or `Bearer error=\"insufficient_scope\", scope=\"\"`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "insufficient_scope" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } }, "404": { "description": "`not_found`: No such resource, or not yours. Also answered while the endpoint is not turned on for you. Never 403: whether another buyer's resource exists is not disclosed.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } }, "429": { "description": "`rate_limited`: Too many requests from this principal in the window.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } }, "500": { "description": "`internal`: Something failed on our side. The response carries no data.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "internal" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } }, "503": { "description": "`auth_unverifiable`: Sign-in could not be confirmed. This is not the same as signed out. `unavailable`: The service did not answer right now, so nothing was returned or sent. Try again in a moment, and wait the number of seconds in `Retry-After` when it is present.", "headers": { "Cache-Control": { "description": "Private to the buyer; nothing shared may cache it.", "schema": { "type": "string", "const": "private, no-store" } }, "Ridekick-API-Version": { "description": "The contract revision this server speaks.", "schema": { "type": "string", "const": "2026-10-13" } }, "Retry-After": { "description": "Seconds to wait before retrying. Present on `unavailable` when the service can say; when it is absent, back off.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "auth_unverifiable", "unavailable" ] }, "message": { "type": "string", "description": "Human text; may change. Branch on `code`." } } } } } } } } } } }, "/api/v1/price-checks": { "get": { "operationId": "list-price-checks", "summary": "The buyer's offers, one card for each car.", "x-ridekick-availability": "planned", "x-ridekick-principals": [ "buyer_session" ], "x-ridekick-rate-limit": { "class": "read", "limit": 120, "windowSeconds": 60 }, "x-ridekick-deadline-ms": null, "x-ridekick-deadline-cancels-read": false, "x-ridekick-rollout-flag": null, "x-ridekick-list-bounds": null, "parameters": [], "responses": {} } }, "/api/v1/requests": { "post": { "operationId": "create-requests", "summary": "Send a request for written offers from the buyer's connected assistant.", "x-ridekick-availability": "planned", "x-ridekick-principals": [ "delegated_agent" ], "x-ridekick-rate-limit": { "class": "write", "limit": 20, "windowSeconds": 60 }, "x-ridekick-deadline-ms": null, "x-ridekick-deadline-cancels-read": false, "x-ridekick-rollout-flag": "API_V1_DELEGATED_ACCESS", "x-ridekick-list-bounds": null, "parameters": [], "responses": {} } }, "/api/v1/requests/preview": { "post": { "operationId": "preview-requests", "summary": "Preview a request before it is sent, and get the token every send needs.", "x-ridekick-availability": "planned", "x-ridekick-principals": [ "delegated_agent" ], "x-ridekick-rate-limit": { "class": "read", "limit": 120, "windowSeconds": 60 }, "x-ridekick-deadline-ms": null, "x-ridekick-deadline-cancels-read": false, "x-ridekick-rollout-flag": "API_V1_DELEGATED_ACCESS", "x-ridekick-list-bounds": null, "parameters": [], "responses": {} } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "The access token a buyer gave an assistant she approved. The assistant sends the buyer to `/oauth/authorize` to sign in and approve it, then sends the token as `Authorization: Bearer `. The buyer's own signed-in session is accepted on the reads as well, and is not an OpenAPI scheme.", "flows": { "authorizationCode": { "authorizationUrl": "/oauth/authorize", "tokenUrl": "/api/oauth/token", "scopes": { "offers:read": "Read the buyer's requests and the offers on them." } } } } } } }