{"openapi":"3.1.0","info":{"title":"RQM Relay API","version":"0.1.0","description":"Discovery, comparison, quoting, execution, and verification for machine capabilities."},"servers":[{"url":"https://api.rqm-relay.com"}],"security":[],"paths":{"/v1/listings":{"get":{"operationId":"listServices","description":"Free provider-published listings, distinct from approved execution routes. Filter query, protocol, access; paginate with limit and cursor.","responses":{"200":{"description":"Listings with provenance, connection details, freshness, prices and access states"}}}},"/v1/listings/search":{"post":{"operationId":"searchServiceListings","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"default":"","type":"string","maxLength":512},"protocol":{"type":"string","enum":["rest","mcp","a2a","x402"]},"access":{"type":"string","enum":["listed","connect_directly","run_through_relay"]},"limit":{"default":20,"type":"integer","minimum":1,"maximum":100},"cursor":{"default":0,"type":"integer","minimum":0,"maximum":1000000}},"required":["query","limit","cursor"],"additionalProperties":false}}}},"responses":{"200":{"description":"Matching listings, total and nextCursor"},"400":{"description":"Invalid search"}}}},"/v1/listings/{id}":{"get":{"operationId":"getServiceListing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Service details; provider claims are not verification"},"404":{"description":"Listing not found"}}}},"/v1/provider-applications":{"post":{"operationId":"submitProviderApplication","description":"Private application only. Does not register, approve, or activate a provider. No credentials or confidential payloads.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"serviceName":{"type":"string","minLength":1,"maxLength":200},"contactEmail":{"type":"string","minLength":1,"maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"documentationUrl":{"type":"string","minLength":1,"maxLength":1000,"format":"uri"},"endpoint":{"type":"string","minLength":1,"maxLength":1000,"format":"uri"},"ownershipEvidenceUrl":{"type":"string","minLength":1,"maxLength":1000,"format":"uri"},"description":{"type":"string","minLength":1,"maxLength":2000},"pricing":{"type":"string","minLength":1,"maxLength":1000},"executionLimits":{"type":"string","minLength":1,"maxLength":1000},"recoveryTerms":{"type":"string","minLength":1,"maxLength":2000},"acceptsReview":{"type":"boolean","const":true}},"required":["serviceName","contactEmail","documentationUrl","endpoint","ownershipEvidenceUrl","description","pricing","executionLimits","recoveryTerms","acceptsReview"],"additionalProperties":false}}}},"responses":{"201":{"description":"Private application reference"},"400":{"description":"Invalid or unsafe application"},"429":{"description":"Submission limit"},"503":{"description":"Durable storage unavailable; application not accepted"}}},"get":{"operationId":"reviewProviderApplications","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Private applications, administrator only"},"401":{"description":"Administrator authentication required"}}}},"/v1/discovery/events":{"post":{"operationId":"recordAggregateDiscoveryEvent","description":"Accepts only service_detail or direct_connection; no identifiers, queries or payloads. Unverified browser counters.","responses":{"204":{"description":"Event processed"},"400":{"description":"Unsupported event"}}}},"/v1/discovery/report":{"get":{"operationId":"getPrivateDiscoveryReport","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Daily aggregate counts, separate server and unverified browser sources"},"401":{"description":"Administrator authentication required"}}}},"/":{"get":{"operationId":"discoverRelay","description":"Agent entry point with API links, authentication requirements, and the configured payer access mode. Check readiness and the unpaid challenge before a new purchase.","responses":{"200":{"description":"Relay discovery links"}}}},"/v1/bazaar":{"get":{"operationId":"getBazaarManifest","description":"Exact RQM capability purchase URLs and quote instructions; verify Coinbase indexing independently.","responses":{"200":{"description":"RQM Bazaar publishing manifest"}}}},"/v1/capabilities/{id}/run":{"post":{"operationId":"runBazaarCapability","description":"Obtain a fresh /v1/quote, then submit quoteId, input and idempotencyKey. Returns an x402 challenge with capability-specific Bazaar metadata. Payment and recovery use the same engine as /v1/run. The body key supports clients that cannot set custom headers.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"PAYMENT-SIGNATURE","in":"header","schema":{"type":"string","writeOnly":true}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["quoteId","input","idempotencyKey"],"properties":{"quoteId":{"type":"string","format":"uuid"},"input":{"type":"object"},"idempotencyKey":{"type":"string","minLength":8,"maxLength":200}},"additionalProperties":false}}}},"responses":{"202":{"description":"Accepted job with private result-access token"},"402":{"description":"Payment required and Bazaar declaration"},"409":{"description":"Quote/capability or idempotency conflict"},"503":{"description":"Unavailable admission or pending finality; recover the original purchase"}}}},"/health":{"get":{"operationId":"health","responses":{"200":{"description":"Liveness"}}}},"/ready":{"get":{"operationId":"ready","responses":{"200":{"description":"Readiness"},"503":{"description":"Not ready"}}}},"/v1/capabilities":{"get":{"operationId":"listCapabilities","parameters":[{"name":"category","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Capability list"}}}},"/v1/capabilities/{id}":{"get":{"operationId":"getCapability","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Capability"},"404":{"description":"Not found"}}}},"/v1/providers":{"get":{"operationId":"listProviders","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Provider list"}}}},"/v1/providers/{id}":{"get":{"operationId":"getProvider","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Provider scorecard"},"404":{"description":"Not found"}}}},"/v1/search":{"post":{"operationId":"search","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Ranked capability results"}}}},"/v1/quote":{"post":{"operationId":"quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"Tamper-evident quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelayQuote"}}}},"409":{"description":"No route"}}}},"/v1/run":{"post":{"operationId":"run","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"x402 v2 buyer authorization matching the selected quote. Omitted on the first request to obtain PAYMENT-REQUIRED. After facilitator settlement, recovery requires the same original signature for authentication; Relay reuses durable settlement evidence without another charge.","schema":{"type":"string","writeOnly":true}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunRequest"}}}},"responses":{"200":{"description":"Accepted or idempotently replayed job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelayJobAccepted"}}}},"202":{"description":"Buyer payment settled and job accepted","headers":{"PAYMENT-RESPONSE":{"description":"x402 v2 facilitator settlement response","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelayJobAccepted"}}}},"402":{"description":"Quote requires an x402 v2 buyer payment","headers":{"PAYMENT-REQUIRED":{"description":"Dynamic x402 v2 payment requirements for this quote","schema":{"type":"string"}}}},"503":{"description":"Execution disabled, beta not ready, or buyer settlement waiting for Base finality"}}}},"/v1/jobs/{jobId}":{"get":{"operationId":"getJob","security":[{"bearerAuth":[]}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status"},"401":{"description":"Invalid result-access capability"},"404":{"description":"Not found"},"410":{"description":"Result access expired"}}}},"/v1/jobs/{jobId}/result":{"get":{"operationId":"getJobResult","security":[{"bearerAuth":[]}],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job result"},"202":{"description":"Pending"},"401":{"description":"Invalid result-access capability"},"404":{"description":"Not found"},"410":{"description":"Result access expired"}}}},"/v1/receipts/{receiptId}":{"get":{"operationId":"getReceipt","security":[{"bearerAuth":[]}],"parameters":[{"name":"receiptId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Signed receipt","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionReceipt"}}}},"401":{"description":"Invalid result-access capability"},"404":{"description":"Not found"},"410":{"description":"Result access expired"}}}},"/v1/providers/register":{"post":{"operationId":"registerProvider","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","name","endpoint"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"endpoint":{"type":"string","format":"uri"},"capabilityIds":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}}}},"responses":{"201":{"description":"Discovered provider; not executable"},"401":{"description":"Unauthorized"}}}},"/mcp":{"post":{"operationId":"mcp","responses":{"200":{"description":"MCP JSON-RPC response"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"SearchRequest":{"type":"object","properties":{"query":{"type":"string"},"category":{"type":"string"},"protocol":{"enum":["rest","mcp","a2a","x402"]},"providerId":{"type":"string"},"verifiedOnly":{"type":"boolean"},"maximumPriceUsd":{"type":"string"},"maximumLatencyMs":{"type":"integer"},"requiredNetwork":{"type":"string"},"requiredAsset":{"type":"string"},"noRetention":{"type":"boolean"},"limit":{"type":"integer","minimum":1,"maximum":100}},"additionalProperties":false},"QuoteRequest":{"type":"object","required":["capabilityId"],"properties":{"capabilityId":{"type":"string"},"capabilityVersion":{"type":"string"},"maximumPriceUsd":{"type":"string"},"requiredNetwork":{"type":"string"},"requiredAsset":{"type":"string"},"maximumLatencyMs":{"type":"integer"},"noRetention":{"type":"boolean"}},"additionalProperties":false},"RunRequest":{"type":"object","required":["quoteId","input"],"properties":{"quoteId":{"type":"string","format":"uuid"},"input":{}},"additionalProperties":false},"RelayJobAccepted":{"type":"object","required":["jobId","quoteId","status","createdAt","updatedAt","receiptId","error","resultHash","resultAccessToken","resultAccessExpiresAt"],"properties":{"jobId":{"type":"string","format":"uuid"},"quoteId":{"type":"string","format":"uuid"},"status":{"enum":["accepted","running","succeeded","failed"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"receiptId":{"type":["string","null"],"format":"uuid"},"error":{"type":["string","null"]},"resultHash":{"type":["string","null"]},"resultAccessToken":{"type":"string","description":"High-entropy bearer capability returned only at acceptance and deterministic replay.","writeOnly":true},"resultAccessExpiresAt":{"type":"string","format":"date-time"}},"additionalProperties":false},"RelayQuote":{"type":"object","required":["quoteId","capabilityId","capabilityVersion","providerId","fallbackProviderIds","providerPrice","rqmFee","maximumTotalPrice","network","asset","tokenContract","facilitatorOrigin","buyerPaymentRequirements","expiresAt","maximumExecutionDurationMs","refundOrCreditPolicy","fallbackAvailable","quoteHash"],"properties":{"quoteId":{"type":"string","format":"uuid"},"capabilityId":{"type":"string"},"capabilityVersion":{"type":"string"},"providerId":{"type":"string"},"fallbackProviderIds":{"type":"array","items":{"type":"string"}},"providerPrice":{"type":"string"},"rqmFee":{"type":"string"},"maximumTotalPrice":{"type":"string"},"network":{"type":"string"},"asset":{"type":"string"},"tokenContract":{"type":["string","null"]},"facilitatorOrigin":{"type":["string","null"],"format":"uri"},"buyerPaymentRequirements":{"oneOf":[{"type":"null"},{"type":"object","required":["x402Version","scheme","network","asset","amount","payTo","facilitatorOrigin"],"properties":{"x402Version":{"const":2},"scheme":{"const":"exact"},"network":{"type":"string"},"asset":{"type":"string"},"amount":{"type":"string","pattern":"^[0-9]+$"},"payTo":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"facilitatorOrigin":{"type":"string","format":"uri"}},"additionalProperties":false}]},"expiresAt":{"type":"string","format":"date-time"},"maximumExecutionDurationMs":{"type":"integer","minimum":1},"refundOrCreditPolicy":{"type":"string"},"fallbackAvailable":{"type":"boolean"},"quoteHash":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"additionalProperties":true},"ExecutionReceipt":{"type":"object","required":["receiptId","quoteId","capabilityId","providerId","providerPrice","rqmFee","totalAmount","network","asset","outcome","schemaValid","refundOrCreditStatus","signature","publicKey"],"properties":{"receiptId":{"type":"string","format":"uuid"},"relayJobId":{"type":"string","format":"uuid"},"quoteId":{"type":"string","format":"uuid"},"capabilityId":{"type":"string"},"providerId":{"type":"string"},"providerCorrelationId":{"type":"string"},"idempotencyKeyHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"network":{"type":"string"},"asset":{"type":"string"},"tokenContract":{"type":"string"},"buyerPaymentTransactionHash":{"type":"string"},"providerPaymentTransactionHash":{"type":"string"},"providerRefundTransactionHash":{"type":"string"},"buyerPassThroughTransactionHash":{"type":"string"},"buyerRefundTransactionHash":{"type":"string"},"compensationTransactionHash":{"type":"string"},"accountCoreOperationId":{"type":"string"},"providerPrice":{"type":"string"},"rqmFee":{"type":"string"},"totalAmount":{"type":"string"},"resultHash":{"type":["string","null"]},"schemaValid":{"type":"boolean"},"outcome":{"enum":["succeeded","failed"]},"refundOrCreditStatus":{"enum":["not_applicable","pending","refunded","credited"]},"providerManifestHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"signingKeyId":{"type":"string","pattern":"^[a-f0-9]{64}$"},"signature":{"type":"string"},"publicKey":{"type":"string","readOnly":true}},"additionalProperties":true}}}}