{"openapi":"3.1.0","info":{"title":"Nexez Agent API","version":"0.1.0","description":"Discovery and checkout handoff API for AI-readable product and service listings.","x-nexez-agent-distribution":{"docs_url":"https://nexez.ai/agents","runtime_base_url":"https://nexez.app","llms_url":"https://nexez.app/llms.txt","agent_index_url":"https://nexez.app/agent-pages.json","agent_search_url_template":"https://nexez.app/api/agent-search?q={query}","openapi_url":"https://nexez.app/openapi.json","capabilities_url":"https://nexez.app/.well-known/nexez.json","mcp_discovery_url":"https://nexez.app/.well-known/mcp.json","openclaw":{"plugin":{"name":"@nexez/openclaw-nexez","displayName":"Nexez OpenClaw Plugin","version":"0.3.0","installCommand":"openclaw plugins install clawhub:@nexez/openclaw-nexez","purpose":"Native tools for search, listing fetch, appointment booking, checkout validation, and negotiation handoff.","tools":["nexez_search","nexez_get_page","nexez_directory","nexez_get_negotiation_status","nexez_wait_for_negotiation_decision","nexez_validate_checkout","nexez_validate_negotiation","nexez_start_checkout","nexez_submit_negotiation","nexez_booking_options","nexez_validate_booking","nexez_book_appointment","nexez_validate_booking_note","nexez_add_booking_note"]},"skill":{"slug":"nexez-agent-discovery","displayName":"Nexez Agent Discovery","version":"0.1.2","installCommand":"openclaw skills install nexez-agent-discovery","purpose":"Instructions and rubrics for discovering, comparing, and safely acting on Nexez agent listings."}},"examples":{"sourcePath":"examples/agents","sourceUrl":"https://github.com/nexez-ai/nexez-agent-examples/tree/main","purpose":"Copy-paste buyer-agent workflows for search, validation, negotiation submission, and status polling."},"sdks":{"typescript":{"name":"@nexez/agent-sdk","displayName":"Nexez Agent SDK","version":"0.4.0","status":"published","installCommand":"npm install @nexez/agent-sdk","npmUrl":"https://www.npmjs.com/package/@nexez/agent-sdk","sourcePath":"sdk/typescript","sourceUrl":"https://www.npmjs.com/package/@nexez/agent-sdk","purpose":"Typed client helpers for agent search, manifest fetch, appointment booking, checkout dry-run, and negotiation handoff."},"python":{"name":"nexez-agent-sdk","moduleName":"nexez_agent_sdk","displayName":"Nexez Python Agent SDK","version":"0.4.0","status":"published","installCommand":"python -m pip install nexez-agent-sdk","pypiUrl":"https://pypi.org/project/nexez-agent-sdk/","sourcePath":"sdk/python","sourceUrl":"https://pypi.org/project/nexez-agent-sdk/","localInstallCommand":"python -m pip install -e sdk/python","purpose":"Dependency-free Python helpers for agent search, manifest fetch, appointment booking, checkout dry-run, and negotiation handoff."}}}},"servers":[{"url":"https://nexez.app"}],"paths":{"/api/agent-search":{"get":{"summary":"Search published agent listings and offers","operationId":"searchAgentPages","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Buyer request or search query, such as strategy session or consulting."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"location","in":"query","required":false,"schema":{"type":"string"},"description":"City, region, or service area to filter results, such as Chicago, IL or Austin, TX."},{"name":"lat","in":"query","required":false,"schema":{"type":"number"},"description":"Optional buyer latitude for future location-aware clients. Use with location when available."},{"name":"lng","in":"query","required":false,"schema":{"type":"number"},"description":"Optional buyer longitude for future location-aware clients. Use with location when available."},{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["all","professional","consumer"]}},{"name":"industry","in":"query","required":false,"schema":{"type":"string"}},{"name":"min_readiness","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"min_trust","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100}},{"name":"verified","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"nexez_checkout_ready","in":"query","required":false,"description":"Require private payout and Nexez-settlement readiness.","schema":{"type":"boolean"}},{"name":"supports_checkout","in":"query","required":false,"deprecated":true,"description":"Compatibility filter for any actionable offer or external handoff.","schema":{"type":"boolean"}},{"name":"supports_negotiation","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"price_band","in":"query","required":false,"schema":{"type":"string","enum":["free","under_100","100_500","500_2000","2000_plus","custom"]}}],"responses":{"200":{"description":"Offer-level matches with checkout URLs and listing manifests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSearchResponse"}}}}}}},"/agent-pages.json":{"get":{"summary":"List published agent listings","operationId":"listAgentPages","responses":{"200":{"description":"Published listing index with manifest and checkout URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPageIndex"}}}}}}},"/.well-known/mcp.json":{"get":{"summary":"List MCP-enabled agent listings","operationId":"listMcpEnabledAgentPages","responses":{"200":{"description":"Discovery catalog for listings exposing MCP-compatible resources.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpDiscoveryCatalog"}}}}}}},"/{slug}/agent.json":{"get":{"summary":"Read one published listing manifest","operationId":"getAgentPageManifest","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Structured seller, offer, FAQ, and checkout context.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentPageManifest"}}}},"404":{"description":"No published listing for this slug."}}}},"/api/checkout":{"post":{"summary":"Start checkout handoff for an offer","operationId":"startAgentCheckout","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":16,"maxLength":255,"pattern":"^[A-Za-z0-9._~:-]+$"},"description":"Stable retry key for this exact action. Reuse only when retrying the same approved payload."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","offer"],"properties":{"slug":{"type":"string"},"offer":{"type":"string","description":"Offer key such as services-0 or products-0."},"query":{"type":"string","description":"Optional buyer request or agent context."},"buyerEmail":{"type":"string","description":"Optional buyer email. Prefills Stripe checkout and enables the buyer receipt + order portal."},"buyerName":{"type":"string","description":"Optional buyer or business name recorded on the order."},"buyerReference":{"type":"string","description":"Optional buyer-side reference / order id; also stamped on the Stripe session (client_reference_id)."},"buyerAgent":{"type":"string","description":"Optional identifier for the buying agent."},"approvalToken":{"type":"string","description":"Short-lived token returned by a matching dry-run validation."},"dryRun":{"type":"boolean","description":"When true, validate and log checkout intent without creating a Stripe session or redirecting.","default":false},"offerConfiguration":{"type":"object","description":"Buyer values keyed by the target offer's merchant-authored customer input fields. Unknown fields are rejected. Read the offer's agent.json configuration.input_schema for exact keys/types and configuration.checkout.path for the correct one-time or recurring checkout rail.","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"},"maxItems":25}]}}}}}}},"responses":{"200":{"description":"Provider redirect or Stripe Checkout URL.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"ok":{"type":"boolean"},"provider":{"type":"string"},"checkoutUrl":{"type":"string"},"actionUrl":{"type":["string","null"]},"stripeConfigured":{"type":"boolean"},"checkoutSessionId":{"type":"string"},"approvalTokenRequired":{"type":"boolean"},"approvalToken":{"type":"string"},"approvalExpiresAt":{"type":"string","format":"date-time"},"events":{"type":"object","additionalProperties":{"type":"boolean"}},"amountCents":{"type":["integer","null"],"description":"Exact final checkout amount in Stripe smallest units when Nexez can resolve a price."},"offerConfiguration":{"type":"object"},"offerConfigurationFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"offerPricing":{"type":"object","description":"Exact deterministic checkout-time pricing snapshot in Stripe smallest units.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"currency":{"type":"string"},"baseAmount":{"type":"integer"},"adjustments":{"type":"array","items":{"type":"object","properties":{"fieldKey":{"type":"string"},"label":{"type":"string"},"value":{},"model":{"type":"string","enum":["option-delta","boolean-delta","quantity-delta"]},"rule":{"type":"object"},"amount":{"type":"integer"}}}},"adjustmentAmount":{"type":"integer"},"finalAmount":{"type":"integer","minimum":1}},"required":["schemaVersion","currency","baseAmount","adjustments","adjustmentAmount","finalAmount"]},"offerPricingFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"offerFulfillment":{"type":"object","description":"Deterministic checkout-time evaluation of the exact merchant-authored conditional fulfillment policy used for this buyer configuration.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"policyRules":{"type":"array","description":"Exact normalized merchant rule set evaluated at checkout time.","items":{"type":"object"}},"decision":{"type":"string","enum":["eligible","requires-review","ineligible"]},"matchedRuleIds":{"type":"array","items":{"type":"string"}},"reasons":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"inputKey":{"type":"string"},"decision":{"type":"string","enum":["requires-review","ineligible"]},"reasonCode":{"type":"string"},"message":{"type":"string"},"nextAction":{"type":"string","enum":["contact-merchant","send-proposal"]}},"required":["ruleId","inputKey","decision","reasonCode","message"]}}},"required":["schemaVersion","policyRules","decision","matchedRuleIds","reasons"]},"offerFulfillmentFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}}}}}},"404":{"description":"Listing or offer not found."},"409":{"description":"Checkout is not configured for this offer."}}}},"/api/negotiations":{"post":{"summary":"Create an agent-to-agent proposal","operationId":"createAgentNegotiation","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":16,"maxLength":255,"pattern":"^[A-Za-z0-9._~:-]+$"},"description":"Stable retry key for this exact action. Reuse only when retrying the same approved payload."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","offer"],"properties":{"slug":{"type":"string"},"offer":{"type":"string"},"buyerAgent":{"type":"string"},"query":{"type":"string"},"requestedTerms":{"type":"object","description":"Requested work and limits. Use the named fields when possible. Other terms remain available for seller review.","additionalProperties":true,"properties":{"scope":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"maxItems":20}],"description":"Work the buyer wants included."},"deliverables":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"maxItems":20}],"description":"Specific items the seller should deliver."},"revisionCount":{"type":"integer","minimum":0,"maximum":1000,"description":"Number of requested revision rounds."},"projectWeeks":{"type":"integer","minimum":1,"maximum":1000,"description":"Requested project length in weeks."},"constraints":{"description":"Other buyer requirements for seller review."}}},"budget":{"type":"string"},"timeline":{"type":"string"},"contact":{"type":"string"},"negotiationId":{"type":"string","description":"Existing negotiation id for a follow-up turn."},"statusToken":{"type":"string","description":"Private bearer token for an existing negotiation."},"approvalToken":{"type":"string","description":"Short-lived token returned by a matching dry-run validation."},"dryRun":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Negotiation created or validated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentNegotiationResponse"}}}},"412":{"description":"Negotiation table migration has not been applied."}}}},"/api/v1/pages":{"get":{"summary":"List your listings (programmatic API)","operationId":"listOwnerPages","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Listings owned by the authenticated API key.","content":{"application/json":{"schema":{"type":"object","properties":{"pages":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Missing, invalid, or revoked API key."},"503":{"description":"Programmatic API not configured on this deployment."}}},"post":{"summary":"Create a listing (programmatic API)","operationId":"createOwnerPage","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Optional; auto-generated + de-duplicated if omitted."},"description":{"type":"string"},"website_url":{"type":"string"},"industry":{"type":"string"},"services":{"type":"array","items":{"type":"object"}},"products":{"type":"array","items":{"type":"object"}},"faqs":{"type":"array","items":{"type":"object"}},"is_published":{"type":"boolean","default":false,"description":"Defaults to draft."},"custom_domain":{"type":"string"},"domain_path":{"type":"string"}}}}}},"responses":{"201":{"description":"Created listing + public URL.","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"object"},"url":{"type":"string"}}}}}},"400":{"description":"Missing name or invalid body."},"401":{"description":"Missing, invalid, or revoked API key."},"503":{"description":"Programmatic API not configured on this deployment."}}}},"/api/v1/pages/{id}":{"get":{"summary":"Get one of your listings (programmatic API)","operationId":"getOwnerPage","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The listing.","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"object"}}}}}},"401":{"description":"Missing, invalid, or revoked API key."},"404":{"description":"Listing not found for this owner."},"503":{"description":"Programmatic API not configured on this deployment."}}},"patch":{"summary":"Update one of your listings (programmatic API)","operationId":"updateOwnerPage","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Any writable listing fields (name, description, services, products, faqs, is_published, custom_domain, domain_path, ...)."}}}},"responses":{"200":{"description":"Updated listing + public URL.","content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"object"},"url":{"type":"string"}}}}}},"400":{"description":"No writable fields or invalid body."},"401":{"description":"Missing, invalid, or revoked API key."},"404":{"description":"Listing not found for this owner."},"503":{"description":"Programmatic API not configured on this deployment."}}}},"/api/service-agreements/checkout":{"post":{"summary":"Create or dry-run a merchant-authored recurring service agreement","operationId":"startAgentCheckout","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":16,"maxLength":255,"pattern":"^[A-Za-z0-9._~:-]+$"},"description":"Stable retry key for this exact action. Reuse only when retrying the same approved payload."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","offer"],"properties":{"slug":{"type":"string"},"offer":{"type":"string","description":"Offer key such as services-0 or products-0."},"query":{"type":"string","description":"Optional buyer request or agent context."},"buyerEmail":{"type":"string","description":"Optional buyer email. Prefills Stripe checkout and enables the buyer receipt + order portal."},"buyerName":{"type":"string","description":"Optional buyer or business name recorded on the order."},"buyerReference":{"type":"string","description":"Optional buyer-side reference / order id; also stamped on the Stripe session (client_reference_id)."},"buyerAgent":{"type":"string","description":"Optional identifier for the buying agent."},"approvalToken":{"type":"string","description":"Short-lived token returned by a matching dry-run validation."},"dryRun":{"type":"boolean","description":"When true, validate and log checkout intent without creating a Stripe session or redirecting.","default":false},"offerConfiguration":{"type":"object","description":"Buyer values keyed by the target offer's merchant-authored customer input fields. Unknown fields are rejected. Read the offer's agent.json configuration.input_schema for exact keys/types and configuration.checkout.path for the correct one-time or recurring checkout rail.","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"},"maxItems":25}]}}}}}}},"responses":{"200":{"description":"Provider redirect or Stripe Checkout URL.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"ok":{"type":"boolean"},"provider":{"type":"string"},"checkoutUrl":{"type":"string"},"actionUrl":{"type":["string","null"]},"stripeConfigured":{"type":"boolean"},"checkoutSessionId":{"type":"string"},"approvalTokenRequired":{"type":"boolean"},"approvalToken":{"type":"string"},"approvalExpiresAt":{"type":"string","format":"date-time"},"events":{"type":"object","additionalProperties":{"type":"boolean"}},"amountCents":{"type":["integer","null"],"description":"Exact final checkout amount in Stripe smallest units when Nexez can resolve a price."},"offerConfiguration":{"type":"object"},"offerConfigurationFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"offerPricing":{"type":"object","description":"Exact deterministic checkout-time pricing snapshot in Stripe smallest units.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"currency":{"type":"string"},"baseAmount":{"type":"integer"},"adjustments":{"type":"array","items":{"type":"object","properties":{"fieldKey":{"type":"string"},"label":{"type":"string"},"value":{},"model":{"type":"string","enum":["option-delta","boolean-delta","quantity-delta"]},"rule":{"type":"object"},"amount":{"type":"integer"}}}},"adjustmentAmount":{"type":"integer"},"finalAmount":{"type":"integer","minimum":1}},"required":["schemaVersion","currency","baseAmount","adjustments","adjustmentAmount","finalAmount"]},"offerPricingFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"offerFulfillment":{"type":"object","description":"Deterministic checkout-time evaluation of the exact merchant-authored conditional fulfillment policy used for this buyer configuration.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"policyRules":{"type":"array","description":"Exact normalized merchant rule set evaluated at checkout time.","items":{"type":"object"}},"decision":{"type":"string","enum":["eligible","requires-review","ineligible"]},"matchedRuleIds":{"type":"array","items":{"type":"string"}},"reasons":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"inputKey":{"type":"string"},"decision":{"type":"string","enum":["requires-review","ineligible"]},"reasonCode":{"type":"string"},"message":{"type":"string"},"nextAction":{"type":"string","enum":["contact-merchant","send-proposal"]}},"required":["ruleId","inputKey","decision","reasonCode","message"]}}},"required":["schemaVersion","policyRules","decision","matchedRuleIds","reasons"]},"offerFulfillmentFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"recurringAgreement":{"type":"object","description":"Exact buyer-approval-bound recurring service agreement snapshot.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"terms":{"type":"object"},"resolvedSchedule":{"type":"object","properties":{"interval":{"type":"string","enum":["day","week","month","year"]},"intervalCount":{"type":"integer","minimum":1},"source":{"type":"string","enum":["fixed","buyer-option"]},"inputKey":{"type":"string"},"inputValue":{"type":"string"}},"required":["interval","intervalCount","source"]},"configuration":{"type":"object"},"fulfillment":{"type":"object","description":"Deterministic checkout-time evaluation of the exact merchant-authored conditional fulfillment policy used for this buyer configuration.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"policyRules":{"type":"array","description":"Exact normalized merchant rule set evaluated at checkout time.","items":{"type":"object"}},"decision":{"type":"string","enum":["eligible","requires-review","ineligible"]},"matchedRuleIds":{"type":"array","items":{"type":"string"}},"reasons":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"inputKey":{"type":"string"},"decision":{"type":"string","enum":["requires-review","ineligible"]},"reasonCode":{"type":"string"},"message":{"type":"string"},"nextAction":{"type":"string","enum":["contact-merchant","send-proposal"]}},"required":["ruleId","inputKey","decision","reasonCode","message"]}}},"required":["schemaVersion","policyRules","decision","matchedRuleIds","reasons"]},"pricing":{"oneOf":[{"type":"object","description":"Exact deterministic checkout-time pricing snapshot in Stripe smallest units.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"currency":{"type":"string"},"baseAmount":{"type":"integer"},"adjustments":{"type":"array","items":{"type":"object","properties":{"fieldKey":{"type":"string"},"label":{"type":"string"},"value":{},"model":{"type":"string","enum":["option-delta","boolean-delta","quantity-delta"]},"rule":{"type":"object"},"amount":{"type":"integer"}}}},"adjustmentAmount":{"type":"integer"},"finalAmount":{"type":"integer","minimum":1}},"required":["schemaVersion","currency","baseAmount","adjustments","adjustmentAmount","finalAmount"]},{"type":"null"}]},"amountPerPeriod":{"type":"integer","minimum":1},"currency":{"type":"string"}},"required":["schemaVersion","terms","resolvedSchedule","configuration","fulfillment","pricing","amountPerPeriod","currency"]},"recurringAgreementFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"serviceAgreementId":{"type":"string","format":"uuid"}}}}}},"404":{"description":"Listing or offer not found."},"409":{"description":"Checkout is not configured for this offer."}},"description":"Recurring service offers must use this endpoint. Dry-run resolves exact cadence, per-period pricing, configuration, conditional fulfillment decision, and agreement fingerprint before buyer approval."}},"/api/reservable-resources/checkout":{"post":{"summary":"Atomically hold merchant-authored resources and start immediate checkout","operationId":"startAgentCheckout","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":16,"maxLength":255},"description":"Use the exact same key for dry-run approval and the live payment request."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","offer"],"properties":{"slug":{"type":"string"},"offer":{"type":"string","description":"Offer key such as services-0 or products-0."},"query":{"type":"string","description":"Optional buyer request or agent context."},"buyerEmail":{"type":"string","description":"Optional buyer email. Prefills Stripe checkout and enables the buyer receipt + order portal."},"buyerName":{"type":"string","description":"Optional buyer or business name recorded on the order."},"buyerReference":{"type":"string","description":"Optional buyer-side reference / order id; also stamped on the Stripe session (client_reference_id)."},"buyerAgent":{"type":"string","description":"Optional identifier for the buying agent."},"approvalToken":{"type":"string","description":"Short-lived token returned by a matching dry-run validation."},"dryRun":{"type":"boolean","description":"When true, validate and log checkout intent without creating a Stripe session or redirecting.","default":false},"offerConfiguration":{"type":"object","description":"Buyer values keyed by the target offer's merchant-authored customer input fields. Unknown fields are rejected. Read the offer's agent.json configuration.input_schema for exact keys/types and configuration.checkout.path for the correct one-time or recurring checkout rail.","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"},"maxItems":25}]}}}}}}},"responses":{"200":{"description":"Provider redirect or Stripe Checkout URL.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"ok":{"type":"boolean"},"provider":{"type":"string"},"checkoutUrl":{"type":"string"},"actionUrl":{"type":["string","null"]},"stripeConfigured":{"type":"boolean"},"checkoutSessionId":{"type":"string"},"approvalTokenRequired":{"type":"boolean"},"approvalToken":{"type":"string"},"approvalExpiresAt":{"type":"string","format":"date-time"},"events":{"type":"object","additionalProperties":{"type":"boolean"}},"amountCents":{"type":["integer","null"],"description":"Exact final checkout amount in Stripe smallest units when Nexez can resolve a price."},"offerConfiguration":{"type":"object"},"offerConfigurationFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"offerPricing":{"type":"object","description":"Exact deterministic checkout-time pricing snapshot in Stripe smallest units.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"currency":{"type":"string"},"baseAmount":{"type":"integer"},"adjustments":{"type":"array","items":{"type":"object","properties":{"fieldKey":{"type":"string"},"label":{"type":"string"},"value":{},"model":{"type":"string","enum":["option-delta","boolean-delta","quantity-delta"]},"rule":{"type":"object"},"amount":{"type":"integer"}}}},"adjustmentAmount":{"type":"integer"},"finalAmount":{"type":"integer","minimum":1}},"required":["schemaVersion","currency","baseAmount","adjustments","adjustmentAmount","finalAmount"]},"offerPricingFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"offerFulfillment":{"type":"object","description":"Deterministic checkout-time evaluation of the exact merchant-authored conditional fulfillment policy used for this buyer configuration.","properties":{"schemaVersion":{"type":"integer","enum":[1]},"policyRules":{"type":"array","description":"Exact normalized merchant rule set evaluated at checkout time.","items":{"type":"object"}},"decision":{"type":"string","enum":["eligible","requires-review","ineligible"]},"matchedRuleIds":{"type":"array","items":{"type":"string"}},"reasons":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"inputKey":{"type":"string"},"decision":{"type":"string","enum":["requires-review","ineligible"]},"reasonCode":{"type":"string"},"message":{"type":"string"},"nextAction":{"type":"string","enum":["contact-merchant","send-proposal"]}},"required":["ruleId","inputKey","decision","reasonCode","message"]}}},"required":["schemaVersion","policyRules","decision","matchedRuleIds","reasons"]},"offerFulfillmentFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"resources":{"type":"object","description":"Authoritative production resource hold acquired during dry-run. This is not a committed reservation until the matching payment event succeeds.","properties":{"status":{"type":"string","enum":["held"]},"holdId":{"type":"string","format":"uuid"},"expiresAt":{"type":"string","format":"date-time"},"allocationFingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"allocations":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"object","properties":{"poolId":{"type":"string","format":"uuid"},"poolKey":{"type":"string"},"poolLabel":{"type":"string"},"poolVersion":{"type":"integer","minimum":1},"kind":{"type":"string","enum":["consumable","reusable"]},"unit":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":10000},"windowId":{"type":["string","null"],"format":"uuid"},"windowVersion":{"type":["integer","null"],"minimum":1},"startsAt":{"type":["string","null"],"format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"}},"required":["poolId","poolVersion","kind","unit","quantity"]}}},"required":["status","holdId","expiresAt","allocationFingerprint","allocations"]}}}}}},"404":{"description":"Listing or offer not found."},"409":{"description":"Checkout is not configured for this offer."}},"description":"Reservable-resource offers must use this endpoint. Dry-run requires an Idempotency-Key and acquires a real expiring hold from the same production resolver used for payment."}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"nxz_live_…","description":"Nexez API key. Create one in Dashboard → Tools → Developer Platform. Send as: Authorization: Bearer nxz_live_…"}},"schemas":{"AgentSearchResponse":{"type":"object","properties":{"schema_version":{"type":"string"},"ranking_policy":{"type":"string","const":"nexez.discovery-ranking.v1"},"query":{"type":"string"},"result_count":{"type":"integer"},"filters":{"type":"object"},"results":{"type":"array","items":{"$ref":"#/components/schemas/AgentSearchResult"}}}},"AgentSearchResult":{"type":"object","properties":{"score":{"type":"number"},"matched_query_terms":{"type":"array","items":{"type":"string"}},"match_reasons":{"type":"array","items":{"type":"string"}},"ranking":{"type":"object","properties":{"policy_version":{"type":"string","const":"nexez.discovery-ranking.v1"},"relevance":{"type":"number"},"location":{"type":"string"},"availability":{"type":"string"},"actionability":{"type":"string"},"seller_verified":{"type":"boolean"},"agent_ready_certified":{"type":"boolean"},"verified_purchase_reviews":{"type":"integer"},"reputation":{"type":["number","null"]},"review_evidence":{"type":"string"},"readiness":{"type":"integer"},"freshness":{"type":"string"}}},"page":{"type":"object"},"offer":{"type":["object","null"]}}},"AgentPageIndex":{"type":"object","properties":{"schema_version":{"type":"string"},"llms_url":{"type":"string"},"openapi_url":{"type":"string"},"pages":{"type":"array","items":{"type":"object"}}}},"McpDiscoveryCatalog":{"type":"object","properties":{"schema_version":{"type":"string"},"generated_at":{"type":"string"},"protocol_note":{"type":"string"},"homepage_url":{"type":"string"},"llms_url":{"type":"string"},"capabilities_url":{"type":"string"},"agent_index_url":{"type":"string"},"page_count":{"type":"integer"},"pages":{"type":"array","items":{"type":"object"}}}},"AgentPageManifest":{"type":"object","properties":{"schema_version":{"type":"string"},"page":{"type":"object"},"offers":{"type":"array","items":{"type":"object"}},"faqs":{"type":"array","items":{"type":"object"}},"plain_text":{"type":"string"}}},"AgentNegotiationResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"dryRun":{"type":"boolean"},"negotiationId":{"type":"string"},"status":{"type":"string"},"decisionPending":{"type":"boolean"},"persistentLink":{"type":"string"},"negotiationUrl":{"type":"string"},"statusToken":{"type":"string"},"statusUrl":{"type":"string"},"escrowMode":{"type":"string"},"stripeConfigured":{"type":"boolean"},"next":{"type":"string"},"publicPageUrl":{"type":"string"},"replayed":{"type":"boolean"},"idempotencyKeyAccepted":{"type":"boolean"},"approvalTokenRequired":{"type":"boolean"},"approvalToken":{"type":"string"},"approvalExpiresAt":{"type":"string","format":"date-time"},"rulesEvaluation":{"type":"object","description":"Deterministic price and requested-term checks returned by a dry run."}}}}}}