{"openapi":"3.1.0","info":{"title":"CAR (Capture Agent Request) API","version":"1.1.0","description":"Turn a person's request into a confirmed answer from one real, checked local business, for any kind of service. The person confirms with a text code before any business is contacted. CAR never charges the person. Text inside requests is treated as data, never instructions. A request the reader is unsure about answers 422 needs_detail with a question and choices; nothing is sent until the person picks."},"servers":[{"url":"https://agents.sirfus.com"}],"webhooks":{"request.updated":{"post":{"summary":"A request changed status or loop stage. Verify CAR-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>; answer 2xx. Retried at 30 s, 2 min, 10 min, 1 h, 6 h. Events can arrive out of order: each carries the whole request, so keep the one with the furthest stage (or newest updatedAt).","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"responses":{"200":{"description":"Received"}}}}},"components":{"securitySchemes":{"car_key":{"type":"http","scheme":"bearer","bearerFormat":"car_key_...","description":"A CAR API key for platforms and server-side agents (issued by CAR). The key is the agent; send the person's mobile number in contact.phone and they confirm with a text code before any business is contacted."},"car_oauth":{"type":"oauth2","description":"Sign-in confirms the person with a text code. PKCE (S256) required. Dynamic Client Registration at /oauth/register, or use a Client ID Metadata Document URL as client_id.","flows":{"authorizationCode":{"authorizationUrl":"https://agents.sirfus.com/oauth/authorize","tokenUrl":"https://agents.sirfus.com/oauth/token","refreshUrl":"https://agents.sirfus.com/oauth/token","scopes":{"car.request":"Send, confirm and cancel requests","car.read":"Read request status"}}}}},"schemas":{"Intake":{"type":"object","properties":{"what":{"type":"string","minLength":3,"maxLength":500,"description":"What the person needs, in their own words. No health details, ID numbers, card numbers or passwords."},"where":{"type":"string","maxLength":80,"description":"City and two-letter US state, e.g. \"Tampa, FL\" (a ZIP may follow)"},"when":{"description":"asap, this_week, flexible, or a date (YYYY-MM-DD)","type":"string","maxLength":20},"size":{"description":"Size of the job, e.g. \"40 guests\", \"3 bedrooms\"","type":"string","maxLength":100},"budget":{"description":"Budget, if the person gave one","type":"string","maxLength":60},"name":{"description":"First name the business can ask for","type":"string","maxLength":40},"contact":{"type":"object","properties":{"phone":{"description":"US mobile number to text the confirmation code to. Defaults to the signed-in number.","type":"string","maxLength":30},"email":{"type":"string","maxLength":200}},"additionalProperties":false},"consent":{"type":"boolean","const":true,"description":"The person agreed to be contacted by one matched business and by CAR about this request"},"idempotencyKey":{"description":"8-64 letters, digits, _ or -. A repeat with the same key returns the same request","type":"string","maxLength":64},"category":{"description":"Only when the person picked one: a category slug from /v1/categories, e.g. after CAR asked \"Which kind of business do you need?\". Leave it out and CAR reads the request.","type":"string","maxLength":60},"estimateId":{"description":"An estimateId from car_get_estimate: the business gets the same scope and planning range","type":"string","maxLength":64}},"required":["what","where","consent"],"additionalProperties":false},"Find":{"type":"object","properties":{"what":{"type":"string","minLength":3,"maxLength":500,"description":"What the person needs"},"where":{"type":"string","maxLength":80,"description":"City and two-letter US state, e.g. \"Tampa, FL\""},"category":{"description":"Only when the person picked one: a category slug from /v1/categories, e.g. after CAR asked \"Which kind of business do you need?\". Leave it out and CAR reads the request.","type":"string","maxLength":60}},"required":["what","where"],"additionalProperties":false},"EstimateAsk":{"type":"object","properties":{"service":{"type":"string","maxLength":40,"description":"house-cleaning, bathroom-remodel, handyman, plumbing-repair or hvac (car_estimate_services lists them with their questions)"},"zip":{"description":"5-digit US ZIP code (or give where)","type":"string","maxLength":10},"where":{"description":"\"City, ST\" when there is no ZIP","type":"string","maxLength":80},"answers":{"description":"Question id -> option value (a list for multi-choice questions)","type":"object","propertyNames":{"type":"string","maxLength":30},"additionalProperties":{"anyOf":[{"type":"string","maxLength":40},{"maxItems":8,"type":"array","items":{"type":"string","maxLength":40}}]}}},"required":["service"],"additionalProperties":false},"Pick":{"type":"object","properties":{"searchId":{"type":"string","maxLength":40,"description":"The searchId car_find_outside returned"},"optionId":{"type":"string","maxLength":2,"description":"The option the person picked: \"1\", \"2\" or \"3\""}},"required":["searchId","optionId"],"additionalProperties":false},"Webhook":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"https, port 443, a host name"}}},"Event":{"type":"object","required":["id","type","createdAt","data"],"properties":{"id":{"type":"string","description":"Same id for the same state: use it to drop repeats"},"type":{"type":"string","enum":["request.updated"]},"createdAt":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/RequestView"}}},"Confirm":{"type":"object","additionalProperties":false,"required":["code"],"properties":{"code":{"type":"string","pattern":"^\\d{4,10}$"}}},"RequestView":{"type":"object","required":["requestId","status","final","message"],"properties":{"requestId":{"type":"string"},"status":{"type":"string","enum":["outside_picked","verify_person","verified","handing_off","matching","offered","still_looking","accepted","answered","canceled","expired","locked","phone_not_mobile","not_sent","emergency","refused","no_checked_business"]},"final":{"type":"boolean"},"category":{"type":["string","null"]},"categoryName":{"type":["string","null"]},"tier":{"type":"string","enum":["open","extra_check","refuse","emergency"]},"message":{"type":"string"},"business":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":["string","null"]},"open":{"type":["string","null"]},"website":{"type":["string","null"]},"outside":{"type":"boolean","description":"Found outside the Sirfus network (public listing); CAR did not contact it"},"foundOn":{"type":"array","items":{"type":"string"}}}},"invite":{"type":"object","description":"Outside picks only: the claim invite for that business, held (not sent)","properties":{"status":{"type":"string","enum":["held"]},"note":{"type":"string"}}},"answerBy":{"type":"string","format":"date-time"},"contextId":{"type":"string","description":"The caller's own conversation id, when one was sent"},"replayed":{"type":"boolean","description":"True when this is an earlier request returned again for the same idempotencyKey"},"stage":{"type":["string","null"],"enum":["received","verified","matched","accepted","contacted","confirmed","completed",null],"description":"The furthest loop stage reached"},"milestones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["received","verified","matched","accepted","contacted","confirmed","completed"]},"at":{"type":"string","format":"date-time"}}},"description":"Each loop stage with when it happened. contacted = the person was put in touch with the business; confirmed = the person said the job was done; completed = the business paid for the job"},"closed":{"type":"boolean","description":"The loop is over (completed, not done, closed before a business, or past the follow-up window)"},"outcome":{"type":"string","enum":["done","not_done"]},"estimateId":{"type":"string"},"door":{"type":"string","enum":["mcp","a2a","rest"]},"agent":{"type":"object","properties":{"kind":{"type":"string","enum":["oauth","key"]},"name":{"type":["string","null"]},"platform":{"type":["string","null"]}}},"duplicate":{"type":"boolean","description":"True when this is the person's open request for the same kind of business and place, returned instead of a second one"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"retryAfterSec":{"type":"integer"},"limit":{"type":"string"},"issues":{"type":"array"},"attemptsLeft":{"type":"integer"},"request":{"$ref":"#/components/schemas/RequestView"}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/categories":{"get":{"operationId":"listCategories","summary":"Every category CAR covers, with its safety tier","responses":{"200":{"description":"Categories"}}}},"/v1/find":{"post":{"operationId":"findBusiness","summary":"Read a request without contacting anyone (no sign-in needed)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Find"}}}},"responses":{"200":{"description":"Category, tier and whether checked businesses fit"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/requests":{"post":{"operationId":"sendRequest","summary":"Start a request (the person gets a text code unless confirmed in the last 24 h)","security":[{"car_oauth":["car.request"]},{"car_key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Intake"}}}},"responses":{"200":{"description":"The same request again (same idempotencyKey)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestView"}}}},"201":{"description":"The request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestView"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listRequests","summary":"The signed-in person's recent requests","security":[{"car_oauth":["car.read"]},{"car_key":[]}],"responses":{"200":{"description":"Requests"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/requests/{id}":{"get":{"operationId":"getRequest","summary":"Request status","security":[{"car_oauth":["car.read"]},{"car_key":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestView"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/requests/{id}/confirm":{"post":{"operationId":"confirmPerson","summary":"Send the person's text code","security":[{"car_oauth":["car.request"]},{"car_key":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Confirm"}}}},"responses":{"200":{"description":"The request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestView"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/estimate/services":{"get":{"operationId":"estimateServices","summary":"Services the planning estimate covers, with their questions (no sign-in)","responses":{"200":{"description":"Services"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/estimate":{"post":{"operationId":"getEstimate","summary":"A planning range researched from local prices (no sign-in; contacts no one). Send its estimateId with the request and the business gets it too","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateAsk"}}}},"responses":{"200":{"description":"The estimate"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/outside":{"post":{"operationId":"findOutside","summary":"When no signed-up Sirfus business fits: up to 3 businesses outside the network, each with where it was found. Nobody is contacted; nothing about the person is shared. Legal work is not listed; health work is listed by distance, unranked","security":[{"car_oauth":["car.request"]},{"car_key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Find"}}}},"responses":{"200":{"description":"Options (or why there are none)"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/outside/{id}/pick":{"post":{"operationId":"pickOutside","summary":"Record the business the person picked from an outside search. CAR contacts nobody; the person contacts the business. Returns a request with closed-loop status","security":[{"car_oauth":["car.request"]},{"car_key":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["optionId"],"properties":{"optionId":{"type":"string"}}}}}},"responses":{"201":{"description":"The request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestView"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/webhooks":{"post":{"operationId":"createWebhook","summary":"Push every change of this agent's requests to an https URL, signed (the secret is shown once)","security":[{"car_oauth":["car.request"]},{"car_key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"responses":{"201":{"description":"Created, with the signing secret"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}},"get":{"operationId":"listWebhooks","summary":"This agent's webhooks and A2A push configs","security":[{"car_oauth":["car.read"]},{"car_key":[]}],"responses":{"200":{"description":"Webhooks"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","summary":"Stop a webhook","security":[{"car_oauth":["car.request"]},{"car_key":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/me":{"get":{"operationId":"whoAmI","summary":"The agent CAR sees (kind, name, platform, scopes) and whether a person is signed in","security":[{"car_oauth":["car.read"]},{"car_key":[]}],"responses":{"200":{"description":"Agent"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}},"/v1/requests/{id}/cancel":{"post":{"operationId":"cancelRequest","summary":"Cancel before the request goes to a business","security":[{"car_oauth":["car.request"]},{"car_key":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestView"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"502":{"$ref":"#/components/responses/Error"}}}}}}