{"openapi":"3.1.0","info":{"title":"GovLaws","version":"1.0.0","description":"U.S. federal regulation and U.S. Code canary 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 three 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/batch-resolve, /api/mpp/search, or /api/mpp/changes with no auth — you will receive a 402 payment challenge. Tempo pathUSD is the primary micro-payment rail. (3) x402 lane: call /api/x402/resolve, /api/x402/search, or /api/x402/changes for Coinbase CDP/Base USDC payments and x402 Bazaar / AgentCore-style discovery. All responses include provenance metadata citing official .gov sources."},"servers":[{"url":"https://govlaws.ai","description":"Production"}],"x-service-info":{"categories":["legal","government","regulations","statutes"],"docs":{"homepage":"https://govlaws.ai/","apiReference":"https://govlaws.ai/openapi.json","llms":"https://govlaws.ai/llms.txt","x402":"https://govlaws.ai/api/x402/resolve"}},"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","description":"Machine-readable provenance for a federal legal artifact. Agents should branch on `trust.disclaimer_code` and `trust.citation_suitability` instead of parsing the prose `disclaimer`.","properties":{"is_official_edition":{"type":"boolean","description":"True only when the payload derives from an official published edition or a positive-law U.S. Code title."},"disclaimer":{"type":"string","description":"Human-readable disclaimer. Use `trust.disclaimer_code` for programmatic decisions."},"official_artifact_url":{"type":"string","nullable":true,"description":"URL of a direct official artifact when available, including Federal Register documents, section-level GovInfo CFR artifacts, or OLRC U.S. Code XML packages."},"govinfo_source_url":{"type":"string","nullable":true,"description":"GovInfo URL stored during ingestion. May be title-level eCFR bulk XML or, when available, a section-level official CFR or U.S. Code artifact."},"ecfr_url":{"type":"string","nullable":true,"description":"Human-facing eCFR URL for the citation."},"source_system":{"type":"string","enum":["ecfr","govinfo","federal_register","olrc_uscode"],"description":"Upstream system that supplied this record."},"currency":{"type":"object","description":"Whether the record reflects the current state of the regulation.","properties":{"reflects_current_text":{"type":"boolean","description":"True for current eCFR and OLRC U.S. Code records. False for point-in-time artifacts like Federal Register notices."},"as_of":{"type":"string","format":"date-time","nullable":true,"description":"When this record was retrieved or detected."},"effective_date":{"type":"string","nullable":true,"description":"Regulatory effective date for CFR/Federal Register records, or U.S. Code release point for OLRC records."}}},"official_edition":{"type":"object","description":"Whether this record is from an official legal edition.","properties":{"is_official":{"type":"boolean"},"edition_year":{"type":"integer","nullable":true},"artifact_url":{"type":"string","nullable":true,"description":"Direct link to the official edition artifact when available. This may be present even when `is_official` is false if the response text is eCFR-derived but an official GovInfo CFR artifact is known."}}},"trust":{"type":"object","description":"Machine-readable trust signals.","properties":{"disclaimer_code":{"type":"string","enum":["ECFR_UNOFFICIAL","GOVINFO_OFFICIAL","FR_NOTICE","USCODE_CURRENT"],"description":"Stable code for the disclaimer category. ECFR_UNOFFICIAL: eCFR current text, not an official legal edition. GOVINFO_OFFICIAL: GovInfo annual CFR, official edition. FR_NOTICE: Federal Register publication. USCODE_CURRENT: current U.S. Code from OLRC XML through the stated public law release point."},"citation_suitability":{"type":"array","items":{"type":"string","enum":["research","reference","legal_filing"]},"description":"Contexts an agent can safely cite this record in. Current eCFR and non-positive-law U.S. Code records are limited to 'research' and 'reference'."}}}}},"ChangeEvent":{"type":"object","properties":{"citation":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"change_type":{"type":"string","enum":["amendment","final_rule","proposed_rule","correction"]},"effective_date":{"type":"string","format":"date","nullable":true},"detected_at":{"type":"string","format":"date-time","description":"When GovLaws detected or ingested this change."},"agency":{"type":"string","nullable":true},"source":{"type":"string"},"document_number":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"provenance":{"$ref":"#/components/schemas/ProvenanceObject"}}},"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 or U.S. Code citation, e.g. \"12 CFR 1026.43\" or \"15 U.S.C. § 1681\"","example":"15 U.S.C. § 1681"}}},"SearchRegulationsInput":{"type":"object","additionalProperties":false,"required":["query"],"properties":{"query":{"type":"string","description":"Natural-language or keyword query over federal regulations and U.S. Code canary coverage.","example":"fair credit reporting congressional findings"},"limit":{"type":"integer","minimum":1,"maximum":20,"default":5,"description":"Maximum number of ranked results to return."},"corpus":{"type":"string","enum":["regulations","statutes","all"],"default":"regulations","description":"Corpus filter. regulations = CFR only, statutes = U.S. Code only, all = CFR plus U.S. Code canary coverage. Defaults to regulations for backward compatibility."}}},"MppBatchResolveInput":{"type":"object","additionalProperties":false,"required":["citations"],"properties":{"citations":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10,"description":"CFR or U.S. Code citations to resolve in a single paid MPP request."},"fields":{"type":"array","items":{"type":"string","enum":["citation","title","text","agency","source","freshness","recent_changes","provenance"]},"default":["citation","title","text","provenance"],"description":"Fields to include in each resolved result."}}},"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","batch-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 or U.S. Code citation to current text + provenance","description":"Given a CFR or U.S. Code citation string, returns current text, source metadata, and provenance linking to official government sources. U.S. Code coverage is canary-first and should be requested explicitly by citation.","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 or U.S. Code citation, e.g. \"12 CFR 1026.43\" or \"15 U.S.C. § 1681\"","example":"15 U.S.C. § 1681"}],"responses":{"200":{"description":"Citation resolved","content":{"application/json":{"example":{"citation":"15 U.S.C. § 1681","title":"Congressional statement of findings and declaration of purpose","agency":null,"text":"The Congress makes the following findings...","source":{"system":"olrc_uscode","url":"https://uscode.house.gov/download/releasepoints/us/pl/119/84/xml_usc15@119-84.zip","retrieved_at":"2026-04-27T19:27:08Z"},"freshness":{"up_to_date_as_of":"2026-04-27T19:27:08Z","status":"current"},"recent_changes":[],"provenance":{"is_official_edition":false,"disclaimer":"Derived from Office of the Law Revision Counsel U.S. Code XML downloads.","official_artifact_url":"https://uscode.house.gov/download/releasepoints/us/pl/119/84/xml_usc15@119-84.zip","govinfo_source_url":null,"ecfr_url":null,"source_system":"olrc_uscode","currency":{"reflects_current_text":true,"as_of":"2026-04-27T19:27:08Z","effective_date":"Public Law 119-84"},"official_edition":{"is_official":false,"edition_year":null,"artifact_url":"https://uscode.house.gov/download/releasepoints/us/pl/119/84/xml_usc15@119-84.zip"},"trust":{"disclaimer_code":"USCODE_CURRENT","citation_suitability":["research","reference"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Citation not found"},"429":{"$ref":"#/components/responses/RateLimitExceeded"}}}},"/api/search":{"post":{"summary":"Semantic search over federal regulations and U.S. Code canary coverage","description":"Natural language or keyword query → ranked CFR sections and/or U.S. Code sections with snippets. Use corpus = statutes for U.S. Code canary results. The default corpus remains regulations.","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":"15 U.S.C. § 1681","title":"Congressional statement of findings and declaration of purpose","score":0.88,"snippet":"The Congress makes the following findings...","url":null}],"query":"fair credit reporting congressional findings","corpus":"statutes","total":1,"provenance":{"is_official_edition":false,"source_system":"olrc_uscode","trust":{"disclaimer_code":"USCODE_CURRENT","citation_suitability":["research","reference"]},"currency":{"reflects_current_text":true,"as_of":"2026-04-27T19:27:08Z","effective_date":"Public Law 119-84"}}}}}}}}},"/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","title":"Ability to Repay","change_type":"final_rule","effective_date":"2026-02-28","detected_at":"2026-03-11T12:00:00Z","agency":"Consumer Financial Protection Bureau","source":"Federal Register","document_number":"2026-04567","url":"https://www.federalregister.gov/documents/2026-04567","provenance":{"is_official_edition":true,"source_system":"federal_register","official_artifact_url":"https://www.federalregister.gov/documents/2026-04567","trust":{"disclaimer_code":"FR_NOTICE","citation_suitability":["research","reference","legal_filing"]},"currency":{"reflects_current_text":false,"as_of":"2026-03-11T12:00:00Z","effective_date":"2026-02-28"}}}],"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 mixed CFR and U.S. Code citations in a single request. Returns text + corpus-specific 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 or U.S. Code 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","15 U.S.C. § 1681"],"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,"source_system":"ecfr","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","trust":{"disclaimer_code":"ECFR_UNOFFICIAL","citation_suitability":["research","reference"]}}},{"citation":"15 U.S.C. § 1681","title":"Congressional statement of findings and declaration of purpose","text":"The Congress makes the following findings...","provenance":{"is_official_edition":false,"source_system":"olrc_uscode","official_artifact_url":"https://uscode.house.gov/download/releasepoints/us/pl/119/84/xml_usc15@119-84.zip","ecfr_url":null,"trust":{"disclaimer_code":"USCODE_CURRENT","citation_suitability":["research","reference"]}}}],"resolved":2,"errors":0}}}},"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. Staleness is source-specific: Federal Register is stale after 6 hours, while eCFR is stale after 30 hours because it runs daily.","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, U.S. Code canary titles, Federal Register change types, and state-statute placeholders) 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":24},{"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. Tempo pathUSD is the primary rail for the $0.05 microtransaction. Stripe Machine Payments is reserved for higher-value MPP charges that meet Stripe minimums.","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","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"50000","settlement":"Tempo pathUSD stablecoin","role":"primary"}]},"parameters":[{"name":"citation","in":"query","required":true,"schema":{"type":"string"},"description":"CFR or U.S. Code citation, e.g. \"12 CFR 1026.43\" or \"15 U.S.C. § 1681\"","example":"15 U.S.C. § 1681"}],"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/x402/resolve":{"get":{"summary":"Resolve a citation via x402 pay-per-request","description":"Same legal response as GET /api/resolve, but requires no GovLaws API key. Uses x402 exact payments over Base USDC through the Coinbase CDP facilitator. Designed for x402 Bazaar and Amazon Bedrock AgentCore Payments discovery.","operationId":"x402ResolveCitation","security":[],"tags":["x402"],"x-input-schema":{"$ref":"#/components/schemas/ResolveCitationInput"},"x-payment-info":{"amount":"0.05","currency":"USDC","description":"GovLaws citation resolution - official-source federal legal text with provenance","facilitator":"https://api.cdp.coinbase.com/platform/v2/x402","method":"x402","network":"eip155:8453","pay_to_configured":true,"scheme":"exact","settlement":"Base USDC via Coinbase CDP x402 facilitator"},"parameters":[{"name":"citation","in":"query","required":true,"schema":{"type":"string"},"description":"CFR or U.S. Code citation, e.g. \"12 CFR 1026.43\" or \"15 U.S.C. § 1681\"","example":"12 CFR 1026.43"}],"responses":{"200":{"description":"Citation resolved after x402 payment settlement."},"400":{"description":"Missing citation parameter"},"402":{"description":"Payment Required"},"404":{"description":"Citation not found"},"503":{"description":"x402 lane disabled or not configured"}}}},"/api/mpp/batch-resolve":{"post":{"summary":"Batch resolve citations via pay-per-request (MPP)","description":"Resolve up to 10 mixed CFR and U.S. Code citations in one no-signup MPP request. The request is validated before any payment challenge is issued. Uses Tempo pathUSD for the $0.15 batch charge.","operationId":"mppBatchResolveCitations","security":[],"tags":["MPP"],"x-input-schema":{"$ref":"#/components/schemas/MppBatchResolveInput"},"x-payment-info":{"amount":"150000","currency":"0x20c000000000000000000000b9537d11c60e8b50","description":"GovLaws batch citation resolution - up to 10 federal legal citations with provenance","intent":"charge","method":"tempo","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"150000","settlement":"Tempo pathUSD stablecoin","role":"primary"}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MppBatchResolveInput"},"example":{"citations":["12 CFR 1026.43","15 U.S.C. § 1681"],"fields":["citation","title","text","provenance"]}}}},"responses":{"200":{"description":"Batch results (paid). Includes Payment-Receipt header.","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,"source_system":"ecfr"}},{"citation":"15 U.S.C. § 1681","title":"Congressional statement of findings and declaration of purpose","text":"The Congress makes the following findings...","provenance":{"is_official_edition":false,"source_system":"olrc_uscode"}}],"resolved":2,"errors":0}}}},"400":{"description":"Missing or invalid citations array, invalid fields, or exceeds 10-citation MPP limit"},"402":{"description":"Payment Required"}}}},"/api/x402/search":{"post":{"summary":"Semantic search via x402 pay-per-request","description":"Same legal response as POST /api/search, but requires no GovLaws API key. Supports corpus = regulations, statutes, or all. Uses x402 exact payments over Base USDC through the Coinbase CDP facilitator.","operationId":"x402SearchFederalLegalText","security":[],"tags":["x402"],"x-input-schema":{"$ref":"#/components/schemas/SearchRegulationsInput"},"x-payment-info":{"amount":"0.03","currency":"USDC","description":"GovLaws federal legal search - semantic search across CFR and U.S. Code canary coverage","facilitator":"https://api.cdp.coinbase.com/platform/v2/x402","method":"x402","network":"eip155:8453","pay_to_configured":true,"scheme":"exact","settlement":"Base USDC via Coinbase CDP x402 facilitator"},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRegulationsInput"}}}},"responses":{"200":{"description":"Search results after x402 payment settlement."},"400":{"description":"Invalid or missing query"},"402":{"description":"Payment Required"},"503":{"description":"x402 lane disabled or not configured"}}}},"/api/x402/changes":{"get":{"summary":"Recent regulatory changes via x402 pay-per-request","description":"Same legal response as GET /api/changes, but requires no GovLaws API key. Uses x402 exact payments over Base USDC through the Coinbase CDP facilitator.","operationId":"x402GetChanges","security":[],"tags":["x402"],"x-input-schema":{"$ref":"#/components/schemas/ChangesQueryInput"},"x-payment-info":{"amount":"0.03","currency":"USDC","description":"GovLaws change feed - recent Federal Register activity with source links","facilitator":"https://api.cdp.coinbase.com/platform/v2/x402","method":"x402","network":"eip155:8453","pay_to_configured":true,"scheme":"exact","settlement":"Base USDC via Coinbase CDP x402 facilitator"},"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 after x402 payment settlement."},"400":{"description":"Invalid query parameters"},"402":{"description":"Payment Required"},"503":{"description":"x402 lane disabled or not configured"}}}},"/api/mpp/search":{"post":{"summary":"Semantic search via pay-per-request (MPP)","description":"Same as POST /api/search but requires no API key. Supports corpus = regulations, statutes, or all. 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","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"30000","settlement":"Tempo pathUSD stablecoin","role":"primary"}]},"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":"15 U.S.C. § 1681","title":"...","score":0.88,"snippet":"..."}],"query":"fair credit reporting congressional findings","corpus":"statutes","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","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"30000","settlement":"Tempo pathUSD stablecoin","role":"primary"}]},"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","title":"Ability to Repay","change_type":"final_rule","effective_date":"2026-02-28","detected_at":"2026-03-19T12:00:00Z"}],"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","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"0","settlement":"Tempo pathUSD stablecoin","role":"primary"}]},"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","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"0","settlement":"Tempo pathUSD stablecoin","role":"primary"}]},"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","methods":[{"method":"tempo","intent":"charge","currency":"0x20c000000000000000000000b9537d11c60e8b50","decimals":6,"amount":"0","settlement":"Tempo pathUSD stablecoin","role":"primary"}]},"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 pathUSD is primary for current microtransactions. Stripe Machine Payments is configured for higher-value MPP charges that meet Stripe minimums. No API key needed — payment via 402 challenge/credential flow."},{"name":"x402","description":"Pay-per-request endpoints via x402 exact payments over Base USDC through the Coinbase CDP facilitator. Intended for x402 Bazaar and Amazon Bedrock AgentCore Payments discovery."},{"name":"System","description":"Health and status endpoints"}]}