{"openapi":"3.1.0","info":{"title":"Agent Offers API","version":"1.0.0","description":"Create a current, machine-readable commercial offer with price, capability, terms, evidence and a direct purchase path. Agent Offers analyses your product URL, OpenAPI, llms.txt, schema.org data and x402 endpoint, labels every commercial field VERIFIED, SELLER_PROVIDED, INFERRED or UNKNOWN, never invents a price, and publishes a signed offer document that buyer agents can read for free.\n\nPrice: 0.049 USDC per paid offer revision via x402 on Base mainnet (eip155:8453). Operator: Active Life Hub LLC.","x-operator":"Active Life Hub LLC"},"servers":[{"url":"https://agentoffers.online"}],"components":{"securitySchemes":{"managementKey":{"type":"http","scheme":"bearer","description":"aom_<epoch>_<key> returned at creation (or rotation)."}},"schemas":{"OfferInput":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"sources":{"type":"object","properties":{"docs_url":{"type":"string","minLength":1,"maxLength":2048},"openapi_url":{"type":"string","minLength":1,"maxLength":2048},"llms_txt_url":{"type":"string","minLength":1,"maxLength":2048},"pricing_url":{"type":"string","minLength":1,"maxLength":2048},"descriptor_url":{"type":"string","minLength":1,"maxLength":2048},"terms_url":{"type":"string","minLength":1,"maxLength":2048}},"additionalProperties":false},"seller":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"url":{"type":"string","minLength":1,"maxLength":2048}},"additionalProperties":false},"product":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","minLength":1,"maxLength":2000},"category":{"type":"string","minLength":1,"maxLength":120},"capabilities":{"maxItems":25,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"jobs_to_be_done":{"maxItems":25,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"use_cases":{"maxItems":25,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"translations":{"type":"object","propertyNames":{"type":"string","maxLength":35,"pattern":"^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$"},"additionalProperties":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false}}},"additionalProperties":false},"commercial_terms":{"type":"object","properties":{"price":{"type":"object","properties":{"model":{"type":"string","enum":["one_time","per_request","usage","subscription","fixed","quote_required","free"]},"amount":{"anyOf":[{"type":"string","maxLength":40},{"type":"number"}]},"currency":{"type":"string","minLength":1,"maxLength":12},"network":{"type":"string","minLength":3,"maxLength":80},"asset":{"type":"string","minLength":1,"maxLength":128},"unit":{"type":"string","minLength":1,"maxLength":80},"per_quantity":{"type":"integer","minimum":1,"maximum":1000000000},"interval":{"type":"string","enum":["day","week","month","year"]},"original":{"type":"string","minLength":1,"maxLength":300}},"additionalProperties":false},"minimum_purchase":{"type":"string","minLength":1,"maxLength":200},"included_usage":{"type":"string","minLength":1,"maxLength":500},"additional_fees":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"amount":{"anyOf":[{"type":"string","maxLength":40},{"type":"number"}]},"currency":{"type":"string","minLength":1,"maxLength":12},"description":{"type":"string","minLength":1,"maxLength":500}},"required":["name"],"additionalProperties":false}},"refund_terms":{"type":"object","properties":{"summary":{"type":"string","minLength":1,"maxLength":2000},"url":{"type":"string","minLength":1,"maxLength":2048}},"additionalProperties":false}},"additionalProperties":false},"transaction":{"type":"object","properties":{"purchase_endpoint":{"type":"string","minLength":1,"maxLength":2048},"purchase_type":{"type":"string","enum":["x402_endpoint","api_endpoint","checkout_url","quote_request","contact"]},"http_method":{"type":"string","enum":["GET","POST","PUT","PATCH"]},"payment_protocol":{"type":"string","enum":["x402","card","invoice","bank_transfer","crypto_transfer","platform_billing","other"]},"authentication":{"type":"string","enum":["none","api_key","oauth2","account","other"]},"input_schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"output_schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"example_request":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"additionalProperties":false},"availability":{"type":"object","properties":{"status":{"type":"string","enum":["available","limited","unavailable","preorder"]},"service_area":{"type":"object","properties":{"scope":{"type":"string","enum":["global","regions"]},"regions":{"maxItems":250,"type":"array","items":{"type":"string","pattern":"^([A-Z]{2}(-[A-Z0-9]{1,3})?|\\d{3})$"}}},"required":["scope"],"additionalProperties":false},"jurisdictions":{"maxItems":25,"type":"array","items":{"type":"string","minLength":1,"maxLength":100}},"languages":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":35,"pattern":"^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$"}},"constraints":{"maxItems":25,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}}},"additionalProperties":false},"validity":{"type":"object","properties":{"valid_from":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,3})?)?(Z|[+-]\\d{2}:\\d{2}))?$"},"valid_until":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,3})?)?(Z|[+-]\\d{2}:\\d{2}))?$"},"freshness_days":{"type":"integer","minimum":1,"maximum":90}},"additionalProperties":false},"limitations":{"maxItems":25,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},"content_language":{"type":"string","maxLength":35,"pattern":"^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$"}},"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}},"x-pricing":{"amount":"0.049","currency":"USDC","network":"eip155:8453","unit":"paid offer revision","protocol":"x402"},"paths":{"/api/v1/offers":{"post":{"operationId":"createOffer","summary":"Create an offer (paid: 0.049 USDC via x402). Returns a DRAFT and a management key.","x-payment":{"protocol":"x402","amount":"0.049","currency":"USDC","network":"eip155:8453"},"parameters":[{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferInput"},"example":{"url":"https://vendorfinder.online","transaction":{"purchase_endpoint":"https://vendorfinder.online/api/v1/searches","payment_protocol":"x402"}}}}},"responses":{"200":{"description":"Idempotent replay of a settled payment."},"201":{"description":"Created (DRAFT); includes management_key once."},"402":{"description":"Payment required (x402 v2). The PAYMENT-REQUIRED header carries the requirement; retry with PAYMENT-SIGNATURE.","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"payment_reused | operation_in_progress","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"422":{"description":"invalid_offer (nothing charged)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"503":{"description":"not_configured | settlement_unknown","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"get":{"operationId":"listOffers","summary":"Simple discovery of published offers (free, cached; not a search engine).","parameters":[{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"capability","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"include","in":"query","schema":{"enum":["current","all"]}},{"name":"authority","in":"query","schema":{"enum":["any","DOMAIN_CONFIRMED"]}}],"responses":{"200":{"description":"Summaries (≤100)."}}}},"/api/v1/offers/preview":{"post":{"operationId":"previewOffer","summary":"Validate structured input and show the resulting offer and report (free; nothing fetched or stored).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferInput"}}}},"responses":{"200":{"description":"Preview"},"422":{"description":"invalid_offer","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/api/v1/offers/collection":{"get":{"operationId":"offerCollection","summary":"Hostable agent-offers.json for a domain (DOMAIN_CONFIRMED, published offers).","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Collection"}}}},"/api/v1/offers/{id}":{"get":{"operationId":"getOffer","summary":"Public offer document with read-time status (free, cached ≤60 s).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^off_[a-z2-7]{42}$"}},{"name":"lang","in":"query","schema":{"type":"string"},"description":"Include a seller-provided translation, if any (originals unchanged)."}],"responses":{"200":{"description":"Offer or paused notice"},"404":{"description":"offer_not_found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"410":{"description":"withdrawn","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"patch":{"operationId":"reviseOffer","summary":"Revise or refresh (paid: 0.049 USDC). JSON merge patch over the stored submission; {} = refresh.","security":[{"managementKey":[]}],"x-payment":{"protocol":"x402","amount":"0.049","currency":"USDC","network":"eip155:8453"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^off_[a-z2-7]{42}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Revised (draft until published)"},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"402":{"description":"Payment required (x402 v2). The PAYMENT-REQUIRED header carries the requirement; retry with PAYMENT-SIGNATURE.","content":{"application/json":{"schema":{"type":"object"}}}},"409":{"description":"concurrent_revision | offer_withdrawn","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}},"422":{"description":"invalid_offer","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/api/v1/offers/{id}/manage":{"get":{"operationId":"manageOffer","summary":"Private view: draft, published revision, lifecycle, authority challenge (free).","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^off_[a-z2-7]{42}$"}}],"responses":{"200":{"description":"Management view"},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/api/v1/offers/{id}/publish":{"post":{"operationId":"publishOffer","summary":"Publish the latest revision (free). Requires report.ready_for_agents and CURRENT terms.","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^off_[a-z2-7]{42}$"}}],"responses":{"200":{"description":"Published"},"422":{"description":"offer_not_ready | offer_not_current","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}},"/api/v1/offers/{id}/pause":{"post":{"operationId":"pauseOffer","summary":"Pause a published offer (free).","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^off_[a-z2-7]{42}$"}}],"responses":{"200":{"description":"Paused"}}}},"/api/v1/offers/{id}/withdraw":{"post":{"operationId":"withdrawOffer","summary":"Withdraw permanently (free).","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^off_[a-z2-7]{42}$"}}],"responses":{"200":{"description":"Withdrawn"}}}},"/api/v1/offers/{id}/authority":{"post":{"operationId":"confirmDomain","summary":"Check the domain-control challenge (free): {\"method\":\"dns_txt\"|\"http_well_known\",\"domain\":\"…\"}.","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^off_[a-z2-7]{42}$"}}],"responses":{"200":{"description":"confirmed | not_confirmed"}}}},"/api/v1/offers/{id}/rotate-key":{"post":{"operationId":"rotateKey","summary":"Rotate the management key (free).","security":[{"managementKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^off_[a-z2-7]{42}$"}}],"responses":{"200":{"description":"New key"}}}},"/api/v1/offers/{id}/artifact":{"get":{"operationId":"offerArtifact","summary":"Signed agent-offer.json for self-hosting (free).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^off_[a-z2-7]{42}$"}}],"responses":{"200":{"description":"Signed document"}}}},"/api/v1/documents/verify":{"post":{"operationId":"verifyDocument","summary":"Verify the signature and freshness of any Agent Offers document copy (free).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Result"}}}},"/api/v1/pricing":{"get":{"operationId":"pricing","summary":"Price, cost basis and margin (free).","responses":{"200":{"description":"Pricing"}}}},"/api/v1/health":{"get":{"operationId":"health","summary":"Configuration health (no database). ?ready=1 adds a cached database probe.","responses":{"200":{"description":"ok"},"503":{"description":"not_configured"}}}}},"x-limits":{"request_bytes":65536,"schema_bytes":16384,"freshness_days_default":30,"freshness_days_max":90,"public_cache_seconds":60}}