{"openapi":"3.1.0","info":{"title":"Agent Intent Match API","version":"1.0.0","summary":"Find public buyer intent that matches what you sell.","description":"Agent Intent Match finds existing, public buyer intent for what a seller offers: current requests, RFPs/RFQs, public tenders and forum posts in which someone asks for the seller’s product, service, API or capability. Every returned signal has a verbatim quote, source URL and freshness data. It discovers demand only; it never contacts buyers.\n\nAlso known as: buyer intent, buyer intent discovery, demand discovery, demand signals, purchase intent, service request discovery, procurement intent, agent intent matching, buyer request matching, commercial intent, find buyers, find demand, capability demand.\n\nPrice: 0.35 USDC per request, paid with x402 v2 (exact scheme, USDC on eip155:8453). One payment buys one search-and-classify run, including a credible zero-match result (no demand found is a valid answer). If the paid run fails, resend the identical body with the same Idempotency-Key plus Authorization: Bearer <Idempotency-Key> (no new payment) for up to two free retries. A URL-only request whose page cannot be retrieved is refused before settlement, so nothing is charged. No automatic refunds; uncertain settlements require reconciliation. See /terms.\n\nFreshness: freshness (24h, 7d, 30d, 90d, 365d) is the maximum age of a buyer signal. Signals with a known publication date outside the window are rejected. Signals with an unknown date are returned with published_at null and an uncertainty unless require_known_date is true. Procurement notices whose deadline has passed are rejected as closed.","contact":{"name":"Active Life Hub LLC","url":"https://agentintentmatch.online/docs"},"x-operator":"Active Life Hub LLC","x-price":{"amount":"0.35","currency":"USDC","network":"eip155:8453","pricing_version":"agent-intent-match-cost-plus-2026-09-29-v1"}},"servers":[{"url":"https://agentintentmatch.online"}],"paths":{"/api/v1/matches":{"post":{"operationId":"createIntentMatch","summary":"Find current public buyer intent for a seller offering (paid, x402).","description":"Without PAYMENT-SIGNATURE the response is 402 with the x402 requirement in the PAYMENT-REQUIRED header and body. Sign it and resend the identical body with the same Idempotency-Key. The search runs inside the request (typically 30–120 s). To recover a paid request, resend with Authorization: Bearer <Idempotency-Key>.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"},"description":"Random secret. Also the result access key."},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"Base64 x402 v2 payment payload."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string","pattern":"^Bearer [A-Za-z0-9_-]{16,128}$"},"description":"Bearer <Idempotency-Key> to resume or retry a paid request without paying again."},{"name":"X-City-Referral","in":"header","required":false,"schema":{"type":"string","maxLength":4096},"description":"Optional America Agent City referral token (City Advantage: 20% off). Invalid, expired or reused tokens simply give the normal price. Alternatively a city_referral body field or query parameter. https://americaagent.city/docs/city-advantage.md"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchRequest"}},"text/plain":{"schema":{"type":"string","description":"Treated as description."}}}},"responses":{"200":{"description":"Completed Intent Match Report (possibly with zero matches).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"202":{"description":"Accepted and in progress; poll GET /api/v1/matches/{id}."},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (x402). See PAYMENT-REQUIRED header. With X-City-Referral the body also carries the CityQuote fields."},"409":{"description":"Idempotency conflict or reused payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Result expired under the retention policy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request larger than 16 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Unsupported media type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Price ceiling exceeded or seller URL unreadable (nothing charged).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Not configured, provider unavailable, or paid search failed (retryable).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/matches/{id}":{"get":{"operationId":"getIntentMatch","summary":"Retrieve status or result.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"description":"Bearer <Idempotency-Key used to create the request>."}],"responses":{"200":{"description":"Completed report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"202":{"description":"Status: created | paid | searching."},"401":{"description":"Missing bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown ID or wrong key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Expired and deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Failed or settlement uncertain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/quote":{"post":{"operationId":"quoteIntentMatch","summary":"Free quote: price and x402 requirement for a request body.","parameters":[{"name":"X-City-Referral","in":"header","required":false,"schema":{"type":"string","maxLength":4096},"description":"Optional America Agent City referral token (City Advantage: 20% off). Invalid, expired or reused tokens simply give the normal price. Alternatively a city_referral body field or query parameter. https://americaagent.city/docs/city-advantage.md"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchRequest"}}}},"responses":{"200":{"description":"Quote."},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/pricing":{"get":{"operationId":"getPricing","summary":"Current price and policy.","responses":{"200":{"description":"Pricing."}}}},"/api/v1/health":{"get":{"operationId":"getHealth","summary":"Configuration health (no database). Add ?ready=1 for a cached database probe.","responses":{"200":{"description":"Ready."},"503":{"description":"Not configured (fails closed)."}}}}},"components":{"schemas":{"MatchRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"url":{"type":"string","maxLength":2000},"description":{"type":"string","maxLength":4000},"capabilities":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"jobs_to_be_done":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"use_cases":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"price":{"type":"object","properties":{"amount":{"type":"number","minimum":0,"maximum":1000000000000},"currency":{"type":"string","pattern":"^[A-Z]{3,5}$"},"unit":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","minLength":1,"maxLength":500}},"additionalProperties":false},"service_area":{"type":"object","properties":{"regions":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"remote":{"type":"boolean"},"description":{"type":"string","minLength":1,"maxLength":500}},"additionalProperties":false},"languages":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8}){0,3}$"}},"constraints":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"exclude":{"default":[],"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"geography":{"type":"string","minLength":1,"maxLength":500},"industry":{"type":"string","minLength":1,"maxLength":500},"buyer_type":{"type":"string","minLength":1,"maxLength":500},"min_match":{"default":"possible","type":"string","enum":["strong","possible","weak"]},"freshness":{"default":"30d","type":"string","enum":["24h","7d","30d","90d","365d"]},"require_known_date":{"default":false,"type":"boolean"},"include_ambiguous":{"default":false,"type":"boolean"},"search_languages":{"maxItems":4,"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8}){0,3}$"}},"source_types":{"default":["web","procurement","forum"],"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["web","procurement","forum"]}},"max_results":{"default":10,"type":"integer","minimum":1,"maximum":20},"preferred_output_language":{"type":"string","pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8}){0,3}$"},"max_price_usdc":{"type":"number","exclusiveMinimum":0,"maximum":1000}},"additionalProperties":false},"Report":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"request_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"},"status":{"type":"string","const":"completed"},"seller":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}]},"summary":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"url_retrieved":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["name","url","summary","capabilities","url_retrieved"],"additionalProperties":false},"searched_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"query":{},"language":{"type":"object","properties":{"seller":{"type":"string"},"seller_confidence":{"type":"string","enum":["high","low"]},"output":{"type":"string"},"output_basis":{"type":"string","enum":["explicit","detected","fallback"]},"search":{"type":"array","items":{"type":"string"}},"note":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["seller","seller_confidence","output","output_basis","search","note"],"additionalProperties":false},"matches":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer","minimum":1,"maximum":9007199254740991},"intent":{"type":"object","properties":{"state":{"type":"string","enum":["CONFIRMED_INTENT","LIKELY_INTENT","AMBIGUOUS","NOT_INTENT"]},"type":{"type":"string"},"original_text":{"type":"string"},"original_language":{"type":"string"},"translation":{"anyOf":[{"type":"string"},{"type":"null"}]},"normalized_need":{"type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"buyer":{"type":"object","properties":{"organization":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["organization","type"],"additionalProperties":false},"geography":{"anyOf":[{"type":"string"},{"type":"null"}]},"geography_basis":{"type":"string","enum":["structured_field","verbatim_quote","unknown"]},"published_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"source_url":{"type":"string","format":"uri"},"source_type":{"type":"string","enum":["public_procurement","forum","web_page","demo"]},"source_name":{"type":"string"}},"required":["state","type","original_text","original_language","translation","normalized_need","title","buyer","geography","geography_basis","published_at","source_url","source_type","source_name"],"additionalProperties":false},"match":{"type":"object","properties":{"classification":{"type":"string","enum":["STRONG_MATCH","POSSIBLE_MATCH","WEAK_MATCH","NOT_A_MATCH"]},"reasons":{"type":"array","items":{"type":"string"}},"capability_matches":{"type":"array","items":{"type":"object","properties":{"seller_capability":{"type":"string"},"buyer_need":{"type":"string"},"buyer_quote":{"type":"string"}},"required":["seller_capability","buyer_need","buyer_quote"],"additionalProperties":false}},"constraints_satisfied":{"type":"array","items":{"type":"object","properties":{"statement":{"type":"string"},"buyer_quote":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["statement","buyer_quote"],"additionalProperties":false}},"constraints_conflicting":{"type":"array","items":{"type":"object","properties":{"statement":{"type":"string"},"buyer_quote":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["statement","buyer_quote"],"additionalProperties":false}},"uncertainties":{"type":"array","items":{"type":"string"}}},"required":["classification","reasons","capability_matches","constraints_satisfied","constraints_conflicting","uncertainties"],"additionalProperties":false},"evidence":{"minItems":1,"type":"array","items":{"type":"object","properties":{"source_url":{"type":"string","format":"uri"},"quoted_or_extracted_fact":{"type":"string"},"kind":{"type":"string","enum":["verbatim_quote","structured_field"]},"retrieved_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["source_url","quoted_or_extracted_fact","kind","retrieved_at"],"additionalProperties":false}},"freshness":{"type":"object","properties":{"published_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"published_at_basis":{"anyOf":[{"type":"string","enum":["source_api","json_ld","meta_tag","html_time_element"]},{"type":"null"}]},"last_updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]},"retrieved_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"age_days":{"anyOf":[{"type":"number"},{"type":"null"}]},"within_window":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"window":{"type":"string","enum":["24h","7d","30d","90d","365d"]},"request_status":{"type":"string","enum":["open","closed","resolved","expired","unknown"]},"status_basis":{"type":"string"},"deadline_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"},{"type":"null"}]}},"required":["published_at","published_at_basis","last_updated_at","retrieved_at","age_days","within_window","window","request_status","status_basis","deadline_at"],"additionalProperties":false},"confidence":{"type":"object","properties":{"intent":{"type":"string","enum":["high","medium","low"]},"match":{"type":"string","enum":["high","medium","low"]},"basis":{"type":"string"}},"required":["intent","match","basis"],"additionalProperties":false}},"required":["rank","intent","match","evidence","freshness","confidence"],"additionalProperties":false}},"rejected_signals":{"type":"array","items":{"type":"object","properties":{"source_url":{"type":"string"},"source_type":{"type":"string","enum":["public_procurement","forum","web_page","demo"]},"reason":{"type":"string"},"intent_state":{"anyOf":[{"type":"string","enum":["CONFIRMED_INTENT","LIKELY_INTENT","AMBIGUOUS","NOT_INTENT"]},{"type":"null"}]},"match_classification":{"anyOf":[{"type":"string","enum":["STRONG_MATCH","POSSIBLE_MATCH","WEAK_MATCH","NOT_A_MATCH"]},{"type":"null"}]},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source_url","source_type","reason","intent_state","match_classification","published_at"],"additionalProperties":false}},"search_summary":{"type":"object","properties":{"freshness_window":{"type":"string","enum":["24h","7d","30d","90d","365d"]},"source_families":{"type":"array","items":{"type":"string","enum":["web","procurement","forum"]}},"queries":{"type":"array","items":{"type":"object","properties":{"family":{"type":"string","enum":["web","procurement","forum"]},"query":{"type":"string"},"language":{"type":"string"}},"required":["family","query","language"],"additionalProperties":false}},"sources_retrieved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sources_classified":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"by_intent_state":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"failed_sources":{"type":"array","items":{"type":"string"}}},"required":["freshness_window","source_families","queries","sources_retrieved","sources_classified","by_intent_state","failed_sources"],"additionalProperties":false},"ranking_method":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}},"cost":{"type":"object","properties":{"amount":{"type":"string"},"currency":{"type":"string","const":"USDC"},"pricing_version":{"type":"string"}},"required":["amount","currency","pricing_version"],"additionalProperties":false},"retention":{"type":"object","properties":{"expires_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["expires_at"],"additionalProperties":false},"mode":{"type":"string","enum":["demo","live"]}},"required":["request_id","status","seller","searched_at","query","language","matches","rejected_signals","search_summary","ranking_method","limitations","cost","retention","mode"],"additionalProperties":false},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","invalid_json","invalid_encoding","invalid_url","unsupported_media_type","request_too_large","request_timeout","idempotency_key_required","idempotency_conflict","payment_reused","price_exceeds_ceiling","seller_url_unavailable","unauthorized","not_found","expired","rate_limited","not_configured","payment_provider_unavailable","settlement_unknown","provider_unavailable","service_unavailable"]},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object"}}}}}},"CityQuote":{"type":"object","description":"Present when a referral token was sent. The amount due is city_price (equal to normal_price when no discount applies).","properties":{"normal_price":{"type":"string"},"city_discount":{"type":"string"},"city_price":{"type":"string"},"city_advantage_applied":{"type":"boolean"},"city_referral_id":{"type":["string","null"]},"city_discount_percent":{"type":["string","null"]},"city_advantage_reason":{"type":"string"}}}}}}