{"openapi":"3.1.0","info":{"title":"Terms Check API","version":"1.0.0","description":"Published terms + a specific question → structured report with evidence. Information extraction, not legal advice. USDC on Base via x402 v2. Keep the randomly generated Idempotency-Key secret; it is the retrieval bearer token."},"servers":[{"url":"https://termscheck.online"},{"url":"http://localhost:3000","description":"Local demo"}],"paths":{"/api/v1/health":{"get":{"operationId":"health","summary":"Configuration and database readiness","responses":{"200":{"description":"Ready"},"503":{"description":"Not ready; payments disabled"}}}},"/api/v1/pricing":{"get":{"operationId":"pricing","summary":"Current prices, limits and payment policy","responses":{"200":{"description":"Pricing in USDC"}}}},"/api/v1/quote":{"post":{"operationId":"quote","summary":"Validate input and return the price and x402 requirements without charging","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckInput"}}}},"responses":{"200":{"description":"amount, currency, tier, mode, network, payment (x402 PaymentRequired), policy"},"400":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/check":{"post":{"operationId":"check","summary":"Pay per check and analyze published documents","description":"Normally synchronous. Use a random key for each new check and persist it before paying. 202 means another invocation is processing this same key; poll retrieval. Retry failed paid checks with identical body and same key without a new payment, at most twice. Do not retry with a new key after settlement_unknown.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"description":"Base64 x402 v2 PaymentPayload from @x402/fetch or another compatible client.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckInput"}}}},"responses":{"200":{"description":"Completed Terms Check Report. PAYMENT-RESPONSE contains a base64 settlement receipt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermsReport"}}}},"202":{"description":"Request in progress; GET status with the original secret key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestStatus"}}}},"400":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"x402 v2 payment required. PAYMENT-REQUIRED header is base64 JSON; body also contains x402Version, resource, accepts, mode, price and policy."},"409":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Unconfigured service, provider failure, or settlement_unknown. Paid failures return request_id, paid and retryable.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/RequestStatus"}]}}}}}}},"/api/v1/requests/{id}":{"get":{"operationId":"getRequest","summary":"Privately retrieve a report or processing status","security":[{"requestKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Terms Check Report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermsReport"}}}},"202":{"description":"In progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestStatus"}}}},"401":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Structured error. No stack traces or provider secrets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"requestKey":{"type":"http","scheme":"bearer","description":"Original secret Idempotency-Key, not a wallet private key."}},"schemas":{"CheckInput":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"source_url":{"type":"string","maxLength":2048},"source_text":{"type":"string","minLength":10,"maxLength":120000},"document_title":{"type":"string","minLength":1,"maxLength":200},"question":{"type":"string","minLength":4,"maxLength":2000},"preferred_output_language":{"type":"string","maxLength":35,"pattern":"^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$"},"context":{"type":"string","maxLength":4000},"additional_urls":{"default":[],"maxItems":5,"type":"array","items":{"type":"string","maxLength":2048}},"tier":{"default":"standard","type":"string","enum":["simple","standard","deep"]},"discover_related":{"default":true,"type":"boolean"}},"required":["question","additional_urls","tier","discover_related"],"additionalProperties":false},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}}}},"RequestStatus":{"type":"object","required":["request_id","status","paid","retryable"],"properties":{"request_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["settling","processing","failed","settlement_unknown","payment_failed"]},"paid":{"type":"boolean"},"retryable":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"TermsReport":{"type":"object","required":["request_id","question","answer","summary","conditions","restrictions","relevant_provisions","related_documents","conflicts","document_dates","checked_at","limitations","mode"],"properties":{"request_id":{"type":"string","format":"uuid"},"question":{"type":"string"},"output_language":{"type":"string"},"system_notice_language":{"type":"string"},"answer":{"type":"string","enum":["allowed","prohibited","allowed_with_conditions","unclear","insufficient_information"]},"summary":{"type":"string"},"conditions":{"type":"array","items":{"type":"object","required":["text","evidence"],"properties":{"text":{"type":"string"},"evidence":{"type":"array","items":{"type":"integer","minimum":0}}}}},"restrictions":{"type":"array","items":{"type":"object","required":["text","evidence"],"properties":{"text":{"type":"string"},"evidence":{"type":"array","items":{"type":"integer","minimum":0}}}}},"relevant_provisions":{"type":"array","items":{"type":"object","required":["id","document_id","source_url","document_title","section","section_id","text","relevance","retrieved_at","source_sha256"],"properties":{"id":{"type":"integer"},"document_id":{"type":"string"},"source_url":{"type":["string","null"]},"document_title":{"type":"string"},"section":{"type":["string","null"]},"section_id":{"type":"string"},"text":{"type":"string"},"original_text":{"type":"string"},"source_language":{"type":["string","null"]},"relevance":{"type":"string"},"retrieved_at":{"type":"string","format":"date-time"},"source_sha256":{"type":"string"}}}},"related_documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":["string","null"]},"requested_url":{"type":["string","null"]},"title":{"type":"string"},"retrieved_at":{"type":"string","format":"date-time"},"sha256":{"type":"string"},"source_language":{"type":["string","null"]},"used":{"type":"boolean"}}}},"conflicts":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"evidence":{"type":"array","items":{"type":"integer"}}}}},"document_dates":{"type":"array","items":{"type":"object","properties":{"document_id":{"type":"string"},"label":{"type":"string"},"text":{"type":"string"},"section_id":{"type":"string"}}}},"checked_at":{"type":"string","format":"date-time"},"limitations":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["demo","live"]}}}}}}