{"openapi":"3.1.0","info":{"title":"LicenseGround API","description":"Machine-readable regulatory ground truth and compliance verification for trade contractors in CA, FL, and TX.","version":"1.0.0"},"paths":{"/":{"get":{"summary":"Landing Page","description":"Serve the interactive developer portal & playground.","operationId":"landing_page__get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/v1/health":{"get":{"summary":"Health Check","description":"Health status and cache metrics.","operationId":"health_check_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/verify":{"post":{"summary":"Verify License","description":"Verify state trade contractor license with low-latency persistent caching.\nSupports California (CSLB), Florida (DBPR), and Texas (TDLR).","operationId":"verify_license_v1_verify_post","parameters":[{"name":"X-Agent-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-Key"}},{"name":"X-Agent-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseVerificationQuery"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LicenseVerificationResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/compliance-check":{"post":{"summary":"Check Compliance","description":"Evaluate contractor against compliance rules (active license, workers comp, surety bond, citations).\nReturns instant deterministic boolean (can_hire), risk score, and risk flags.","operationId":"check_compliance_v1_compliance_check_post","parameters":[{"name":"X-Agent-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-Key"}},{"name":"X-Agent-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComplianceRiskQuery"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComplianceRiskResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/search":{"post":{"summary":"Search Contractors","description":"Search active licensed trade contractors by trade classification and city.","operationId":"search_contractors_v1_search_post","parameters":[{"name":"X-Agent-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-Key"}},{"name":"X-Agent-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractorSearchQuery"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractorSearchResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/federal/debarment-check":{"post":{"summary":"Check Federal Debarment Endpoint","description":"Check if contractor entity is debarred or suspended on the federal SAM.gov EPLS.","operationId":"check_federal_debarment_endpoint_v1_federal_debarment_check_post","parameters":[{"name":"X-Agent-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-Key"}},{"name":"X-Agent-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNameQuery"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/safety/osha-audit":{"post":{"summary":"Check Osha Safety Endpoint","description":"Audit contractor worksite safety history against the OSHA inspection and enforcement database.","operationId":"check_osha_safety_endpoint_v1_safety_osha_audit_post","parameters":[{"name":"X-Agent-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-Key"}},{"name":"X-Agent-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Agent-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNameQuery"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agent-keys":{"post":{"summary":"Create Agent Api Key","description":"Autonomous registration endpoint: AI agents or deployment scripts can register\nand receive an evaluation API key preloaded with 25 free queries.\nProtected by strict IP rate limiting to prevent Sybil/abuse attacks.","operationId":"create_agent_api_key_v1_agent_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentKeyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeterStatus"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agent-keys/{api_key}":{"get":{"summary":"Get Agent Key Status","description":"Check credit balance, total queries used, and spending ceilings.","operationId":"get_agent_key_status_v1_agent_keys__api_key__get","parameters":[{"name":"api_key","in":"path","required":true,"schema":{"type":"string","title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeterStatus"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/agent-topup":{"post":{"summary":"Top Up Agent Credits","description":"Top up credit balance for an agent key.","operationId":"top_up_agent_credits_v1_agent_topup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopUpCreditsRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeterStatus"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/checkout/create-session":{"post":{"summary":"Create Checkout Session Endpoint","description":"Generate a Stripe Checkout session or development simulation.","operationId":"create_checkout_session_endpoint_v1_checkout_create_session_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stripe-webhook":{"post":{"summary":"Stripe Webhook","description":"Stripe webhook listener to credit API keys upon successful checkout.","operationId":"stripe_webhook_v1_stripe_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/checkout/simulate-payment":{"get":{"summary":"Simulate Checkout Payment","description":"Simulate instant successful Stripe payment for local testing and dev.","operationId":"simulate_checkout_payment_checkout_simulate_payment_get","parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string","title":"Session Id"}},{"name":"key","in":"query","required":true,"schema":{"type":"string","title":"Key"}},{"name":"plan","in":"query","required":false,"schema":{"type":"string","default":"growth","title":"Plan"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/checkout/success":{"get":{"summary":"Checkout Success Page","description":"Landing page after successful checkout.","operationId":"checkout_success_page_checkout_success_get","parameters":[{"name":"session_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"}},{"name":"key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Key"}},{"name":"plan","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"growth","title":"Plan"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"CheckoutSessionRequest":{"properties":{"plan":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan"},"plan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Id","default":"growth"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},"type":"object","title":"CheckoutSessionRequest"},"ComplianceRiskQuery":{"properties":{"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name"},"license_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License Number"},"state":{"$ref":"#/components/schemas/StateCode"},"trade":{"$ref":"#/components/schemas/TradeCategory","default":"any"},"require_active_status":{"type":"boolean","title":"Require Active Status","description":"Enforce ACTIVE_CURRENT status.","default":true},"require_workers_comp":{"type":"boolean","title":"Require Workers Comp","description":"Reject if no verified workers comp policy (or unverified exemption).","default":true},"require_surety_bond":{"type":"boolean","title":"Require Surety Bond","description":"Enforce active contractor bond.","default":true},"max_disciplinary_actions":{"type":"integer","title":"Max Disciplinary Actions","description":"Maximum acceptable disciplinary citations.","default":0},"min_confidence_score":{"type":"number","title":"Min Confidence Score","description":"Minimum entity name grounding match confidence.","default":0.85}},"type":"object","required":["state"],"title":"ComplianceRiskQuery","description":"Input for automated policy assessment for autonomous hiring/procurement."},"ComplianceRiskResult":{"properties":{"can_hire":{"type":"boolean","title":"Can Hire","description":"Deterministic decision: True if compliant with all risk criteria."},"risk_level":{"$ref":"#/components/schemas/RiskLevel","description":"LOW, MEDIUM, HIGH, or CRITICAL."},"risk_score":{"type":"number","maximum":100.0,"minimum":0.0,"title":"Risk Score","description":"Risk index from 0.0 (safest) to 100.0 (maximum risk)."},"flags":{"items":{"type":"string"},"type":"array","title":"Flags","description":"Specific risk warning triggers."},"verification":{"$ref":"#/components/schemas/LicenseVerificationResult","description":"Full underlying verification ground truth."}},"type":"object","required":["can_hire","risk_level","risk_score","verification"],"title":"ComplianceRiskResult","description":"Instant machine-actionable hiring decision."},"ContractorSearchQuery":{"properties":{"state":{"$ref":"#/components/schemas/StateCode","description":"Two-letter US state code (CA, FL, TX)."},"trade":{"$ref":"#/components/schemas/TradeCategory","description":"Trade category (roofing, hvac, electrical, plumbing, general_contractor)."},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"City name to search in."},"limit":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Limit","description":"Maximum number of licensed entities to return.","default":10}},"type":"object","required":["state","trade"],"title":"ContractorSearchQuery","description":"Input payload for searching contractors by trade and location."},"ContractorSearchResult":{"properties":{"state":{"$ref":"#/components/schemas/StateCode"},"trade":{"$ref":"#/components/schemas/TradeCategory"},"total_found":{"type":"integer","title":"Total Found"},"contractors":{"items":{"$ref":"#/components/schemas/LicenseVerificationResult"},"type":"array","title":"Contractors"}},"type":"object","required":["state","trade","total_found","contractors"],"title":"ContractorSearchResult","description":"Result list of active licensed trade contractors."},"CreateAgentKeyRequest":{"properties":{"agent_name":{"type":"string","title":"Agent Name","default":"autonomous-procurement-agent"},"spending_ceiling_usd":{"type":"number","title":"Spending Ceiling Usd","default":50.0}},"type":"object","title":"CreateAgentKeyRequest"},"DisciplinaryRecord":{"properties":{"case_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Case Number"},"action_type":{"type":"string","title":"Action Type","description":"E.g., 'Citation', 'Formal Accusation', 'Administrative Fine', 'Suspension Order'"},"effective_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Effective Date"},"description":{"type":"string","title":"Description","description":"Summary of board violation or sanctions"},"penalty_amount":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Penalty Amount"},"resolved":{"type":"boolean","title":"Resolved","default":true}},"type":"object","required":["action_type","description"],"title":"DisciplinaryRecord","description":"Detail of any disciplinary citations, suspensions, or formal administrative actions."},"EntityNameQuery":{"properties":{"entity_name":{"type":"string","title":"Entity Name"}},"type":"object","required":["entity_name"],"title":"EntityNameQuery"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LicenseStatus":{"type":"string","enum":["ACTIVE_CURRENT","INACTIVE","EXPIRED","SUSPENDED","REVOKED","PENDING","DELINQUENT","NOT_FOUND"],"title":"LicenseStatus"},"LicenseVerificationQuery":{"properties":{"entity_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Name","description":"The business name or DBA to verify (e.g. 'Apex Roofing LLC'). At least entity_name or license_number must be provided."},"state":{"$ref":"#/components/schemas/StateCode","description":"Two-letter US state code. Supported in Option 1: CA, FL, TX."},"license_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License Number","description":"State license or certificate registration number (e.g., 'CCC1330999', '1058291', 'TACLA12345C')."},"trade":{"$ref":"#/components/schemas/TradeCategory","description":"Primary trade category to filter or validate against: roofing, hvac, electrical, plumbing, general_contractor, or any.","default":"any"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"Optional city to filter geographic disambiguation."}},"type":"object","required":["state"],"title":"LicenseVerificationQuery","description":"Input payload for verifying a trade contractor license."},"LicenseVerificationResult":{"properties":{"verified":{"type":"boolean","title":"Verified","description":"True if the entity possesses an authentic, matching registration on the official state registry."},"canonical_name":{"type":"string","title":"Canonical Name","description":"Official legal business name registered with the state licensing board."},"dba_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dba Name","description":"Registered Doing-Business-As (DBA) or fictitious business name if applicable."},"license_number":{"type":"string","title":"License Number","description":"Official state license/certificate identifier."},"state":{"$ref":"#/components/schemas/StateCode","description":"State code (CA, FL, TX)."},"trade_classification":{"type":"string","title":"Trade Classification","description":"State trade classification (e.g., 'C-39 Roofing', 'CCC Certified Roofing Contractor', 'TACLA HVAC')."},"trade_category":{"$ref":"#/components/schemas/TradeCategory","description":"Normalized trade category.","default":"any"},"status":{"$ref":"#/components/schemas/LicenseStatus","description":"Current operational license status."},"is_active":{"type":"boolean","title":"Is Active","description":"Helper boolean: True only if status is ACTIVE_CURRENT."},"disciplinary_actions":{"type":"integer","title":"Disciplinary Actions","description":"Total count of historical or pending disciplinary actions/citations.","default":0},"disciplinary_records":{"items":{"$ref":"#/components/schemas/DisciplinaryRecord"},"type":"array","title":"Disciplinary Records","description":"Detailed list of formal board actions, if any."},"issue_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issue Date","description":"Date the license was originally issued (YYYY-MM-DD)."},"expiration_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expiration Date","description":"Expiration date of the current license cycle (YYYY-MM-DD)."},"is_expired":{"type":"boolean","title":"Is Expired","description":"True if expiration_date is in the past.","default":false},"workers_comp_exempt":{"type":"boolean","title":"Workers Comp Exempt","description":"True if the contractor filed an exemption claiming zero employees.","default":false},"workers_comp_covered":{"type":"boolean","title":"Workers Comp Covered","description":"True if active Workers' Compensation insurance policy is confirmed on file with the state board.","default":false},"workers_comp_insurer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Workers Comp Insurer","description":"Name of workers' comp insurance carrier, policy number, or status note."},"bond_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bond Status","description":"Contractor surety bond status (e.g. 'ACTIVE $25,000', 'EXEMPT', 'NOT_REQUIRED')."},"bond_company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bond Company","description":"Surety company underwriting the contractor bond."},"business_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Address","description":"Principal place of business on official record."},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"},"zip_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zip Code"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"},"qualifying_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qualifying Agent","description":"Licensed individual qualifier, master, or primary officer (e.g. Master Electrician or RMO/RME)."},"grounding_confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Grounding Confidence","description":"Confidence score (0.0 to 1.0) indicating exactness of entity name match against registry records."},"source_registry":{"type":"string","title":"Source Registry","description":"Official source registry name (e.g. 'CA Contractors State License Board (CSLB)')."},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url","description":"Direct URL to official state verification record."},"cached":{"type":"boolean","title":"Cached","description":"True if served from low-latency persistent cache.","default":false},"source_timestamp":{"type":"string","title":"Source Timestamp","description":"ISO 8601 timestamp when data was fetched or grounded."}},"type":"object","required":["verified","canonical_name","license_number","state","trade_classification","status","is_active","grounding_confidence","source_registry"],"title":"LicenseVerificationResult","description":"Machine-actionable, deterministic ground-truth verification result."},"MeterStatus":{"properties":{"api_key":{"type":"string","title":"Api Key"},"remaining_credits":{"type":"integer","title":"Remaining Credits"},"total_used":{"type":"integer","title":"Total Used"},"spending_ceiling_usd":{"type":"number","title":"Spending Ceiling Usd"},"current_spend_usd":{"type":"number","title":"Current Spend Usd"},"is_active":{"type":"boolean","title":"Is Active"}},"type":"object","required":["api_key","remaining_credits","total_used","spending_ceiling_usd","current_spend_usd","is_active"],"title":"MeterStatus","description":"Credits and usage metering information for agent accounts."},"RiskLevel":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"],"title":"RiskLevel"},"StateCode":{"type":"string","enum":["CA","FL","TX","NY","MA","IL","AZ","US"],"title":"StateCode"},"TopUpCreditsRequest":{"properties":{"api_key":{"type":"string","title":"Api Key"},"credits":{"type":"integer","title":"Credits","default":500},"payment_reference":{"type":"string","title":"Payment Reference","default":"tx_settled_micro_rail"}},"type":"object","required":["api_key"],"title":"TopUpCreditsRequest"},"TradeCategory":{"type":"string","enum":["roofing","hvac","electrical","plumbing","general_contractor","any"],"title":"TradeCategory"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}