{"openapi":"3.1.0","info":{"title":"Realask Agent Verification API","version":"0.2.0","summary":"Ask the real world a current question; receive a structured, time-stamped, confidence-scored answer.","description":"Machine-purchasable verification of local-business facts. Flow: POST /v1/quotes (free) -> POST /v1/jobs (payment-protected, HTTP 402 challenge via x402) -> poll GET /v1/jobs/{id} or receive a signed webhook -> GET /v1/jobs/{id}/result. Jobs are asynchronous; the paid request returns 202 immediately. United States only. Business-information purposes only.","x-agent-hints":{"payment":{"protocol":"x402","x402Version":2,"scheme":"exact","network":"eip155:8453","payTo":"0x8B4d990B8F59ae2e2E169DF4aEfBfdaF12d33fF5","facilitator":"coinbase-cdp","resource":"https://realask.net/v1/jobs","bazaar_discoverable":true,"description":"Ask the real world a question and get a structured, time-stamped, confidence-scored answer. Verifies current facts about a specific US local business - in stock, price, same-day availability, whether it can do an unusual job, a policy exception, current wait time - by calling the business and extracting typed facts with evidence. Use when web and profile data are missing, stale, or unreliable. Get a price from POST /v1/quotes first; this endpoint buys that quote and returns a job_id to poll. Returns the answer, not a transcript.","tags":["verification","ground-truth","local-business","phone-call","real-time-data","availability","inventory","pricing","confirm","fact-check"]},"idempotency":"Send Idempotency-Key on POST /v1/jobs. Retrying with the same key or the same signed payment returns the existing job and never charges twice.","async":"Expect several minutes for live verification. Continue other work and poll, or supply callback_url on the quote.","evidence":"Facts below confidence 0.60 are never reported as verified. Conflicts are surfaced in limitations."}},"servers":[{"url":"https://realask.net"}],"paths":{"/v1/quotes":{"post":{"operationId":"createQuote","summary":"Create a free, immutable quote for a verification job","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request not permitted or unsupported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/quotes/{quote_id}":{"get":{"operationId":"getQuote","summary":"Fetch a quote","parameters":[{"name":"quote_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/jobs":{"post":{"operationId":"purchaseJob","summary":"Purchase a quoted job (payment-protected)","description":"Without payment the response is HTTP 402 with a PAYMENT-REQUIRED header (x402 v2). Retry with PAYMENT-SIGNATURE. On success: 202 with job_id and a one-time job_token. Idempotent by Idempotency-Key and by payment receipt.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateJobRequest"}}}},"responses":{"200":{"description":"Idempotent replay: existing job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreatedResponse"}}}},"202":{"description":"Job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobCreatedResponse"}}}},"402":{"description":"Payment required (x402 challenge in PAYMENT-REQUIRED header and body)"},"404":{"description":"Quote not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Quote already used or payment replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"410":{"description":"Quote expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/jobs/{job_id}":{"get":{"operationId":"getJobStatus","summary":"Job status and progress","security":[{"jobToken":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/jobs/{job_id}/result":{"get":{"operationId":"getJobResult","summary":"Final structured result with evidence","security":[{"jobToken":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Result (final)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResultResponse"}}}},"202":{"description":"Not final yet; provisional view of progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResultResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/jobs/{job_id}/cancel":{"post":{"operationId":"cancelJob","summary":"Cancel a running job (no refund in v1)","security":[{"jobToken":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Canceled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatusResponse"}}}}}}}},"webhooks":{"jobEvent":{"post":{"summary":"Signed job completion event","description":"Header X-Realask-Signature: t=<unix>,v1=<hex HMAC-SHA256 over `${t}.${body}`>. Reject if |now-t| > 300s.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Acknowledged"}}}}},"components":{"securitySchemes":{"jobToken":{"type":"http","scheme":"bearer","description":"job_token returned once when the job was purchased"}},"schemas":{"QuoteRequest":{"type":"object","properties":{"request":{"type":"string","minLength":8,"maxLength":2000},"location":{"type":"object","properties":{"postal_code":{"type":"string","minLength":3,"maxLength":12},"city":{"type":"string","maxLength":80},"region":{"type":"string","maxLength":40},"country":{"default":"US","type":"string","minLength":2,"maxLength":2},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"radius_miles":{"type":"number","minimum":1,"maximum":50}},"required":["country"],"additionalProperties":false},"limits":{"default":{"max_businesses":5,"deadline_seconds":600,"max_call_attempts_per_target":1},"type":"object","properties":{"max_businesses":{"default":5,"type":"integer","minimum":1,"maximum":5},"deadline_seconds":{"default":600,"type":"integer","minimum":60,"maximum":600},"max_call_attempts_per_target":{"default":1,"type":"integer","minimum":1,"maximum":2}},"required":["max_businesses","deadline_seconds","max_call_attempts_per_target"],"additionalProperties":false},"target":{"type":"object","properties":{"business_name":{"type":"string","maxLength":120},"phone":{"type":"string","maxLength":24},"place_id":{"type":"string","maxLength":200}},"additionalProperties":false},"verification_mode":{"default":"auto","type":"string","enum":["digital_fast","live_verified","auto"]},"max_fact_age_seconds":{"type":"integer","minimum":60,"maximum":7776000},"callback_url":{"type":"string","maxLength":2000,"format":"uri"},"priority":{"default":false,"type":"boolean"},"action":{"type":"object","properties":{"action":{"type":"string","enum":["book","hold","request_quote","cancel"]},"what":{"type":"string","minLength":3,"maxLength":500},"when":{"type":"string","maxLength":200},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":999},"max_price_minor":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"currency":{"default":"USD","type":"string","minLength":3,"maxLength":3},"on_behalf_of":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80},"callback_phone":{"type":"string","minLength":10,"maxLength":24}},"required":["name","callback_phone"],"additionalProperties":false},"reference":{"type":"string","maxLength":120},"notes":{"type":"string","maxLength":500},"authorized":{"type":"boolean","const":true}},"required":["action","what","currency","on_behalf_of","authorized"],"additionalProperties":false}},"required":["request","location","limits","verification_mode","priority"],"additionalProperties":false},"QuoteResponse":{"type":"object","properties":{"quote_id":{"type":"string"},"request_id":{"type":"string"},"price":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"default":"USD","type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"scope":{"type":"object","properties":{"job_type":{"type":"string","enum":["single_business","find_any","compare","capability","policy","status","book","hold","request_quote","cancel"]},"max_businesses":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max_call_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"deadline_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"verification_mode":{"type":"string","enum":["digital_fast","live_verified","auto"]}},"required":["job_type","max_businesses","max_call_attempts","deadline_seconds","verification_mode"],"additionalProperties":false},"deliverable":{"type":"array","items":{"type":"string"}},"expected_completion_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max_completion_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"cached_answer":{"type":"object","properties":{"available":{"type":"boolean"},"price":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":0,"maximum":9007199254740991},"currency":{"default":"USD","type":"string","minLength":3,"maxLength":3}},"required":["amount_minor","currency"],"additionalProperties":false},"age_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["available"],"additionalProperties":false},"expires_at":{"type":"string"},"created_at":{"type":"string"}},"required":["quote_id","request_id","price","scope","deliverable","expected_completion_seconds","max_completion_seconds","expires_at","created_at"],"additionalProperties":false},"CreateJobRequest":{"type":"object","properties":{"quote_id":{"type":"string","minLength":4}},"required":["quote_id"],"additionalProperties":false},"JobCreatedResponse":{"type":"object","properties":{"job_id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["quoted","awaiting_payment","queued","discovering","calling","extracting","completed","partial","failed","timed_out","canceled"]},"status_url":{"type":"string"},"result_url":{"type":"string"},"job_token":{"type":"string"},"expected_completion_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"deadline_at":{"type":"string"},"created_at":{"type":"string"}},"required":["job_id","request_id","status","status_url","result_url","job_token","expected_completion_seconds","deadline_at","created_at"],"additionalProperties":false},"JobStatusResponse":{"type":"object","properties":{"job_id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["quoted","awaiting_payment","queued","discovering","calling","extracting","completed","partial","failed","timed_out","canceled"]},"progress":{"type":"object","properties":{"targets_discovered":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"targets_attempted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"targets_reached":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"confirmed_answers":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["targets_discovered","targets_attempted","targets_reached","confirmed_answers"],"additionalProperties":false},"deadline_at":{"type":"string"},"result_url":{"type":"string"},"updated_at":{"type":"string"}},"required":["job_id","request_id","status","progress","deadline_at","result_url","updated_at"],"additionalProperties":false},"JobResultResponse":{"type":"object","properties":{"job_id":{"type":"string"},"request_id":{"type":"string"},"status":{"type":"string","enum":["quoted","awaiting_payment","queued","discovering","calling","extracting","completed","partial","failed","timed_out","canceled"]},"job_type":{"type":"string","enum":["single_business","find_any","compare","capability","policy","status","book","hold","request_quote","cancel"]},"verification_mode":{"type":"string","enum":["digital_fast","live_verified","auto"]},"answer":{"type":"object","properties":{"summary":{"type":"string"},"resolved":{"type":"boolean"},"best_match":{"anyOf":[{"type":"object","properties":{"business_name":{"type":"string"},"place_id":{"type":"string"},"address":{"type":"string"},"phone":{"type":"string"},"distance_miles":{"type":"number"},"confirmed":{"type":"boolean"},"outcome":{"type":"string","enum":["confirmed_match","confirmed_no_match","uncertain","not_reached","declined","not_attempted","suppressed"]},"facts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean","null"]}},"fact_details":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":["string","number","boolean","null"]},"currency":{"type":"string"},"status":{"type":"string","enum":["confirmed","uncertain","unconfirmed","conflicting","not_asked"]},"source":{"type":"object","properties":{"type":{"type":"string","enum":["live_business_call","published_listing","cached_verified_fact","business_website","merchant_feed"]},"call_attempt_id":{"type":"string"},"job_id":{"type":"string"},"speaker_role":{"type":"string","enum":["business_employee","ivr","voicemail","unknown","assistant"]},"observed_at":{"type":"string"}},"required":["type","observed_at"],"additionalProperties":false},"confidence":{"type":"number","minimum":0,"maximum":1},"age_seconds":{"type":"integer","minimum":0,"maximum":9007199254740991},"notes":{"type":["string","null"]}},"required":["name","value","status","source","confidence","age_seconds","notes"],"additionalProperties":false}},"verified_at":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["business_name","confirmed","outcome","facts","fact_details","confidence"],"additionalProperties":false},{"type":"null"}]},"alternatives":{"type":"array","items":{"type":"object","properties":{"business_name":{"type":"string"},"place_id":{"type":"string"},"address":{"type":"string"},"phone":{"type":"string"},"distance_miles":{"type":"number"},"confirmed":{"type":"boolean"},"outcome":{"type":"string","enum":["confirmed_match","confirmed_no_match","uncertain","not_reached","declined","not_attempted","suppressed"]},"facts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean","null"]}},"fact_details":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":["string","number","boolean","null"]},"currency":{"type":"string"},"status":{"type":"string","enum":["confirmed","uncertain","unconfirmed","conflicting","not_asked"]},"source":{"type":"object","properties":{"type":{"type":"string","enum":["live_business_call","published_listing","cached_verified_fact","business_website","merchant_feed"]},"call_attempt_id":{"type":"string"},"job_id":{"type":"string"},"speaker_role":{"type":"string","enum":["business_employee","ivr","voicemail","unknown","assistant"]},"observed_at":{"type":"string"}},"required":["type","observed_at"],"additionalProperties":false},"confidence":{"type":"number","minimum":0,"maximum":1},"age_seconds":{"type":"integer","minimum":0,"maximum":9007199254740991},"notes":{"type":["string","null"]}},"required":["name","value","status","source","confidence","age_seconds","notes"],"additionalProperties":false}},"verified_at":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["business_name","confirmed","outcome","facts","fact_details","confidence"],"additionalProperties":false}}},"required":["summary","resolved","best_match","alternatives"],"additionalProperties":false},"commitment":{"anyOf":[{"type":"object","properties":{"state":{"type":"string","enum":["committed","declined","unavailable","over_budget","not_reached","needs_human","canceled"]},"action":{"type":"string","enum":["book","hold","request_quote","cancel"]},"business_name":{"type":"string"},"place_id":{"type":"string"},"phone":{"type":"string"},"confirmation_reference":{"type":["string","null"]},"what":{"type":"string"},"agreed_time":{"type":["string","null"]},"agreed_price_minor":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"currency":{"type":["string","null"]},"cancellation_policy":{"type":["string","null"]},"held_under_name":{"type":["string","null"]},"committed_at":{"type":["string","null"]},"confidence":{"type":"number","minimum":0,"maximum":1},"evidence_excerpt":{"type":["string","null"]},"notes":{"type":["string","null"]}},"required":["state","action","business_name","confirmation_reference","what","agreed_time","agreed_price_minor","currency","cancellation_policy","held_under_name","committed_at","confidence","evidence_excerpt","notes"],"additionalProperties":false},{"type":"null"}]},"evidence":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["live_business_call","published_listing","cached_verified_fact","business_website","merchant_feed"]},"business_name":{"type":"string"},"place_id":{"type":"string"},"timestamp":{"type":"string"},"speaker_role":{"type":"string","enum":["business_employee","ivr","voicemail","unknown","assistant"]},"excerpt":{"type":"string"},"call_attempt_id":{"type":"string"},"transcript_retention":{"type":"string","enum":["policy-controlled","not-retained","retained"]}},"required":["type","business_name","timestamp","speaker_role","excerpt","transcript_retention"],"additionalProperties":false}},"freshness":{"type":"object","properties":{"verified_at":{"type":["string","null"]},"age_seconds":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"fact_class":{"type":"string","enum":["volatile","daily","stable"]}},"required":["verified_at","age_seconds","fact_class"],"additionalProperties":false},"limitations":{"type":"array","items":{"type":"string"}},"completed_at":{"type":["string","null"]}},"required":["job_id","request_id","status","job_type","verification_mode","answer","evidence","freshness","limitations","completed_at"],"additionalProperties":false},"WebhookEvent":{"type":"object","properties":{"event":{"type":"string","enum":["job.completed","job.partial","job.failed","job.timed_out","job.canceled"]},"job_id":{"type":"string"},"status":{"type":"string","enum":["quoted","awaiting_payment","queued","discovering","calling","extracting","completed","partial","failed","timed_out","canceled"]},"result_url":{"type":"string"},"occurred_at":{"type":"string"}},"required":["event","job_id","status","result_url","occurred_at"],"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"],"additionalProperties":false},"request_id":{"type":"string"}},"required":["error","request_id"],"additionalProperties":false}}}}