{"openapi":"3.1.0","info":{"title":"GovLaws","version":"1.0.0","description":"U.S. federal regulation data for AI agents. Instant citation lookup, change detection, and semantic search over official government sources.","contact":{"name":"govlaws.ai","url":"https://govlaws.ai","email":"api@govlaws.ai"},"license":{"name":"See terms at GovLaws /terms","url":"https://govlaws.ai/terms"},"guidance":"GovLaws provides two access lanes. (1) API-key lane: POST /api/signup to create an account, then pass the key as Bearer token. (2) MPP lane: call /api/mpp/resolve, /api/mpp/search, or /api/mpp/changes with no auth — you will receive a 402 with a Tempo payment challenge. Pay via Tempo stablecoin and replay the request with the credential. All responses include provenance metadata citing official .gov sources."},"servers":[{"url":"https://govlaws.ai","description":"Production"}],"x-service-info":{"categories":["legal","government","regulations"],"docs":{"homepage":"https://govlaws.ai/","apiReference":"https://govlaws.ai/openapi.json","llms":"https://govlaws.ai/llms.txt"}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key from POST /api/signup. Format: X-API-Key: glaw_sk_live_..."},"BearerAuth":{"type":"http","scheme":"bearer","description":"API key from POST /api/signup. Format: Authorization: Bearer glaw_sk_live_..."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"invalid_api_key","message":"API key not found or inactive."}}}},"RateLimitExceeded":{"description":"Monthly request limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limit_exceeded","message":"Monthly request limit reached. Upgrade your plan or wait until next month.","reset_at":"2026-04-01T00:00:00Z","upgrade_url":"https://govlaws.ai/pricing"}}}}},"schemas":{"ProvenanceObject":{"type":"object","properties":{"is_official_edition":{"type":"boolean"},"disclaimer":{"type":"string"},"official_artifact_url":{"type":"string","nullable":true,"description":"Section-level GovInfo PDF URL (null until V1 volume mapping)"},"govinfo_source_url":{"type":"string","nullable":true,"description":"GovInfo bulk XML URL the data was ingested from (title-level)"},"ecfr_url":{"type":"string","nullable":true}}},"ChangeEvent":{"type":"object","properties":{"citation":{"type":"string","nullable":true},"change_type":{"type":"string","enum":["amendment","final_rule","proposed_rule","correction"]},"effective_date":{"type":"string","format":"date","nullable":true},"agency":{"type":"string","nullable":true},"source":{"type":"string"},"document_number":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}},"ResolveCitationInput":{"type":"object","additionalProperties":false,"required":["citation"],"properties":{"citation":{"type":"string","description":"CFR citation, e.g. \"12 CFR 1026.43\"","example":"12 CFR 1026.43"}}},"SearchRegulationsInput":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","description":"Natural-language or keyword query over federal regulations.","example":"CFPB mortgage underwriting requirements"},"limit":{"type":"integer","minimum":1,"maximum":20,"default":5,"description":"Maximum number of ranked results to return."}}},"ChangesQueryInput":{"type":"object","additionalProperties":false,"properties":{"agency":{"type":"string","description":"Optional agency name filter.","example":"CFPB"},"citation":{"type":"string","description":"Optional CFR citation prefix filter.","example":"12 CFR 1026"},"days":{"type":"integer","minimum":1,"maximum":90,"default":30,"description":"Optional lookback window in days."}}},"MppRefundRequestInput":{"type":"object","additionalProperties":false,"properties":{"receipt_id":{"type":"string","description":"MPP receipt identifier for the original paid request."},"challenge_id":{"type":"string","description":"MPP challenge identifier for the original paid request."},"reason":{"type":"string","description":"Optional refund reason for support and reconciliation."}}},"MppPaymentHistoryEntry":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"endpoint":{"type":"string","enum":["resolve","search","changes","identity","refunds"]},"amount_usd":{"type":"number"},"challenge_id":{"type":"string","nullable":true},"receipt_id":{"type":"string","nullable":true},"response_status":{"type":"integer","nullable":true}}},"MppRefundRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"payment_id":{"type":"string","format":"uuid"},"challenge_id":{"type":"string","nullable":true},"receipt_id":{"type":"string","nullable":true},"requester_identity":{"type":"string"},"refund_to":{"type":"string"},"amount_usd":{"type":"number"},"reason":{"type":"string","nullable":true},"status":{"type":"string","enum":["requested","approved","rejected","refunded"]},"refund_tx_hash":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/api/resolve":{"get":{"summary":"Resolve a CFR citation to current text + provenance","description":"Given a CFR citation string, returns the current regulatory text, source metadata, and provenance linking to official government sources.","operationId":"resolveCitation","tags":["Core"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"x-input-schema":{"$ref":"#/components/schemas/ResolveCitationInput"},"parameters":[{"name":"citation","in":"query","required":true,"schema":{"type":"string"},"description":"CFR citation, e.g. \"12 CFR 1026.43\"","example":"12 CFR 1026.43"}],"responses":{"200":{"description":"Citation resolved","content":{"application/json":{"example":{"citation":"12 CFR 1026.43","title":"Minimum standards for transactions secured by a dwelling","agency":"Consumer Financial Protection Bureau","text":"(a) Scope...","source":{"system":"ecfr","url":"https://www.ecfr.gov/current/title-12/section-1026.43","retrieved_at":"2026-03-11T08:00:00Z"},"freshness":{"up_to_date_as_of":"2026-03-11T08:00:00Z","status":"current"},"recent_changes":[],"provenance":{"is_official_edition":false,"disclaimer":"Derived from the eCFR, which is not an official legal edition of the CFR.","official_artifact_url":null,"govinfo_source_url":"https://www.govinfo.gov/bulkdata/ECFR/title-12/ECFR-title12.xml"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Citation not found"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/search":{"post":{"summary":"Semantic search over federal regulations","description":"Natural language or keyword query → ranked regulatory sections with snippets.","operationId":"searchRegulations","tags":["Core"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"x-input-schema":{"$ref":"#/components/schemas/SearchRegulationsInput"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRegulationsInput"}}}},"responses":{"200":{"description":"Search results","content":{"application/json":{"example":{"results":[{"citation":"12 CFR 1026.43","title":"Minimum standards for transactions secured by a dwelling","score":0.94,"snippet":"(a) Scope. This section applies to...","url":"https://www.ecfr.gov/current/title-12/section-1026.43"}],"query":"CFPB mortgage underwriting requirements","total":1}}}}}}},"/api/changes":{"get":{"summary":"Recent regulatory changes from the Federal Register","description":"Returns recent regulatory changes filtered by agency, citation prefix, or lookback window.","operationId":"getChanges","tags":["Core"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"x-input-schema":{"$ref":"#/components/schemas/ChangesQueryInput"},"parameters":[{"name":"agency","in":"query","required":false,"schema":{"type":"string"},"example":"CFPB"},{"name":"citation","in":"query","required":false,"schema":{"type":"string"},"example":"12 CFR 1026"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","default":30,"minimum":1,"maximum":90}}],"responses":{"200":{"description":"Change events","content":{"application/json":{"example":{"changes":[{"citation":"12 CFR 1026.43","change_type":"final_rule","effective_date":"2026-02-28","agency":"Consumer Financial Protection Bureau","source":"Federal Register","document_number":"2026-04567","url":"https://www.federalregister.gov/documents/2026-04567"}],"period":{"from":"2026-02-09","to":"2026-03-11"},"total":1}}}}}}},"/api/usage":{"get":{"summary":"Current usage and spend state","description":"Returns requests used, request limits, current billing period, and budget status. Agents and operators use this to monitor consumption.","operationId":"getUsage","tags":["Control Plane"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Usage report","content":{"application/json":{"example":{"plan":"developer","requests_used":1842,"requests_limit":5000,"period":"2026-03","budget":null}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/budgets":{"get":{"summary":"Get current budget controls","description":"Returns the current budget configuration for your account, including caps and spend status.","operationId":"getBudget","tags":["Control Plane"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Budget configuration","content":{"application/json":{"example":{"budget":{"soft_cap_usd":150,"hard_cap_usd":200,"current_spend_usd":42.5,"notify_webhook_url":"https://your-agent.ai/webhooks/budget-events","status":"active","updated_at":"2026-03-15T10:00:00Z"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"summary":"Set or update budget controls","description":"Set soft and hard budget caps with optional notification webhook. Requires Pro plan or higher. An audit event is recorded on every change.","operationId":"setBudget","tags":["Control Plane"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"soft_cap_usd":{"type":"number","minimum":0,"description":"Notification threshold in USD"},"hard_cap_usd":{"type":"number","minimum":0,"description":"Hard spending limit in USD"},"notify_webhook_url":{"type":"string","format":"uri","description":"URL to receive budget event notifications"}}},"example":{"soft_cap_usd":150,"hard_cap_usd":200,"notify_webhook_url":"https://your-agent.ai/webhooks/budget-events"}}}},"responses":{"200":{"description":"Budget updated","content":{"application/json":{"example":{"budget":{"soft_cap_usd":150,"hard_cap_usd":200,"current_spend_usd":0,"status":"active","updated_at":"2026-03-17T10:00:00Z"}}}}},"201":{"description":"Budget created (same shape as 200)"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Plan upgrade required","content":{"application/json":{"example":{"error":"plan_required","message":"Budget controls require Pro plan or higher."}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/subscribe":{"get":{"summary":"List active webhook subscriptions","description":"Returns all webhook subscriptions for your account. Requires Pro plan.","operationId":"listSubscriptions","tags":["Control Plane"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Subscription list","content":{"application/json":{"example":{"subscriptions":[{"id":"sub_abc123","citation_pattern":"12 CFR 1026.*","webhook_url":"https://your-agent.ai/webhooks/govlaws","filters_json":{"change_types":["amendment","final_rule"],"substantive_only":true},"is_active":true,"failure_count":0,"last_delivered_at":"2026-03-15T10:00:00Z","created_at":"2026-03-01T00:00:00Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Pro plan required"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"summary":"Register a webhook for change notifications","description":"Subscribe to citation change events. Webhook payloads are signed with HMAC-SHA256. Retries with exponential backoff (1m, 5m, 30m, 2h, 24h). Max 50 active subscriptions. Requires Pro plan.","operationId":"createSubscription","tags":["Control Plane"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["citation_pattern","webhook_url","webhook_secret"],"properties":{"citation_pattern":{"type":"string","description":"Citation glob pattern, e.g. \"12 CFR 1026.*\""},"webhook_url":{"type":"string","format":"uri","description":"HTTPS URL to receive POST notifications"},"webhook_secret":{"type":"string","minLength":16,"description":"Secret for HMAC-SHA256 payload signing (min 16 chars)"},"filters":{"type":"object","properties":{"change_types":{"type":"array","items":{"type":"string","enum":["amendment","correction","effective_date","proposed_rule","final_rule"]}},"substantive_only":{"type":"boolean"}}}}},"example":{"citation_pattern":"12 CFR 1026.*","webhook_url":"https://your-agent.ai/webhooks/govlaws","webhook_secret":"whsec_your_signing_secret_here","filters":{"change_types":["amendment","final_rule"],"substantive_only":true}}}}},"responses":{"201":{"description":"Subscription created","content":{"application/json":{"example":{"subscription_id":"sub_abc123","citation_pattern":"12 CFR 1026.*","webhook_url":"https://your-agent.ai/webhooks/govlaws","created_at":"2026-03-17T10:00:00Z","status":"active"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Pro plan required"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"delete":{"summary":"Deactivate a webhook subscription","description":"Deactivates a subscription by ID. The subscription will stop receiving notifications.","operationId":"deleteSubscription","tags":["Control Plane"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"Subscription ID to deactivate"}],"responses":{"200":{"description":"Subscription deactivated","content":{"application/json":{"example":{"subscription_id":"sub_abc123","status":"deactivated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Subscription not found"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/keys":{"get":{"summary":"List all API keys for your account","description":"Returns key metadata (prefixes, names, status) for all keys on the account. Never returns plaintext keys.","operationId":"listKeys","tags":["Auth"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Key list","content":{"application/json":{"example":{"keys":[{"id":"uuid","key_prefix":"glaw_sk_live_...","name":"production","is_active":true,"created_at":"2026-03-01T00:00:00Z","last_used_at":"2026-03-19T10:00:00Z"}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"post":{"summary":"Create a new API key","description":"Issues a new API key for your account. The plaintext key is returned ONCE. Maximum 10 active keys per account.","operationId":"createKey","tags":["Auth"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Optional label for the key","example":"production"}}}}}},"responses":{"201":{"description":"Key created — plaintext shown once","content":{"application/json":{"example":{"api_key":"glaw_sk_live_...","id":"uuid","key_prefix":"glaw_sk_live_...","name":"production","created_at":"2026-03-19T10:00:00Z","warning":"This key is shown ONCE. Store it securely."}}}},"400":{"description":"Key limit reached (max 10) or invalid JSON"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}},"delete":{"summary":"Revoke an API key","description":"Deactivates a key by ID. Cannot revoke the key being used to make the request.","operationId":"revokeKey","tags":["Auth"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"Key ID to revoke"}],"responses":{"200":{"description":"Key revoked","content":{"application/json":{"example":{"id":"uuid","key_prefix":"glaw_sk_live_...","status":"revoked"}}}},"400":{"description":"Missing id or attempted self-revoke"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Key not found or not owned by your account"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/keys/rotate":{"post":{"summary":"Rotate an API key","description":"Deactivates the specified key and issues a new one with the same name. The new plaintext key is returned ONCE.","operationId":"rotateKey","tags":["Auth"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"Key ID to rotate"}}},"example":{"id":"uuid-of-key-to-rotate"}}}},"responses":{"201":{"description":"Key rotated — new plaintext shown once","content":{"application/json":{"example":{"api_key":"glaw_sk_live_new_key...","id":"new-uuid","key_prefix":"glaw_sk_live_new_key","rotated_from":{"id":"old-uuid","key_prefix":"glaw_sk_live_old_key"},"warning":"This key is shown ONCE. Store it securely. The old key is now inactive."}}}},"400":{"description":"Key already inactive"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Key not found"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/batch-resolve":{"post":{"summary":"Batch resolve multiple citations in one call","description":"Resolve up to 50 CFR citations in a single request. Returns text + provenance for each. Requires Pro plan or higher.","operationId":"batchResolveCitations","tags":["Core"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["citations"],"properties":{"citations":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":50,"description":"Array of CFR citation strings"},"fields":{"type":"array","items":{"type":"string","enum":["citation","title","text","agency","provenance"]},"default":["citation","title","text","provenance"],"description":"Fields to include in each result (reduces payload size)"}}},"example":{"citations":["12 CFR 1026.43","29 CFR 1910.134"],"fields":["citation","title","text","provenance"]}}}},"responses":{"200":{"description":"Batch results","content":{"application/json":{"example":{"results":[{"citation":"12 CFR 1026.43","title":"Minimum standards for transactions secured by a dwelling","text":"(a) Scope...","provenance":{"is_official_edition":false,"disclaimer":"Derived from the eCFR, not an official legal edition of the CFR.","govinfo_source_url":"https://www.govinfo.gov/bulkdata/ECFR/title-12/ECFR-title12.xml","ecfr_url":"https://www.ecfr.gov/current/title-12/section-1026.43"}},{"citation":"29 CFR 1910.134","error":"not_found"}],"resolved":1,"errors":1}}}},"400":{"description":"Missing or invalid citations array, or exceeds 50 limit"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Pro plan required","content":{"application/json":{"example":{"error":"plan_required","message":"Batch resolve requires Pro plan or higher."}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/freshness":{"get":{"summary":"Per-source data freshness metadata","description":"Returns last sync timestamps, document counts, and staleness status for each data source. A source is \"stale\" if not synced within 6 hours.","operationId":"getFreshness","tags":["Control Plane"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Freshness report","content":{"application/json":{"example":{"sources":{"ecfr":{"last_sync":"2026-03-19T08:00:00Z","documents_tracked":36530,"changes_last_30d":12,"status":"current"},"federal_register":{"last_sync":"2026-03-19T08:00:00Z","notices_last_30d":8,"status":"current"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/collections":{"get":{"summary":"Available data collections and coverage","description":"Lists all data collections (CFR titles, Federal Register change types, state statutes) with their coverage and freshness SLA.","operationId":"getCollections","tags":["Control Plane"],"security":[{"apiKey":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Collection inventory","content":{"application/json":{"example":{"collections":[{"id":"us-federal-cfr","jurisdiction":"us_federal","document_type":"regulation_section","coverage":{"titles":[12,17,26,29,42,45]},"freshness_sla_hours":4},{"id":"us-federal-register","jurisdiction":"us_federal","document_type":"change_event","coverage":{"types":["final_rule","proposed_rule","amendment","correction"]},"freshness_sla_hours":4}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/mpp/resolve":{"get":{"summary":"Resolve a citation via pay-per-request (MPP)","description":"Same as GET /api/resolve but requires no API key. Payment is handled via the Machine Payments Protocol (MPP) — the first call returns 402 with a payment challenge; the agent pays via Tempo stablecoin and replays the request with a credential. $0.05 per request.","operationId":"mppResolveCitation","security":[],"tags":["MPP"],"x-input-schema":{"$ref":"#/components/schemas/ResolveCitationInput"},"x-payment-info":{"amount":"50000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"GovLaws citation resolution - official-source regulatory text with provenance","intent":"charge","method":"tempo"},"parameters":[{"name":"citation","in":"query","required":true,"schema":{"type":"string"},"description":"CFR citation, e.g. \"12 CFR 1026.43\"","example":"12 CFR 1026.43"}],"responses":{"200":{"description":"Citation resolved (paid). Includes Payment-Receipt header.","content":{"application/json":{"example":{"citation":"12 CFR 1026.43","title":"Minimum standards for transactions secured by a dwelling","text":"(a) Scope...","provenance":{"is_official_edition":false}}}}},"400":{"description":"Missing citation parameter"},"402":{"description":"Payment Required"},"404":{"description":"Citation not found"}}}},"/api/mpp/search":{"post":{"summary":"Semantic search via pay-per-request (MPP)","description":"Same as POST /api/search but requires no API key. Uses MPP payment flow (402 challenge → pay → replay). $0.03 per request.","operationId":"mppSearchRegulations","security":[],"tags":["MPP"],"x-input-schema":{"$ref":"#/components/schemas/SearchRegulationsInput"},"x-payment-info":{"amount":"30000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"GovLaws regulatory search - vector similarity search across federal regulations","intent":"charge","method":"tempo"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRegulationsInput"}}}},"responses":{"200":{"description":"Search results (paid). Includes Payment-Receipt header.","content":{"application/json":{"example":{"results":[{"citation":"12 CFR 1026.43","title":"...","score":0.94,"snippet":"..."}],"query":"CFPB mortgage underwriting requirements","total":1}}}},"400":{"description":"Invalid or missing query"},"402":{"description":"Payment Required"}}}},"/api/mpp/changes":{"get":{"summary":"Recent regulatory changes via pay-per-request (MPP)","description":"Same as GET /api/changes but requires no API key. Uses MPP payment flow. $0.03 per request.","operationId":"mppGetChanges","security":[],"tags":["MPP"],"x-input-schema":{"$ref":"#/components/schemas/ChangesQueryInput"},"x-payment-info":{"amount":"30000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"GovLaws change feed - recent regulatory changes with Federal Register sources","intent":"charge","method":"tempo"},"parameters":[{"name":"agency","in":"query","required":false,"schema":{"type":"string"},"example":"CFPB"},{"name":"citation","in":"query","required":false,"schema":{"type":"string"},"example":"12 CFR 1026"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","default":30,"minimum":1,"maximum":90}}],"responses":{"200":{"description":"Change events (paid). Includes Payment-Receipt header.","content":{"application/json":{"example":{"changes":[{"citation":"12 CFR 1026.43","change_type":"final_rule","effective_date":"2026-02-28"}],"period":{"from":"2026-02-17","to":"2026-03-19"},"total":1}}}},"402":{"description":"Payment Required"}}}},"/api/mpp/identity":{"get":{"summary":"Re-authenticate a prior MPP payer with zero-dollar auth","description":"Uses the standard MPP challenge/credential flow with amount 0 so a client can prove it controls the same identity that made earlier paid GovLaws requests. Returns prior payment history and refund status for that identity.","operationId":"mppGetIdentity","security":[],"tags":["MPP"],"x-payment-info":{"amount":"0","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"GovLaws MPP identity auth - verify the same payer identity without charging again","intent":"charge","method":"tempo"},"responses":{"200":{"description":"Verified identity and prior MPP activity.","content":{"application/json":{"example":{"identity":"did:pkh:eip155:42161:0x1234abcd","payment_count":2,"total_spend_usd":0.08,"payments":[{"id":"c1d9d233-20ca-4f6e-b4d0-0585effdd3f9","created_at":"2026-04-01T17:22:00.000Z","endpoint":"resolve","amount_usd":0.05,"challenge_id":"ch_resolve_123","receipt_id":"rcpt_resolve_123","response_status":200}],"refunds":[]}}}},"402":{"description":"Payment Required (zero-dollar auth challenge)"}}}},"/api/mpp/refunds":{"get":{"summary":"List refund requests for the current MPP identity","description":"Uses zero-dollar MPP auth to verify the payer identity, then returns refund requests tied to that identity.","operationId":"mppListRefunds","security":[],"tags":["MPP"],"x-payment-info":{"amount":"0","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"GovLaws MPP refund support - authenticate the payer before viewing or requesting refunds","intent":"charge","method":"tempo"},"responses":{"200":{"description":"Refund requests for the current MPP identity.","content":{"application/json":{"example":{"identity":"did:pkh:eip155:42161:0x1234abcd","refunds":[{"id":"a99cba7a-0f4a-49b8-9069-4b5f8ae5a959","payment_id":"c1d9d233-20ca-4f6e-b4d0-0585effdd3f9","challenge_id":"ch_resolve_123","receipt_id":"rcpt_resolve_123","requester_identity":"did:pkh:eip155:42161:0x1234abcd","refund_to":"did:pkh:eip155:42161:0x1234abcd","amount_usd":0.05,"reason":"Citation response returned a not_found result","status":"requested","refund_tx_hash":null,"created_at":"2026-04-01T18:05:00.000Z","updated_at":"2026-04-01T18:05:00.000Z"}]}}}},"402":{"description":"Payment Required (zero-dollar auth challenge)"}}},"post":{"summary":"Request a refund for a prior MPP payment","description":"Uses zero-dollar MPP auth to verify the payer identity, then records a refund request linked to the original challenge_id or receipt_id. Refund settlement is handled out of protocol to the original payer identity.","operationId":"mppRequestRefund","security":[],"tags":["MPP"],"x-input-schema":{"$ref":"#/components/schemas/MppRefundRequestInput"},"x-payment-info":{"amount":"0","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"GovLaws MPP refund support - authenticate the payer before viewing or requesting refunds","intent":"charge","method":"tempo"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MppRefundRequestInput"}}}},"responses":{"202":{"description":"Refund request recorded.","content":{"application/json":{"example":{"refund":{"id":"a99cba7a-0f4a-49b8-9069-4b5f8ae5a959","payment_id":"c1d9d233-20ca-4f6e-b4d0-0585effdd3f9","challenge_id":"ch_resolve_123","receipt_id":"rcpt_resolve_123","requester_identity":"did:pkh:eip155:42161:0x1234abcd","refund_to":"did:pkh:eip155:42161:0x1234abcd","amount_usd":0.05,"reason":"Citation response returned a not_found result","status":"requested","refund_tx_hash":null,"created_at":"2026-04-01T18:05:00.000Z","updated_at":"2026-04-01T18:05:00.000Z"},"message":"Refund request recorded. Refund settlement is handled out of protocol to the original payer identity."}}}},"400":{"description":"Missing or invalid receipt_id/challenge_id payload"},"402":{"description":"Payment Required (zero-dollar auth challenge)"},"404":{"description":"Original payment not found for this MPP identity"}}}}},"tags":[{"name":"Auth","description":"Account creation and API key management"},{"name":"Core","description":"Citation lookup, search, and change detection"},{"name":"Control Plane","description":"Usage, budgets, webhooks, and account management"},{"name":"MPP","description":"Pay-per-request endpoints via Machine Payments Protocol (Tempo stablecoin). No API key needed — payment via 402 challenge/credential flow."},{"name":"System","description":"Health and status endpoints"}]}