{"openapi":"3.1.0","info":{"title":"HopTire Agent Booking API","version":"1.0.0","summary":"Authorized agents prepare HopTire bookings and hand them to a checkout page where the customer or the agent pays.","description":"Read https://hoptire.com/docs/agents.md first. A booking is submitted as a service request when payment succeeds; it is not a confirmed appointment. Terms version 2026-11-09.2: https://hoptire.com/terms.","contact":{"email":"support@hoptire.com"}},"servers":[{"url":"https://hoptire.com"}],"externalDocs":{"url":"https://hoptire.com/docs/agents"},"paths":{"/api/agent/v1/schema":{"get":{"operationId":"hoptire_agent_schema","summary":"Read the live booking fields, values, conditions and limits","security":[],"parameters":[],"responses":{"200":{"description":"Booking schema for the current flow.","headers":{},"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Query parameters are not accepted.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/quote":{"post":{"operationId":"hoptire_agent_quote","summary":"Price a full or partial booking","description":"No side effects. Missing and invalid answers return field-level issues. The time zone comes from the ZIP.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"Quote result. quote is null until every price answer is valid.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"description":"Bad JSON or unknown top-level fields.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body too large.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable. Retry.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/drafts":{"post":{"operationId":"hoptire_agent_create_draft","summary":"Store a complete booking draft and get its checkout link","description":"Idempotent by Idempotency-Key. Stores a draft only: no message, no payment session, no appointment. Terms and optional text consent are not accepted here.","security":[],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"},"description":"Unique per draft. Reuse it with the same body to retry safely."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftRequest"}}}},"responses":{"200":{"description":"Replay of an earlier request with the same key and body.","headers":{"Idempotent-Replayed":{"schema":{"type":"string","enum":["true"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftResponse"}}}},"201":{"description":"Draft stored.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftResponse"}}}},"400":{"description":"Bad JSON, unknown fields or a missing Idempotency-Key.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict (same key, other body) or quote_changed (expected price differs).","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body too large.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Content-Type must be application/json.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"invalid_answers with issues, or needs_human_review.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Unavailable. Retry with the same key and body.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/v1/drafts/{draftId}":{"get":{"operationId":"hoptire_agent_draft_status","summary":"Read draft, approval and verified payment state","security":[{"statusToken":[]}],"parameters":[{"name":"draftId","in":"path","required":true,"schema":{"type":"string","pattern":"^hta_[a-z0-9]{20}$"}}],"responses":{"200":{"description":"Draft state. Contains no answers or contact details.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftStatus"}}}},"401":{"description":"Missing or malformed Bearer status token.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown draft, wrong token or expired status grant.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Unavailable. Retry.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"statusToken":{"type":"http","scheme":"bearer","description":"The draft.status.token value. It reads state only."}},"schemas":{"Answers":{"type":"object","additionalProperties":false,"properties":{"service":{"description":"What do you need?","type":"string","enum":["replace-supplied","repair","seasonal-changeover"]},"qty":{"description":"How many tires?","type":"string","enum":["1","2","3","4","other"]},"qtyExact":{"description":"Exact number of tires","type":"integer","minimum":1,"maximum":4},"size":{"description":"Tire size. On your tire or the sticker inside the driver door. Not sure? We can help.","type":"string","maxLength":24,"pattern":"^(unknown|(P|LT)?\\s?\\d{3}\\s?/\\s?\\d{2}\\s?Z?R\\s?\\d{2}(\\.5)?(\\s?\\d{2,3}\\s?[A-Z]{1,2})?)$"},"sizeSource":{"description":"Where the size came from","type":"string","enum":["oe-lookup","manual","photo","unknown"]},"sizeRear":{"description":"Rear tire size","type":"string","maxLength":24,"pattern":"^(P|LT)?\\s?\\d{3}\\s?/\\s?\\d{2}\\s?Z?R\\s?\\d{2}(\\.5)?(\\s?\\d{2,3}\\s?[A-Z]{1,2})?$"},"zip":{"description":"ZIP code","type":"string"},"vehicleType":{"description":"Vehicle type","type":"string","enum":["car","suv","pickup","heavy"]},"vehicleTypeSource":{"description":"Where the vehicle type came from","type":"string","enum":["vpic","customer"]},"year":{"description":"Year","type":"string","enum":["2027","2026","2025","2024","2023","2022","2021","2020","2019","2018","2017","2016","2015","2014","2013","2012","2011","2010","2009","2008","2007","2006","2005","2004","2003","2002","2001","2000","1999","1998","1997","1996","Other","unknown"]},"yearOther":{"description":"Vehicle year","type":"integer","minimum":1900,"maximum":2027},"make":{"description":"Make","type":"string","enum":["Acura","Audi","BMW","Buick","Cadillac","Chevrolet","Chrysler","Dodge","Ford","Genesis","GMC","Honda","Hyundai","Infiniti","Jaguar","Jeep","Kia","Land Rover","Lexus","Lincoln","Mazda","Mercedes-Benz","Mini","Mitsubishi","Nissan","Polestar","Porsche","Ram","Rivian","Subaru","Tesla","Toyota","Volkswagen","Volvo","Other","unknown"]},"makeOther":{"description":"Vehicle make","type":"string","maxLength":40},"model":{"description":"Model","type":"string","maxLength":40},"trim":{"description":"Trim (if you know it)","type":"string","maxLength":40},"repairDamageLocation":{"description":"Where is the tire damage?","type":"string","enum":["tread","sidewall","not-visible","not-sure"]},"repairDrivenFlat":{"description":"Was the vehicle driven with this tire flat?","type":"string","enum":["yes","no","not-sure"]},"positions":{"description":"Which positions?","type":"string","enum":["front-left","front-right","front-left,front-right","rear-left","front-left,rear-left","front-right,rear-left","front-left,front-right,rear-left","rear-right","front-left,rear-right","front-right,rear-right","front-left,front-right,rear-right","rear-left,rear-right","front-left,rear-left,rear-right","front-right,rear-left,rear-right","all","front-pair","rear-pair","mixed","not-sure"]},"staggered":{"description":"Different front and rear tire sizes","type":"string","enum":["yes","no","not-sure"]},"customerTireState":{"description":"What kind of tires do you have?","type":"string","enum":["mounted-wheels","new-loose","used","not-sure"]},"tirePref":{"description":"Tire preference","type":"string","enum":["budget","mid","premium"]},"specificTire":{"description":"Which tire?","type":"string","maxLength":80},"damage":{"description":"A wheel is bent or cracked, or a lug nut is seized","type":"string","enum":["no","yes","not-sure"]},"address":{"description":"Street address","type":"string","maxLength":160},"lockKey":{"description":"Do you have the wheel-lock key?. Only if your wheels have locking nuts. The key is usually in the glove box or with the spare.","type":"string","enum":["yes","no","not-sure"]},"availability":{"description":"Your availability","type":"array","maxItems":84,"items":{"$ref":"#/components/schemas/AvailabilitySlot"}},"visitConstraintKind":{"description":"Do you have an arrival or finish deadline?. This is a request, not a confirmed arrival or finish time. Keep your available visit windows selected above.","type":"string","enum":["none","arrive-by","finish-by"]},"visitConstraintDate":{"description":"Requested deadline date","type":"string"},"visitConstraintTime":{"description":"Requested deadline time (AM or PM)","type":"string","maxLength":12},"directions":{"description":"Anything the technician should know?","type":"string","maxLength":600},"name":{"description":"Your name","type":"string","maxLength":80},"email":{"description":"Email","type":"string","maxLength":120},"phone":{"description":"Mobile number. For questions about this request and your visit. This does not sign you up for texts.","type":"string","maxLength":24}},"description":"Booking answers. Read /api/agent/v1/schema for required and conditional fields."},"AvailabilitySlot":{"type":"object","additionalProperties":false,"required":["date","start","end"],"properties":{"date":{"type":"string","format":"date"},"start":{"type":"string","pattern":"^(0[89]|1[0-9]|20):00$"},"end":{"type":"string","pattern":"^(0[89]|1[0-9]|20):00$"}}},"Authorization":{"type":"object","additionalProperties":false,"required":["declaration","agentName","grantedActions"],"properties":{"declaration":{"type":"string","enum":["customer_authorized"]},"agentName":{"type":"string","minLength":1,"maxLength":80},"agentOperator":{"type":["string","null"],"maxLength":120},"grantedActions":{"type":"array","uniqueItems":true,"items":{"type":"string","enum":["prepare_booking","accept_terms","submit_payment"]},"contains":{"const":"prepare_booking"}},"maxAmountMinor":{"type":["integer","null"],"minimum":50,"maximum":99999999}}},"QuoteRequest":{"type":"object","additionalProperties":false,"properties":{"answers":{"$ref":"#/components/schemas/Answers"}}},"Issue":{"type":"object","required":["field","code","message"],"properties":{"field":{"type":"string"},"code":{"type":"string","enum":["missing","invalid","unknown_field","not_accepted"]},"message":{"type":"string"},"requiredFor":{"type":"string","enum":["quote","booking"]}}},"QuoteLine":{"type":"object","required":["id","label","amountMinor"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"amountMinor":{"type":"integer"},"note":{"type":"string"}}},"Quote":{"type":"object","required":["amountMinor","currency","taxIncluded","label","lines","revision","policyVersion","flowVersion","sameDay"],"properties":{"amountMinor":{"type":"integer","description":"Tax-inclusive total in US cents."},"currency":{"type":"string","enum":["usd"]},"taxIncluded":{"type":"boolean","enum":[true]},"label":{"type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/QuoteLine"}},"revision":{"type":"string","pattern":"^qr_[0-9a-f]{24}$","description":"Changes when the price or a price answer changes."},"policyVersion":{"type":"string"},"flowVersion":{"type":"integer"},"sameDay":{"type":"boolean"}}},"Condition":{"type":"object","required":["id","text"],"properties":{"id":{"type":"string"},"text":{"type":"string"}}},"QuoteResponse":{"type":"object","required":["ok","status","complete","payable","quote","issues","conditions","requestedTimes","derived"],"properties":{"ok":{"type":"boolean","enum":[true]},"apiVersion":{"type":"string"},"status":{"type":"string","enum":["needs_answers","quoted_needs_booking_details","ready_for_draft","needs_human_review"]},"complete":{"type":"boolean"},"payable":{"type":"boolean"},"quote":{"oneOf":[{"$ref":"#/components/schemas/Quote"},{"type":"null"}]},"service":{"type":"object"},"derived":{"type":"object"},"requestedTimes":{"type":"object"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/Condition"}},"humanReview":{"type":"array","items":{"type":"string"}},"checkAvailability":{"type":"boolean","description":"True in a check-availability ZIP: no price or payment; use requestPath."},"requestPath":{"type":["string","null"],"description":"The regular request page when HopTire must review first."},"issues":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"ignoredFields":{"type":"array","items":{"type":"string"}},"sideEffects":{"type":"string"}}},"DraftRequest":{"type":"object","additionalProperties":false,"required":["answers","authorization"],"properties":{"answers":{"$ref":"#/components/schemas/Answers"},"authorization":{"$ref":"#/components/schemas/Authorization"},"expectedQuoteRevision":{"type":"string","pattern":"^qr_[0-9a-f]{24}$","description":"Optional. Fails with quote_changed when the current quote differs."},"expectedAmountMinor":{"type":"integer","description":"Optional. Fails with quote_changed when the current total differs."},"source":{"type":"string","enum":["agent","synthetic_qa"],"default":"agent","description":"Use synthetic_qa for test traffic. Live payment is disabled for it."}}},"DraftResponse":{"type":"object","required":["ok","draft"],"properties":{"ok":{"type":"boolean","enum":[true]},"apiVersion":{"type":"string"},"draft":{"type":"object","required":["id","checkoutUrl","status","quote","expiresAt","agentMayApprove"],"properties":{"id":{"type":"string"},"state":{"type":"string"},"source":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"service":{"type":"object"},"quote":{"$ref":"#/components/schemas/Quote"},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/Condition"}},"requestedTimes":{"type":"object"},"authority":{"type":"object"},"agentMayApprove":{"type":"boolean"},"customerApprovalNeededFor":{"type":"array","items":{"type":"object"}},"checkoutUrl":{"type":"string","format":"uri","description":"Secret, expiring link. The token is in the URL fragment."},"status":{"type":"object","required":["url","token","expiresAt"],"properties":{"url":{"type":"string","format":"uri"},"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}},"nextSteps":{"type":"array","items":{"type":"string"}},"sideEffects":{"type":"string"}}},"DraftStatus":{"type":"object","required":["ok","draft","payment","appointment"],"properties":{"ok":{"type":"boolean","enum":[true]},"draft":{"type":"object","properties":{"id":{"type":"string"},"state":{"type":"string","enum":["ready_for_checkout","checkout_opened","expired","payment_pending","paid","partially_refunded","refunded","canceled"]}}},"approval":{"type":["object","null"]},"serviceRequest":{"type":["object","null"]},"payment":{"type":"object","properties":{"state":{"type":"string","enum":["not_started","pending","paid","partially_refunded","refunded"]},"verifiedByServer":{"type":"boolean"},"amountMinor":{"type":["integer","null"]},"refundedMinor":{"type":["integer","null"]},"paidAt":{"type":["string","null"]}}},"appointment":{"type":"object","properties":{"confirmed":{"type":"boolean"},"note":{"type":"string"}}}}},"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","examples":["bad_json","invalid_request","idempotency_key_required","invalid_answers","needs_human_review","quote_changed","idempotency_conflict","unauthorized","not_found","too_large","unsupported_media_type","rate_limited","agent_booking_unavailable","quote_unavailable","draft_unavailable","status_unavailable"]},"message":{"type":"string"},"retryable":{"type":"boolean"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"retryAfterSeconds":{"type":"integer"}}}}}}}}