{"openapi":"3.1.0","info":{"title":"The Leo King Business Intelligence API","version":"1.0.0-alpha.1","description":"B2B astrology intelligence endpoints for audience insights, geocentric tropical chart calculation, Beyond The Veil world forecasting, and heliocentric tropical StarTypes pattern lookup."},"externalDocs":{"description":"Human developer documentation","url":"https://theleokingai.com/api-docs"},"tags":[{"name":"Developer Metadata","description":"Public discovery, status, changelog, and webhook contract endpoints."},{"name":"Audience Intelligence","description":"Customer and campaign-fit intelligence."},{"name":"Experience APIs","description":"Premium spiritual AI experience routes."},{"name":"Chart Core","description":"Deterministic astrology calculation routes."},{"name":"World Signals","description":"Beyond The Veil world intelligence and async jobs."},{"name":"Helio StarTypes","description":"Heliocentric tropical StarTypes background lookup."}],"servers":[{"url":"https://api.theleokingai.com","description":"Current production API host"},{"url":"https://theleokingai.com/api","description":"Legacy website API host for existing alpha integrations"},{"url":"http://localhost:3000/api","description":"Local Next.js development"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"headers":{"RequestId":{"description":"Trace id for support, usage reconciliation, and incident review. Mirrors the JSON request_id.","schema":{"type":"string"}},"ApiVersion":{"description":"Public API major version for this response.","schema":{"type":"string","examples":["v1"]}},"CacheControl":{"description":"Paid API responses are not cacheable by intermediaries.","schema":{"type":"string","examples":["no-store"]}},"RateLimitLimit":{"description":"Maximum requests available in the current rate-limit window when limiter metadata is present.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests remaining in the current rate-limit window when limiter metadata is present.","schema":{"type":"integer"}},"RateLimitReset":{"description":"Seconds until the rate-limit window resets when limiter metadata is present.","schema":{"type":"integer"}},"RetryAfter":{"description":"Seconds the client should wait before retrying a rate-limited request.","schema":{"type":"integer"}}},"schemas":{"DeveloperStatusComponent":{"type":"object","required":["name","status","scope","evidence","publicNote"],"properties":{"name":{"type":"string"},"status":{"type":"string","enum":["live","beta","release_gate"]},"scope":{"type":"string"},"evidence":{"type":"string"},"publicNote":{"type":"string"}}},"DeveloperSlaTarget":{"type":"object","required":["name","status","availabilityTarget","measurement","scope","escalation","exclusions"],"properties":{"name":{"type":"string"},"status":{"type":"string","enum":["live","beta","enterprise"]},"availabilityTarget":{"type":"string"},"measurement":{"type":"string"},"scope":{"type":"array","items":{"type":"string"}},"escalation":{"type":"string"},"exclusions":{"type":"array","items":{"type":"string"}}}},"DeveloperIncidentEntry":{"type":"object","required":["id","status","severity","title","startedAt","resolvedAt","affectedComponents","summary","customerAction"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["investigating","identified","monitoring","resolved","postmortem"]},"severity":{"type":"string","enum":["sev1","sev2","sev3","maintenance"]},"title":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"resolvedAt":{"type":["string","null"],"format":"date-time"},"affectedComponents":{"type":"array","items":{"type":"string"}},"summary":{"type":"string"},"customerAction":{"type":"string"}}},"DeveloperIncidentReportingPolicy":{"type":"object","required":["publicationWindow","severityLevels","requiredFields","postmortemPolicy","supportChannel"],"properties":{"publicationWindow":{"type":"string","examples":["Publish a public incident entry for confirmed partner-impacting production issues that last more than 15 minutes or affect billed output quality."]},"severityLevels":{"type":"array","items":{"type":"string"}},"requiredFields":{"type":"array","items":{"type":"string"}},"postmortemPolicy":{"type":"string"},"supportChannel":{"type":"string"}}},"DeveloperSecurityControl":{"type":"object","required":["name","status","scope","partnerExpectation","evidence"],"properties":{"name":{"type":"string","enum":["Server-Side API Keys","Dedicated HTTPS Gateway","Scoped Endpoint Access","Retry-Safe Usage Records","No Fallback Success For AI Output","Data Minimization","Rate Limits And Abuse Guard","Enterprise Security Review"]},"status":{"type":"string","enum":["live","beta","enterprise"]},"scope":{"type":"string"},"partnerExpectation":{"type":"string"},"evidence":{"type":"string"}}},"DeveloperAccessEnvironment":{"type":"object","required":["name","status","baseUrl","keyPrefix","purpose","dataBoundary"],"properties":{"name":{"type":"string","enum":["Production Gateway","Legacy Website API Host","Local Development"]},"status":{"type":"string","enum":["live","beta"]},"baseUrl":{"type":"string"},"keyPrefix":{"type":"string"},"purpose":{"type":"string"},"dataBoundary":{"type":"string"}}},"DeveloperKeyLifecycleStep":{"type":"object","required":["step","status","owner","action","evidence"],"properties":{"step":{"type":"string","enum":["Create Server-Side Key","Store In Backend Secret Manager","Validate Scope Before Launch","Rotate On Exposure Or Staff Change","Revoke Or Pause On Incident","Negotiate Enterprise Controls"]},"status":{"type":"string","enum":["beta","live","enterprise"]},"owner":{"type":"string","enum":["partner","platform","shared"]},"action":{"type":"string"},"evidence":{"type":"string"}}},"DeveloperAccessControlRequirement":{"type":"object","required":["name","status","scope","partnerRequirement","platformEvidence"],"properties":{"name":{"type":"string","enum":["Server-Side Custody","Endpoint Scope","Environment Separation","Rotation And Revocation","Rate-Limit Cooperation","Enterprise Network Controls"]},"status":{"type":"string","enum":["live","beta","enterprise"]},"scope":{"type":"string"},"partnerRequirement":{"type":"string"},"platformEvidence":{"type":"string"}}},"DeveloperDataRetentionPolicy":{"type":"object","required":["category","status","retention","handling"],"properties":{"category":{"type":"string","enum":["API Request Metadata","Birth Data Payloads","Generated AI Outputs","Billing And Entitlement Records","Support Evidence","Raw Secrets"]},"status":{"type":"string","enum":["beta","live"]},"retention":{"type":"string"},"handling":{"type":"string"}}},"DeveloperDataProcessingPurpose":{"type":"object","required":["category","status","purpose","dataCategories","lawfulBasisBoundary","retentionSource","partnerResponsibility"],"properties":{"category":{"type":"string","enum":["Core Astrology Compute","AI Intelligence And Experiences","Billing And Entitlement","Support, Incident, And Conformance Evidence"]},"status":{"type":"string","enum":["beta","live"]},"purpose":{"type":"string"},"dataCategories":{"type":"array","items":{"type":"string"}},"lawfulBasisBoundary":{"type":"string"},"retentionSource":{"type":"string"},"partnerResponsibility":{"type":"string"}}},"DeveloperSubprocessor":{"type":"object","required":["name","purpose","dataScope","status"],"properties":{"name":{"type":"string","enum":["Vercel","Convex","Clerk","Stripe","OpenAI Or RunPod","Render","Upstash","Sentry"]},"purpose":{"type":"string"},"dataScope":{"type":"string"},"status":{"type":"string","enum":["live","beta"]}}},"DeveloperObservabilityCheck":{"type":"object","required":["name","status","signal","cadence","publicEvidence"],"properties":{"name":{"type":"string","enum":["Production Env Gate","Dedicated Gateway Smoke","Buyer Path Usage Proof","Internal Deep Readiness","AI Output Quality Sampling","Incident Ledger","Error Catalog"]},"status":{"type":"string","enum":["live","beta"]},"signal":{"type":"string"},"cadence":{"type":"string"},"publicEvidence":{"type":"string"}}},"DeveloperOnboardingStep":{"type":"object","required":["step","status","owner","action","proof"],"properties":{"step":{"type":"string","enum":["Choose The Production Base URL","Create A Server-Side Key","Make The First Core Request","Wire Retry And Error Handling","Verify Usage And Credits","Sample AI Output Quality","Prepare The Support Packet","Request Enterprise Terms"]},"status":{"type":"string","enum":["live","beta","enterprise"]},"owner":{"type":"string","enum":["partner","platform","shared"]},"action":{"type":"string"},"proof":{"type":"string"}}},"DeveloperLaunchReadinessGate":{"type":"object","required":["gate","status","owner","requiredEvidence","failureMode"],"properties":{"gate":{"type":"string","enum":["Dedicated Gateway Reachability","Partner Server Key Handling","Usage Ledger Reconciliation","AI Output Quality Sampling","Support And Incident Drill","Signed Enterprise Boundary"]},"status":{"type":"string","enum":["live","beta","enterprise"]},"owner":{"type":"string","enum":["partner","platform","shared"]},"requiredEvidence":{"type":"string"},"failureMode":{"type":"string"}}},"DeveloperLaunchHandoffArtifact":{"type":"object","required":["artifact","owner","requiredFor","redactionBoundary"],"properties":{"artifact":{"type":"string","enum":["Production Smoke Evidence","Partner Integration Matrix","Usage And Billing Proof","AI Quality Evidence","Rollback And Disable Plan"]},"owner":{"type":"string","enum":["partner","platform","shared"]},"requiredFor":{"type":"string"},"redactionBoundary":{"type":"string"}}},"DeveloperSupportTier":{"type":"object","required":["name","status","audience","availability","firstResponseTarget","channels","scope","escalation"],"properties":{"name":{"type":"string","enum":["Developer Metadata Support","Partner Beta Support","Enterprise Contract Support"]},"status":{"type":"string","enum":["live","beta","enterprise"]},"audience":{"type":"string"},"availability":{"type":"string"},"firstResponseTarget":{"type":"string"},"channels":{"type":"array","items":{"type":"string"}},"scope":{"type":"array","items":{"type":"string"}},"escalation":{"type":"string"}}},"DeveloperSdkPackage":{"type":"object","required":["language","packageName","status","sourcePath","installCommand","localBuildCommand","helperSurface","releaseGates"],"properties":{"language":{"type":"string","enum":["node","python"]},"packageName":{"type":"string","enum":["@theleoking/ai-api","theleoking-ai-api"]},"status":{"type":"string","enum":["release_gate"]},"sourcePath":{"type":"string"},"installCommand":{"type":"string"},"localBuildCommand":{"type":"string"},"helperSurface":{"type":"array","items":{"type":"string"}},"releaseGates":{"type":"array","items":{"type":"string"}}}},"DeveloperMigrationGuide":{"type":"object","required":["id","title","status","audience","from","to","reason","timeline","steps","validation"],"properties":{"id":{"type":"string","enum":["legacy-alpha-host-to-dedicated-gateway","customer-profile-alias-to-audience-insights","mundane-forecast-alias-to-world-signals"]},"title":{"type":"string"},"status":{"type":"string","enum":["live","beta"]},"audience":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"reason":{"type":"string"},"timeline":{"type":"string"},"steps":{"type":"array","items":{"type":"string"}},"validation":{"type":"array","items":{"type":"string"}}}},"DeveloperProcurementReviewItem":{"type":"object","required":["category","status","owner","requirement","evidence","publicLink"],"properties":{"category":{"type":"string","enum":["Security Controls","Data Handling","Compliance Mapping","AI Governance","Subprocessor Review","SLA And Incidents","Versioning And Migration","Operational Proof","Legal Terms"]},"status":{"type":"string","enum":["live","beta","enterprise"]},"owner":{"type":"string","enum":["partner","platform","shared"]},"requirement":{"type":"string"},"evidence":{"type":"string"},"publicLink":{"type":"string"}}},"DeveloperComplianceMapping":{"type":"object","required":["framework","status","scope","mappedControls","evidenceLinks","reviewerAction","boundary"],"properties":{"framework":{"type":"string","enum":["SOC 2-Style Security Review","SOC 2-Style Availability Review","GDPR/Data Processing Review Readiness","OWASP API Security Review Readiness","Enterprise Procurement And Vendor Risk","AI Output Quality Governance"]},"status":{"type":"string","enum":["live","beta"]},"scope":{"type":"string"},"mappedControls":{"type":"array","items":{"type":"string"}},"evidenceLinks":{"type":"array","items":{"type":"string"}},"reviewerAction":{"type":"string"},"boundary":{"type":"string"}}},"DeveloperComplianceEvidenceItem":{"type":"object","required":["artifact","status","owner","evidence","publicLink","reviewUse"],"properties":{"artifact":{"type":"string","enum":["Security Packet","Access-Control Packet","Data-Processing Packet","Conformance Contract","Observability Proof","SLA And Incident Policy","Procurement Packet"]},"status":{"type":"string","enum":["live","beta"]},"owner":{"type":"string","enum":["partner","platform","shared"]},"evidence":{"type":"string"},"publicLink":{"type":"string"},"reviewUse":{"type":"string"}}},"DeveloperAiUseCaseBoundary":{"type":"object","required":["category","status","allowedUse","restrictedUse","prohibitedUse","partnerResponsibility"],"properties":{"category":{"type":"string","enum":["Entertainment, Wellness, And Personal Insight","Audience Intelligence And Campaign Strategy","World Signals, Markets, And Public Research","Core Astrology Compute"]},"status":{"type":"string","enum":["beta","live"]},"allowedUse":{"type":"string"},"restrictedUse":{"type":"string"},"prohibitedUse":{"type":"string"},"partnerResponsibility":{"type":"string"}}},"DeveloperAiGovernanceControl":{"type":"object","required":["name","status","owner","scope","requirement","evidence","publicLink"],"properties":{"name":{"type":"string","enum":["No Fallback Success","Route-Specific Quality Gates","Human Review Boundary","Restricted Use Escalation","Transparent Support Evidence","Data Minimization"]},"status":{"type":"string","enum":["live","beta","enterprise"]},"owner":{"type":"string","enum":["partner","platform","shared"]},"scope":{"type":"string"},"requirement":{"type":"string"},"evidence":{"type":"string"},"publicLink":{"type":"string"}}},"DeveloperConformanceCheck":{"type":"object","required":["id","suite","status","owner","target","command","proves","passCriteria","evidenceArtifacts","failureEscalation"],"properties":{"id":{"type":"string","enum":["local-contract-suite","api-reference-discovery-smoke","sdk-source-and-dist","production-build-suite","production-env-gate","dedicated-gateway-smoke","buyer-path-usage-smoke","github-production-release-gate","ai-output-quality-sampling"]},"suite":{"type":"string"},"status":{"type":"string","enum":["live","beta"]},"owner":{"type":"string","enum":["partner","platform","shared"]},"target":{"type":"string"},"command":{"type":"string"},"proves":{"type":"string"},"passCriteria":{"type":"array","items":{"type":"string"}},"evidenceArtifacts":{"type":"array","items":{"type":"string"}},"failureEscalation":{"type":"string"}}},"DeveloperWebhookEvent":{"type":"object","required":["event","status","category","description","delivery","when","payload","idempotency","signature","retryPolicy"],"properties":{"event":{"type":"string","enum":["world_signal.job.completed","world_signal.job.failed","usage.recorded","quality.failed","entitlement.updated","billing.subscription.updated"]},"status":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"delivery":{"type":"string"},"when":{"type":"string"},"payload":{"type":"array","items":{"type":"string"}},"idempotency":{"type":"string"},"signature":{"type":"string"},"retryPolicy":{"type":"string"}}},"DeveloperChangelogEntry":{"type":"object","required":["version","date","status","statusLabel","title","summary","highlights"],"properties":{"version":{"type":"string"},"date":{"type":"string"},"status":{"type":"string"},"statusLabel":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"highlights":{"type":"array","items":{"type":"string"}}}},"DeveloperStatusResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","components","links","readiness"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-beta"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"components":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperStatusComponent"}},"links":{"type":"object","additionalProperties":{"type":"string"}},"readiness":{"type":"object"}}},"DeveloperSlaResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","measurementStatus","gatewayHost","targets","incidentPolicy","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"measurementStatus":{"type":"string","examples":["published-targets-monitoring-next"]},"gatewayHost":{"type":"object"},"targets":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperSlaTarget"}},"incidentPolicy":{"$ref":"#/components/schemas/DeveloperIncidentReportingPolicy"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperIncidentsResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","historyStatus","incidents","reportingPolicy","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"historyStatus":{"type":"string","enum":["no-public-incidents-recorded"]},"incidents":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperIncidentEntry"}},"reportingPolicy":{"$ref":"#/components/schemas/DeveloperIncidentReportingPolicy"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperSecurityResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","scope","controls","dataRetention","subprocessors","securityTxt","enterpriseNotes","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"scope":{"type":"string"},"controls":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperSecurityControl"}},"dataRetention":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperDataRetentionPolicy"}},"subprocessors":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperSubprocessor"}},"securityTxt":{"type":"object"},"enterpriseNotes":{"type":"object"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperAccessControlResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","policy","environments","keyLifecycle","requirements","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"policy":{"type":"object","properties":{"status":{"type":"string","examples":["live"]},"authenticationHeader":{"type":"string","examples":["x-api-key"]},"keyStoragePolicy":{"type":"string"},"browserBoundary":{"type":"string"},"scopeModel":{"type":"string"},"rotationPolicy":{"type":"string"},"revocationPolicy":{"type":"string"},"corsPolicy":{"type":"string"},"ipAllowlistBoundary":{"type":"string"},"enterpriseBoundary":{"type":"string"},"supportEvidence":{"type":"array","items":{"type":"string"}},"neverInclude":{"type":"array","items":{"type":"string"}}}},"environments":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperAccessEnvironment"}},"keyLifecycle":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperKeyLifecycleStep"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperAccessControlRequirement"}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperObservabilityResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","checks","productionChecklist","runbooks","deploymentEvidence","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"checks":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperObservabilityCheck"}},"productionChecklist":{"type":"array","items":{"type":"string"},"examples":[["Production env gate prints READY FOR PUSH/DEPLOY for the target environment.","API CI passes lint, full tests, source-only API reference smoke, and production build.","GitHub API Production Release Gate passes in the protected production environment after deploy.","Dedicated gateway smoke passes in final mode on api.theleokingai.com.","Buyer-path smoke passes against the dedicated gateway with Convex proof enabled.","Core endpoints return no token usage and AI endpoints return model/token visibility.","Fresh AI outputs satisfy product quality requirements after the deploy timestamp.","Support packet includes request_id, endpoint, key prefix only, UTC timestamp, and sanitized payload shape.","Access-control review confirms server-side key custody, endpoint scope, environment separation, rotation triggers, and no public-client key exposure.","Compliance mapping review confirms public evidence links, framework-style mapping, no certification overclaim, and signed-term boundaries.","AI governance review confirms acceptable-use boundaries, prohibited/restricted use cases, human-review requirements, and no fallback-success behavior.","Conformance evidence includes local contract tests, SDK build, app build, env gate, gateway smoke, buyer-path proof, and AI output sampling when relevant.","Data-processing review confirms minimization, restricted-data boundaries, retention policy, subprocessor scope, and signed-DPA requirements.","Launch-readiness handoff includes smoke evidence, partner integration matrix, billing proof, AI quality evidence, and rollback plan."]]},"runbooks":{"type":"object"},"deploymentEvidence":{"type":"object"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperOnboardingResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","productionBaseUrl","steps","launchReadinessGates","handoffArtifacts","productionChecklist","firstCoreRequest","supportPacket","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"productionBaseUrl":{"type":"string","examples":["https://api.theleokingai.com"]},"steps":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperOnboardingStep"}},"launchReadinessGates":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperLaunchReadinessGate"}},"handoffArtifacts":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperLaunchHandoffArtifact"}},"productionChecklist":{"type":"array","items":{"type":"string"},"examples":[["Production env gate prints READY FOR PUSH/DEPLOY for the target environment.","API CI passes lint, full tests, source-only API reference smoke, and production build.","GitHub API Production Release Gate passes in the protected production environment after deploy.","Dedicated gateway smoke passes in final mode on api.theleokingai.com.","Buyer-path smoke passes against the dedicated gateway with Convex proof enabled.","Core endpoints return no token usage and AI endpoints return model/token visibility.","Fresh AI outputs satisfy product quality requirements after the deploy timestamp.","Support packet includes request_id, endpoint, key prefix only, UTC timestamp, and sanitized payload shape.","Access-control review confirms server-side key custody, endpoint scope, environment separation, rotation triggers, and no public-client key exposure.","Compliance mapping review confirms public evidence links, framework-style mapping, no certification overclaim, and signed-term boundaries.","AI governance review confirms acceptable-use boundaries, prohibited/restricted use cases, human-review requirements, and no fallback-success behavior.","Conformance evidence includes local contract tests, SDK build, app build, env gate, gateway smoke, buyer-path proof, and AI output sampling when relevant.","Data-processing review confirms minimization, restricted-data boundaries, retention policy, subprocessor scope, and signed-DPA requirements.","Launch-readiness handoff includes smoke evidence, partner integration matrix, billing proof, AI quality evidence, and rollback plan."]]},"firstCoreRequest":{"type":"object"},"supportPacket":{"type":"object"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperVersioningResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","lifecycle","rateLimits","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"lifecycle":{"type":"object","properties":{"currentVersion":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["live"]},"compatibilityGuarantees":{"type":"array","items":{"type":"string"}},"compatibleChanges":{"type":"array","items":{"type":"string"}},"breakingChanges":{"type":"array","items":{"type":"string"}},"deprecationPolicy":{"type":"object"},"sunsetPolicy":{"type":"object"},"legacySupport":{"type":"object"},"betaBoundary":{"type":"string"}}},"rateLimits":{"type":"object","properties":{"status":{"type":"string","examples":["beta"]},"algorithm":{"type":"string","examples":["Sliding window backed by Upstash Redis or Vercel marketplace Redis aliases."]},"window":{"type":"string","examples":["60 seconds per organization, key, endpoint, and plan limit."]},"responseHeaders":{"type":"array","items":{"type":"string"}},"errorDetails":{"type":"array","items":{"type":"string"}},"planLimits":{"type":"array","items":{"type":"object"}}}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperExamplesResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","usage","cookbooks","endpointExamples","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"usage":{"type":"string"},"cookbooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["core-chart-compute","commerce-audience-intelligence","async-world-signals","dating-compatibility-stack"]},"title":{"type":"string"},"audience":{"type":"string"},"goal":{"type":"string"},"routes":{"type":"array","items":{"type":"string"}},"steps":{"type":"array","items":{"type":"string"}},"proof":{"type":"array","items":{"type":"string"}}}}},"endpointExamples":{"type":"array","items":{"type":"object"}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperSupportResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","supportStatus","contact","tiers","escalationPolicy","supportPacket","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"supportStatus":{"type":"string","examples":["public-intake-enterprise-contract-next"]},"contact":{"type":"string","examples":["mailto:partners@theleokingai.com"]},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperSupportTier"}},"escalationPolicy":{"type":"object","properties":{"status":{"type":"string","examples":["live"]},"publicContact":{"type":"string","examples":["mailto:partners@theleokingai.com"]},"enterpriseContact":{"type":"string"},"supportPacket":{"type":"array","items":{"type":"string"}},"neverInclude":{"type":"array","items":{"type":"string"}},"severityRouting":{"type":"array","items":{"type":"string"}},"escalationRules":{"type":"array","items":{"type":"string"}},"boundaries":{"type":"array","items":{"type":"string"}}}},"supportPacket":{"type":"object"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperSdksResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","packages","releasePolicy","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["release-gate"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperSdkPackage"}},"releasePolicy":{"type":"object","properties":{"status":{"type":"string","examples":["release_gate"]},"packagePublication":{"type":"string"},"generatedClients":{"type":"string"},"versioning":{"type":"string"},"releaseSmokeCommand":{"type":"string","examples":["npm run smoke:sdk-release -- --base-url https://api.theleokingai.com"]},"publicationDryRunCommand":{"type":"string","examples":["npm run smoke:sdk-publication -- --base-url https://api.theleokingai.com"]},"provenance":{"type":"string"},"releaseTagPolicy":{"type":"string"},"rollback":{"type":"string"},"requiredChecks":{"type":"array","items":{"type":"string"}},"rollout":{"type":"array","items":{"type":"string"}}}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperMigrationsResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","policy","lifecycle","guides","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"policy":{"type":"object","properties":{"status":{"type":"string","examples":["live"]},"compatibilitySource":{"type":"string","examples":["/api/v1/versioning"]},"breakingChangeNotice":{"type":"string"},"legacyAliasPolicy":{"type":"string"},"requiredMigrationArtifacts":{"type":"array","items":{"type":"string"}},"partnerChecklist":{"type":"array","items":{"type":"string"}}}},"lifecycle":{"type":"object"},"guides":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperMigrationGuide"}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperProcurementResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","packet","reviewItems","dataHandling","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"packet":{"type":"object","properties":{"status":{"type":"string","examples":["live"]},"publicContact":{"type":"string","examples":["mailto:partners@theleokingai.com"]},"intendedAudience":{"type":"array","items":{"type":"string"}},"buyerPacket":{"type":"array","items":{"type":"string"}},"securityReview":{"type":"array","items":{"type":"string"}},"legalReview":{"type":"array","items":{"type":"string"}},"operationalReview":{"type":"array","items":{"type":"string"}},"unavailableUntilSignedTerms":{"type":"array","items":{"type":"string"}},"requiredSignedArtifacts":{"type":"array","items":{"type":"string"}},"reviewBoundaries":{"type":"array","items":{"type":"string"}}}},"reviewItems":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperProcurementReviewItem"}},"dataHandling":{"type":"object"},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperConformanceResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","policy","checks","productionChecklist","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"policy":{"type":"object","properties":{"status":{"type":"string","examples":["live"]},"cadence":{"type":"array","items":{"type":"string"}},"requiredBefore":{"type":"array","items":{"type":"string"}},"launchGates":{"type":"array","items":{"type":"string"}},"partnerGuidance":{"type":"array","items":{"type":"string"}},"evidenceRetention":{"type":"string"}}},"checks":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperConformanceCheck"}},"productionChecklist":{"type":"array","items":{"type":"string"}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperDataProcessingResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","policy","purposes","dataSubjectRequests","retention","subprocessors","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"policy":{"type":"object","properties":{"status":{"type":"string","examples":["live"]},"publicContact":{"type":"string","examples":["mailto:partners@theleokingai.com"]},"scope":{"type":"string"},"dpaBoundary":{"type":"string"},"dataMinimization":{"type":"array","items":{"type":"string"}},"restrictedData":{"type":"array","items":{"type":"string"}},"regionalBoundary":{"type":"string"},"deletionBoundary":{"type":"string"},"exportBoundary":{"type":"string"}}},"purposes":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperDataProcessingPurpose"}},"dataSubjectRequests":{"type":"object","properties":{"status":{"type":"string","examples":["enterprise"]},"requestTypes":{"type":"array","items":{"type":"string"}},"partnerResponsibilities":{"type":"array","items":{"type":"string"}},"platformResponsibilities":{"type":"array","items":{"type":"string"}},"supportPacket":{"type":"array","items":{"type":"string"}},"exclusions":{"type":"array","items":{"type":"string"}}}},"retention":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperDataRetentionPolicy"}},"subprocessors":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperSubprocessor"}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperComplianceResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","policy","frameworkMappings","evidence","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"policy":{"type":"object","properties":{"status":{"type":"string","examples":["live"]},"publicContact":{"type":"string","examples":["mailto:partners@theleokingai.com"]},"scope":{"type":"string"},"noCertificationClaim":{"type":"string"},"mappedFrameworks":{"type":"array","items":{"type":"string"}},"currentEvidence":{"type":"array","items":{"type":"string"}},"requiresSignedTerms":{"type":"array","items":{"type":"string"}},"reviewerGuidance":{"type":"array","items":{"type":"string"}}}},"frameworkMappings":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperComplianceMapping"}},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperComplianceEvidenceItem"}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperAiGovernanceResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","policy","useCaseBoundaries","controls","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["public-contract"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"policy":{"type":"object","properties":{"status":{"type":"string","examples":["live"]},"publicContact":{"type":"string","examples":["mailto:partners@theleokingai.com"]},"scope":{"type":"string"},"acceptableUseBoundary":{"type":"string"},"outputQualityPolicy":{"type":"string"},"humanReviewBoundary":{"type":"string"},"modelTransparency":{"type":"string"},"prohibitedUses":{"type":"array","items":{"type":"string"}},"restrictedUses":{"type":"array","items":{"type":"string"}},"partnerResponsibilities":{"type":"array","items":{"type":"string"}},"escalationTriggers":{"type":"array","items":{"type":"string"}}}},"useCaseBoundaries":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperAiUseCaseBoundary"}},"controls":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperAiGovernanceControl"}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperChangelogResponse":{"type":"object","required":["name","version","contractVersion","lastReviewedAt","entries","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperChangelogEntry"}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperWebhooksResponse":{"type":"object","required":["name","version","status","contractVersion","lastReviewedAt","delivery","signature","events","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"status":{"type":"string","examples":["release-gate"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"delivery":{"type":"object"},"signature":{"type":"object"},"events":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperWebhookEvent"}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"DeveloperErrorCatalogEntry":{"type":"object","required":["httpStatus","code","summary","retryable","partnerAction","supportSignal"],"properties":{"httpStatus":{"type":"integer","enum":[400,401,402,403,404,409,429,502,503]},"code":{"type":"string","enum":["INVALID_REQUEST","AUTH_REQUIRED","AUTH_INVALID","CREDITS_EXHAUSTED","AUTH_FORBIDDEN","NOT_FOUND","IDEMPOTENCY_CONFLICT","RATE_LIMITED","INVALID_RESPONSE","UPSTREAM_FAILED","SERVER_MISCONFIGURED"]},"summary":{"type":"string"},"retryable":{"type":"boolean"},"partnerAction":{"type":"string"},"supportSignal":{"type":"string"}}},"DeveloperErrorsResponse":{"type":"object","required":["name","version","contractVersion","lastReviewedAt","envelope","errors","links"],"properties":{"name":{"type":"string"},"version":{"type":"string","examples":["v1"]},"contractVersion":{"type":"string","examples":["2026-07-09.enterprise-trust-paid-route-ci-gate-v1"]},"lastReviewedAt":{"type":"string","format":"date"},"envelope":{"type":"object"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/DeveloperErrorCatalogEntry"}},"links":{"type":"object","additionalProperties":{"type":"string"}}}},"PostmanCollectionResponse":{"type":"object","required":["info","variable","auth","item"],"properties":{"info":{"type":"object"},"variable":{"type":"array","items":{"type":"object"}},"auth":{"type":"object"},"item":{"type":"array","items":{"type":"object"}}}},"ApiUsage":{"type":"object","required":["lane","credits"],"properties":{"lane":{"type":"string","enum":["core","ai","ops"],"description":"Billing lane for the request. Core routes do not call AI; AI routes may include model token usage."},"credits":{"type":"number"},"billableUnits":{"type":"number"},"tokens":{"type":"object","properties":{"input":{"type":"number"},"output":{"type":"number"},"total":{"type":"number"}}}}},"ErrorEnvelope":{"type":"object","required":["request_id","error"],"properties":{"request_id":{"type":"string"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","examples":["INVALID_REQUEST","AUTH_REQUIRED","CREDITS_EXHAUSTED"]},"message":{"type":"string"},"details":{"type":"object"}}}}},"CustomerProfileRequest":{"type":"object","required":["customers"],"properties":{"customers":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["id","dob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date"},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}}}},"campaign_context":{"type":"object","properties":{"product_category":{"type":"string","maxLength":120},"tone":{"type":"string","maxLength":120},"channel":{"type":"string","maxLength":80}}}}},"CustomerProfileResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"type":"object","required":["customer_id","personality","campaign_fit"],"properties":{"customer_id":{"type":"string"},"personality":{"type":"object","required":["sun_sign","buyer_archetype","motivations","communication_style"],"properties":{"sun_sign":{"type":"string"},"buyer_archetype":{"type":"string"},"motivations":{"type":"array","items":{"type":"string"}},"communication_style":{"type":"string"}}},"campaign_fit":{"type":"object","required":["score","send","reasoning"],"properties":{"score":{"type":"number","minimum":0,"maximum":1},"send":{"type":"boolean"},"reasoning":{"type":"string"},"suggested_tone_adjustment":{"type":["string","null"]},"optimal_send_time":{"type":["string","null"]}}}}}}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"MundaneForecastRequest":{"type":"object","properties":{"topic":{"type":"string","enum":["markets","politics","climate","tech","culture","spirituality","all"],"default":"all"},"window_days":{"type":"integer","minimum":1,"maximum":90,"default":14},"depth":{"type":"string","enum":["surface","moderate","deep","rabbit_hole"],"default":"moderate"}}},"MundaneForecastResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["forecasts"],"properties":{"forecasts":{"type":"array","items":{"type":"object","required":["headline","signature_stack","historical_analog","themes","manifestations","forecast_window","confidence","empowerment"],"properties":{"headline":{"type":"string"},"signature_stack":{"type":"object","required":["primary","secondary","outer_planet_context"],"description":"Deterministic verified signature class selected by the API after model generation; can come from live Kerykeion transit ephemeris when configured.","properties":{"primary":{"type":"string"},"secondary":{"type":"array","items":{"type":"string"}},"outer_planet_context":{"type":"string"}}},"historical_analog":{"type":"object","required":["date_range","events"],"properties":{"date_range":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}},"description":"Deterministic verified analog class selected by the API after model generation."},"themes":{"type":"array","items":{"type":"string"}},"manifestations":{"type":"array","items":{"type":"object","required":["category","description"],"properties":{"category":{"type":"string"},"description":{"type":"string"}}}},"forecast_window":{"type":"object","required":["start","end","specificity"],"properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"specificity":{"type":"string"}}},"confidence":{"type":"number","minimum":1,"maximum":10},"empowerment":{"type":"string"}}}}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object","properties":{"signatureStack":{"type":"object","properties":{"catalogVersion":{"type":"string"},"selected":{"type":"object"},"candidateIds":{"type":"array","items":{"type":"string"}}}},"btvArticleRag":{"type":"object","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["off","auto","local"]},"corpusCount":{"type":"integer","minimum":0},"chunkCount":{"type":"integer","minimum":0},"citations":{"type":"array","items":{"type":"object"}},"warnings":{"type":"array","items":{"type":"string"}}}},"ephemeris":{"type":"object","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["off","auto","required"]},"source":{"type":"string"},"generatedAt":{"type":"string"},"selectedSignatureId":{"type":"string"},"positions":{"type":"array","items":{"type":"string"}},"aspects":{"type":"array","items":{"type":"string"}},"warnings":{"type":"array","items":{"type":"string"}}}},"historicalAnalog":{"type":"object","properties":{"catalogVersion":{"type":"string"},"selected":{"type":"object"},"candidateIds":{"type":"array","items":{"type":"string"}}}},"qualityControls":{"type":"object","properties":{"signatureStackDateClaimsRemoved":{"type":"integer","minimum":0}}}}}}},"WorldSignalJobCreateResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["job_id","status","endpoint","status_url","reserved_credits","charged_credits","poll_after_ms","created_at","updated_at"],"properties":{"job_id":{"type":"string"},"status":{"type":"string","enum":["queued","running","complete","failed"]},"endpoint":{"type":"string","examples":["/api/v1/world/signals"]},"status_url":{"type":"string","format":"uri"},"reserved_credits":{"type":"number"},"charged_credits":{"type":"number"},"poll_after_ms":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"WorldSignalJobStatusResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["job_id","status","endpoint","status_url","reserved_credits","charged_credits","created_at","updated_at"],"properties":{"job_id":{"type":"string"},"status":{"type":"string","enum":["queued","running","complete","failed"]},"endpoint":{"type":"string","examples":["/api/v1/world/signals"]},"status_url":{"type":"string","format":"uri"},"reserved_credits":{"type":"number"},"charged_credits":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":"string","format":"date-time"},"result":{"$ref":"#/components/schemas/MundaneForecastResponse"},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"HelioPatternRequest":{"type":"object","required":["subjects"],"properties":{"subjects":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["id","dob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","description":"Accepted for caller context only. The current StarTypes short lookup is date-level and does not use birth time.","examples":["14:30"]}}}},"context":{"type":"object","properties":{"use_case":{"type":"string","maxLength":120},"notes":{"type":"string","maxLength":500}}}}},"HelioPatternResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["profiles","lookup"],"properties":{"profiles":{"type":"array","items":{"type":"object","required":["subject_id","birth_date","calculation_basis","startype","interpretation","source"],"properties":{"subject_id":{"type":"string"},"birth_date":{"type":"string","format":"date"},"calculation_basis":{"type":"object","required":["frame","zodiac","system","origin","precision","location_used","birth_time_used","prediction_role","exclusions"],"properties":{"frame":{"type":"string","enum":["heliocentric"]},"zodiac":{"type":"string","enum":["tropical"]},"system":{"type":"string","enum":["StarTypes"]},"origin":{"type":"string"},"precision":{"type":"string","enum":["date_level_short_ephemeris"]},"location_used":{"type":"boolean","enum":[false]},"birth_time_used":{"type":"boolean","enum":[false]},"prediction_role":{"type":"string","enum":["background_evaluation"]},"exclusions":{"type":"array","items":{"type":"string"}}}},"startype":{"type":"object","required":["combo","ephemeris","pattern_code","pattern_signature","components"],"properties":{"combo":{"type":"string"},"ephemeris":{"type":"string"},"pattern_code":{"type":"string"},"pattern_signature":{"type":"string"},"components":{"type":"array","items":{"type":"object","required":["code","color","geometry"],"properties":{"code":{"type":"string"},"color":{"type":"string"},"geometry":{"type":"string"}}}}}},"interpretation":{"type":"object","required":["summary","best_uses","guardrails"],"properties":{"summary":{"type":"string"},"best_uses":{"type":"array","items":{"type":"string"}},"guardrails":{"type":"array","items":{"type":"string"}}}},"source":{"type":"object","required":["title","system","creditLine"],"properties":{"title":{"type":"string"},"system":{"type":"string"},"creditLine":{"type":"string"},"rightsBucket":{"type":"string"},"rowNumber":{"type":"number"}}}}}},"lookup":{"type":"object","required":["coverage","source","mode"],"properties":{"coverage":{"type":"object","required":["start","end","recordCount"],"properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"},"recordCount":{"type":"number"}}},"source":{"type":"string"},"mode":{"type":"string","enum":["structured_lookup"]}}}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"WesternCalculationOptions":{"type":"object","properties":{"house_system":{"type":"string","enum":["placidus","koch","equal","whole_sign","regiomontanus","campanus","porphyry"],"default":"placidus"},"zodiac":{"type":"string","enum":["tropical"],"default":"tropical"},"active_points":{"type":"array","minItems":1,"maxItems":14,"items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","north_node","ascendant","midheaven"]}}}},"NatalChartRequest":{"type":"object","required":["subject"],"properties":{"subject":{"type":"object","required":["id","dob","tob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120,"examples":["America/New_York"]},"timezone_offset_minutes":{"type":"integer","minimum":-840,"maximum":840}},"description":"Full chart routes require time of birth plus place of birth or coordinates."},"options":{"type":"object","properties":{"house_system":{"type":"string","enum":["placidus","koch","equal","whole_sign","regiomontanus","campanus","porphyry"],"default":"placidus"},"zodiac":{"type":"string","enum":["tropical"],"default":"tropical"},"active_points":{"type":"array","minItems":1,"maxItems":14,"items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","north_node","ascendant","midheaven"]}}}}}},"NatalChartResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["subject_id","calculation_basis","chart"],"properties":{"subject_id":{"type":"string"},"calculation_basis":{"type":"object","properties":{"provider":{"type":"string","enum":["owned_western"]},"frame":{"type":"string","enum":["geocentric"]},"zodiac":{"type":"string","enum":["tropical"]},"system":{"type":"string","examples":["The Leo King owned western astrology sidecar"]},"source":{"type":"string"},"house_system":{"type":"string"},"birth_time_used":{"type":"boolean"},"location_used":{"type":"boolean"},"third_party_astrology_api_used":{"type":"boolean","enum":[false]}}},"provider":{"type":"string","enum":["owned_western"]},"supported_lanes":{"type":"array","items":{"type":"string"}},"unsupported_lanes":{"type":"array","items":{"type":"string"}},"sun_sign":{"type":["string","null"]},"chart":{"type":"object","description":"Raw sidecar chart payload. Planet, house, and aspect fields depend on the configured sidecar response."}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"TransitChartRequest":{"type":"object","required":["transit_datetime"],"properties":{"transit_datetime":{"type":"string","format":"date-time","examples":["2026-06-17T12:00:00.000Z"]},"subject":{"type":"object","required":["id","dob","tob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120,"examples":["America/New_York"]},"timezone_offset_minutes":{"type":"integer","minimum":-840,"maximum":840}},"description":"Full chart routes require time of birth plus place of birth or coordinates."},"transit_location":{"type":"string","maxLength":200,"default":"Greenwich, GB"},"max_aspects":{"type":"integer","minimum":1,"maximum":100,"default":30},"options":{"type":"object","properties":{"house_system":{"type":"string","enum":["placidus","koch","equal","whole_sign","regiomontanus","campanus","porphyry"],"default":"placidus"},"zodiac":{"type":"string","enum":["tropical"],"default":"tropical"},"active_points":{"type":"array","minItems":1,"maxItems":14,"items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","north_node","ascendant","midheaven"]}}}}}},"TransitChartResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["transit_datetime","transit_location","calculation_basis","chart","aspects"],"properties":{"transit_datetime":{"type":"string","format":"date-time"},"transit_location":{"type":"string"},"subject_id":{"type":"string"},"calculation_basis":{"type":"object","properties":{"provider":{"type":"string","enum":["owned_western"]},"frame":{"type":"string","enum":["geocentric"]},"zodiac":{"type":"string","enum":["tropical"]},"system":{"type":"string","examples":["The Leo King owned western astrology sidecar"]},"source":{"type":"string"},"house_system":{"type":"string"},"birth_time_used":{"type":"boolean"},"location_used":{"type":"boolean"},"third_party_astrology_api_used":{"type":"boolean","enum":[false]}}},"provider":{"type":"string","enum":["owned_western"]},"supported_lanes":{"type":"array","items":{"type":"string"}},"unsupported_lanes":{"type":"array","items":{"type":"string"}},"natal_chart":{"type":"object"},"chart":{"type":"object","description":"Raw sidecar transit chart payload."},"aspects":{"type":"array","items":{"type":"object"}},"lunar_phase":{"type":"object"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"SynastryChartRequest":{"type":"object","required":["subject","partner"],"properties":{"subject":{"type":"object","required":["id","dob","tob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120,"examples":["America/New_York"]},"timezone_offset_minutes":{"type":"integer","minimum":-840,"maximum":840}},"description":"Full chart routes require time of birth plus place of birth or coordinates."},"partner":{"type":"object","required":["id","dob","tob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120,"examples":["America/New_York"]},"timezone_offset_minutes":{"type":"integer","minimum":-840,"maximum":840}},"description":"Full chart routes require time of birth plus place of birth or coordinates."},"max_aspects":{"type":"integer","minimum":1,"maximum":120,"default":40},"options":{"type":"object","properties":{"house_system":{"type":"string","enum":["placidus","koch","equal","whole_sign","regiomontanus","campanus","porphyry"],"default":"placidus"},"zodiac":{"type":"string","enum":["tropical"],"default":"tropical"},"active_points":{"type":"array","minItems":1,"maxItems":14,"items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","north_node","ascendant","midheaven"]}}}}}},"SynastryChartResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["pair_id","calculation_basis","aspects","relationship_signals"],"properties":{"pair_id":{"type":"string"},"subject_id":{"type":"string"},"partner_id":{"type":"string"},"calculation_basis":{"type":"object","properties":{"provider":{"type":"string","enum":["owned_western"]},"frame":{"type":"string","enum":["geocentric"]},"zodiac":{"type":"string","enum":["tropical"]},"system":{"type":"string","examples":["The Leo King owned western astrology sidecar"]},"source":{"type":"string"},"house_system":{"type":"string"},"birth_time_used":{"type":"boolean"},"location_used":{"type":"boolean"},"third_party_astrology_api_used":{"type":"boolean","enum":[false]}}},"provider":{"type":"string","enum":["owned_western"]},"supported_lanes":{"type":"array","items":{"type":"string"}},"unsupported_lanes":{"type":"array","items":{"type":"string"}},"subject_chart":{"type":"object"},"partner_chart":{"type":"object"},"aspects":{"type":"array","items":{"type":"object"}},"relationship_signals":{"type":"array","items":{"type":"object"}}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"CurrentSkyRequest":{"type":"object","properties":{"datetime":{"type":"string","format":"date-time","examples":["2026-06-17T12:00:00.000Z"]},"location":{"type":"string","maxLength":200,"default":"Greenwich, GB"},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120},"options":{"type":"object","properties":{"house_system":{"type":"string","enum":["placidus","koch","equal","whole_sign","regiomontanus","campanus","porphyry"],"default":"placidus"},"zodiac":{"type":"string","enum":["tropical"],"default":"tropical"},"active_points":{"type":"array","minItems":1,"maxItems":14,"items":{"type":"string","enum":["sun","moon","mercury","venus","mars","jupiter","saturn","uranus","neptune","pluto","chiron","north_node","ascendant","midheaven"]}}}}}},"CurrentSkyResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["datetime","calculation_basis","chart"],"properties":{"datetime":{"type":"string","format":"date-time"},"location":{"type":"string"},"calculation_basis":{"type":"object","properties":{"provider":{"type":"string","enum":["owned_western"]},"frame":{"type":"string","enum":["geocentric"]},"zodiac":{"type":"string","enum":["tropical"]},"system":{"type":"string","examples":["The Leo King owned western astrology sidecar"]},"source":{"type":"string"},"house_system":{"type":"string"},"birth_time_used":{"type":"boolean"},"location_used":{"type":"boolean"},"third_party_astrology_api_used":{"type":"boolean","enum":[false]}}},"provider":{"type":"string","enum":["owned_western"]},"supported_lanes":{"type":"array","items":{"type":"string"}},"unsupported_lanes":{"type":"array","items":{"type":"string"}},"chart":{"type":"object"},"lunar_phase":{"type":"object"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"LunarPhaseRequest":{"$ref":"#/components/schemas/CurrentSkyRequest"},"LunarPhaseResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["datetime","calculation_basis","lunar_phase"],"properties":{"datetime":{"type":"string","format":"date-time"},"location":{"type":"string"},"calculation_basis":{"type":"object","properties":{"provider":{"type":"string","enum":["owned_western"]},"frame":{"type":"string","enum":["geocentric"]},"zodiac":{"type":"string","enum":["tropical"]},"system":{"type":"string","examples":["The Leo King owned western astrology sidecar"]},"source":{"type":"string"},"house_system":{"type":"string"},"birth_time_used":{"type":"boolean"},"location_used":{"type":"boolean"},"third_party_astrology_api_used":{"type":"boolean","enum":[false]}}},"provider":{"type":"string","enum":["owned_western"]},"supported_lanes":{"type":"array","items":{"type":"string"}},"unsupported_lanes":{"type":"array","items":{"type":"string"}},"lunar_phase":{"type":"object"},"chart":{"type":"object"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"CompatibilityScoreRequest":{"allOf":[{"$ref":"#/components/schemas/SynastryChartRequest"},{"type":"object","properties":{"context":{"type":"object"},"scoring_profile":{"type":"string","enum":["balanced","romantic","long_term","chemistry"],"default":"balanced"},"include_helio_background":{"type":"boolean","default":false}}}]},"CompatibilityScoreResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["pair_id","score","tier","subscores","strengths","risk_flags"],"properties":{"pair_id":{"type":"string"},"subject_id":{"type":"string"},"partner_id":{"type":"string"},"calculation_basis":{"type":"object","properties":{"frame":{"type":"string","enum":["geocentric"]},"zodiac":{"type":"string","enum":["tropical"]},"system":{"type":"string","examples":["Kerykeion sidecar + deterministic compatibility scorer"]},"source":{"type":"string"}}},"score":{"type":"integer","minimum":0,"maximum":100},"tier":{"type":"string","enum":["low","mixed","strong","exceptional"]},"subscores":{"type":"object"},"strengths":{"type":"array","items":{"type":"string"}},"risk_flags":{"type":"array","items":{"type":"string"}},"aspect_highlights":{"type":"array","items":{"type":"object"}},"framework_notes":{"type":"object"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"FuturePartnerVisionRequest":{"type":"object","required":["subject"],"properties":{"subject":{"type":"object","required":["id","dob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120,"examples":["America/New_York"]},"timezone_offset_minutes":{"type":"integer","minimum":-840,"maximum":840}},"description":"Full chart routes require time of birth plus place of birth or coordinates."},"intent":{"type":"string","default":"future long-term partner"},"context":{"type":"object"},"include_image_prompt":{"type":"boolean","default":true}}},"FuturePartnerVisionResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["partner_archetype","relationship_signature","meeting_scene","timing_windows","next_action"],"properties":{"partner_archetype":{"type":"string"},"relationship_signature":{"type":"object"},"meeting_scene":{"type":"object"},"timing_windows":{"type":"array","items":{"type":"object"}},"next_action":{"type":"string"},"image_prompt":{"type":["string","null"]}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"LoveRevealRequest":{"type":"object","required":["question"],"properties":{"question":{"type":"string","maxLength":1200},"subject":{"type":"object","required":["id","dob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120,"examples":["America/New_York"]},"timezone_offset_minutes":{"type":"integer","minimum":-840,"maximum":840}},"description":"Full chart routes require time of birth plus place of birth or coordinates."},"partner":{"type":"object","required":["id","dob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120,"examples":["America/New_York"]},"timezone_offset_minutes":{"type":"integer","minimum":-840,"maximum":840}},"description":"Full chart routes require time of birth plus place of birth or coordinates."},"context":{"type":"object"},"include_tarot_symbols":{"type":"boolean","default":true}}},"LoveRevealResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["answer","dynamic","evidence","next_action","boundary"],"properties":{"answer":{"type":"string"},"dynamic":{"type":"string"},"evidence":{"type":"object"},"next_action":{"type":"string"},"boundary":{"type":"string"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"CrystalBallVisionRequest":{"type":"object","required":["question"],"properties":{"question":{"type":"string","maxLength":1200},"topic":{"type":"string","enum":["love","career","money","spirituality","family","timing","general"],"default":"general"},"subject":{"type":"object","required":["id","dob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120,"examples":["America/New_York"]},"timezone_offset_minutes":{"type":"integer","minimum":-840,"maximum":840}},"description":"Full chart routes require time of birth plus place of birth or coordinates."},"style":{"type":"string","default":"cinematic, grounded, direct"},"generate_image_prompt":{"type":"boolean","default":true}}},"CrystalBallVisionResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["vision","symbols","interpretation","action"],"properties":{"vision":{"type":"string"},"symbols":{"type":"array","items":{"type":"object"}},"interpretation":{"type":"string"},"action":{"type":"string"},"image_prompt":{"type":["string","null"]}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"OracleAskRequest":{"type":"object","required":["question"],"properties":{"question":{"type":"string","maxLength":1200},"birth_date":{"type":"string","format":"date"},"topic":{"type":"string","enum":["love","career","money","spirituality","timing","family","general"],"default":"general"},"context":{"type":"object"}}},"OracleAskResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["answer","insight","support","next_action","caution"],"properties":{"answer":{"type":"string"},"insight":{"type":"string"},"support":{"type":"array","items":{"type":"string"}},"next_action":{"type":"string"},"caution":{"type":"string"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"TarotDrawRequest":{"type":"object","required":["question"],"properties":{"question":{"type":"string","maxLength":1200},"spread_type":{"type":"string","enum":["single","three_card","past_present_future","celtic_cross"],"default":"three_card"},"topic":{"type":"string","enum":["love","career","money","spirituality","timing","general"],"default":"general"},"seed":{"type":"string"},"include_image_prompt":{"type":"boolean","default":false}}},"TarotDrawResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["spread","answer","card_readings","synthesis","next_action"],"properties":{"spread":{"type":"object"},"answer":{"type":"string"},"card_readings":{"type":"array","items":{"type":"object"}},"synthesis":{"type":"string"},"next_action":{"type":"string"},"image_prompt":{"type":["string","null"]}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"DailyHoroscopeRequest":{"type":"object","properties":{"sign":{"type":"string","enum":["aries","taurus","gemini","cancer","leo","virgo","libra","scorpio","sagittarius","capricorn","aquarius","pisces"]},"subject":{"type":"object","required":["id","dob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120,"examples":["America/New_York"]},"timezone_offset_minutes":{"type":"integer","minimum":-840,"maximum":840}},"description":"Full chart routes require time of birth plus place of birth or coordinates."},"date":{"type":"string","format":"date"},"tone":{"type":"string"},"sections":{"type":"array","items":{"type":"string","enum":["theme","love","work","money","spiritual","action"]}}}},"DailyHoroscopeResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["sign","date","theme","drivers","sections","action"],"properties":{"sign":{"type":"string"},"date":{"type":"string","format":"date"},"theme":{"type":"string"},"drivers":{"type":"array","items":{"type":"string"}},"sections":{"type":"object"},"action":{"type":"string"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"PastLifeReadingRequest":{"type":"object","properties":{"subject":{"type":"object","required":["id","dob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120,"examples":["America/New_York"]},"timezone_offset_minutes":{"type":"integer","minimum":-840,"maximum":840}},"description":"Full chart routes require time of birth plus place of birth or coordinates."},"question":{"type":"string","maxLength":1200},"focus":{"type":"string","enum":["relationship","career","family","spiritual_gift","fear_pattern","soul_mission","general"],"default":"general"},"depth":{"type":"string","enum":["summary","full"],"default":"summary"}}},"PastLifeReadingResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["lifetime_theme","scene","karmic_pattern","present_life_echo","healing_action","empowerment"],"properties":{"lifetime_theme":{"type":"string"},"scene":{"type":"object"},"karmic_pattern":{"type":"string"},"present_life_echo":{"type":"string"},"healing_action":{"type":"string"},"empowerment":{"type":"string"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"TimingWindowsRequest":{"type":"object","properties":{"subject":{"type":"object","required":["id","dob"],"properties":{"id":{"type":"string","maxLength":120},"dob":{"type":"string","format":"date","examples":["1990-07-23"]},"tob":{"type":"string","pattern":"^\\d{2}:\\d{2}$","examples":["14:30"]},"pob":{"type":"string","maxLength":200,"examples":["New York, US"]},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"timezone_name":{"type":"string","maxLength":120,"examples":["America/New_York"]},"timezone_offset_minutes":{"type":"integer","minimum":-840,"maximum":840}},"description":"Full chart routes require time of birth plus place of birth or coordinates."},"topic":{"type":"string","enum":["love","career","money","launch","content","spirituality","general"],"default":"general"},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"objective":{"type":"string","maxLength":500},"max_windows":{"type":"integer","minimum":1,"maximum":5,"default":3}}},"TimingWindowsResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["topic","windows","strategy"],"properties":{"topic":{"type":"string"},"windows":{"type":"array","items":{"type":"object"}},"strategy":{"type":"string"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"MundaneHotZonesRequest":{"type":"object","properties":{"topic":{"type":"string","enum":["markets","politics","climate","tech","culture","spirituality","all"],"default":"all"},"regions":{"type":"array","items":{"type":"string"}},"window_days":{"type":"integer","minimum":1,"maximum":90,"default":30},"depth":{"type":"string","enum":["surface","moderate","deep"],"default":"moderate"}}},"MundaneHotZonesResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["topic","window","hot_zones","synthesis"],"properties":{"topic":{"type":"string"},"window":{"type":"object"},"hot_zones":{"type":"array","items":{"type":"object"}},"synthesis":{"type":"string"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}},"MundaneEventAnalysisRequest":{"type":"object","required":["event"],"properties":{"event":{"type":"string","maxLength":1600},"event_date":{"type":"string","format":"date"},"location":{"type":"string"},"topic":{"type":"string","enum":["markets","politics","climate","tech","culture","spirituality","all"],"default":"all"},"window_days":{"type":"integer","minimum":1,"maximum":90,"default":30}}},"MundaneEventAnalysisResponse":{"type":"object","required":["request_id","data","usage","meta"],"properties":{"request_id":{"type":"string"},"data":{"type":"object","required":["event_summary","signature_stack","analogs","forecast_implications","watch_window","confidence","action"],"properties":{"event_summary":{"type":"string"},"signature_stack":{"type":"array","items":{"type":"string"}},"analogs":{"type":"array","items":{"type":"string"}},"forecast_implications":{"type":"array","items":{"type":"string"}},"watch_window":{"type":"object"},"confidence":{"type":"number","minimum":1,"maximum":10},"action":{"type":"string"}}},"usage":{"$ref":"#/components/schemas/ApiUsage"},"meta":{"type":"object"}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/v1/status":{"get":{"tags":["Developer Metadata"],"summary":"Get public API platform status","description":"Public developer status surface for discovery, integration review, and enterprise readiness planning. Deep readiness remains internal and requires ops auth.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperStatusResponse"}}}}},"operationId":"getV1Status"}},"/v1/sla":{"get":{"tags":["Developer Metadata"],"summary":"Get public API SLA targets","description":"Public SLA target and support-boundary contract for partner review. Contractual enterprise SLA terms require signed customer terms and dedicated monitoring.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperSlaResponse"}}}}},"operationId":"getV1Sla"}},"/v1/incidents":{"get":{"tags":["Developer Metadata"],"summary":"Get public API incident history","description":"Public incident-history surface and reporting policy for partner-impacting production incidents, quality regressions, and planned maintenance.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperIncidentsResponse"}}}}},"operationId":"getV1Incidents"}},"/v1/security":{"get":{"tags":["Developer Metadata"],"summary":"Get the public API security packet","description":"Public security, trust, data handling, subprocessor, and enterprise-review metadata for partner procurement and integration review.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperSecurityResponse"}}}}},"operationId":"getV1Security"}},"/v1/access-control":{"get":{"tags":["Developer Metadata"],"summary":"Get public API access-control policy","description":"Public API-key custody, endpoint scope, environment boundary, rotation, revocation, browser/CORS, support evidence, and enterprise allowlist policy.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperAccessControlResponse"}}}}},"operationId":"getV1AccessControl"}},"/v1/observability":{"get":{"tags":["Developer Metadata"],"summary":"Get public API observability proof","description":"Public production proof contract covering env gates, gateway smoke, buyer-path usage proof, readiness boundaries, and AI output quality sampling.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperObservabilityResponse"}}}}},"operationId":"getV1Observability"}},"/v1/onboarding":{"get":{"tags":["Developer Metadata"],"summary":"Get public API onboarding steps","description":"Public onboarding path from dedicated gateway base URL and server-side key setup through first request, retry handling, usage proof, launch-readiness gates, handoff artifacts, and enterprise escalation.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperOnboardingResponse"}}}}},"operationId":"getV1Onboarding"}},"/v1/versioning":{"get":{"tags":["Developer Metadata"],"summary":"Get public API versioning and limits policy","description":"Public lifecycle, compatibility, deprecation, sunset, and rate-limit policy for partners integrating with v1.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperVersioningResponse"}}}}},"operationId":"getV1Versioning"}},"/v1/examples":{"get":{"tags":["Developer Metadata"],"summary":"Get public API examples and cookbooks","description":"Public request/response examples, SDK snippets, and partner integration cookbooks generated from the documented endpoint catalog.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperExamplesResponse"}}}}},"operationId":"getV1Examples"}},"/v1/support":{"get":{"tags":["Developer Metadata"],"summary":"Get public API support and escalation policy","description":"Public support tier, support packet, severity routing, secret-handling, and enterprise escalation boundary contract for partner integration review.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperSupportResponse"}}}}},"operationId":"getV1Support"}},"/v1/sdks":{"get":{"tags":["Developer Metadata"],"summary":"Get public API SDK package readiness metadata","description":"Public SDK package names, source paths, install commands, helper surfaces, generated-client policy, and release gates.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperSdksResponse"}}}}},"operationId":"getV1Sdks"}},"/v1/migrations":{"get":{"tags":["Developer Metadata"],"summary":"Get public API migration and deprecation guides","description":"Public migration policy, required deprecation artifacts, legacy alias policy, route migration guides, and validation checklists.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperMigrationsResponse"}}}}},"operationId":"getV1Migrations"}},"/v1/procurement":{"get":{"tags":["Developer Metadata"],"summary":"Get public API procurement packet","description":"Public procurement and compliance-review packet with buyer evidence, security/legal/ops review boundaries, signed-term gates, and trust links.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperProcurementResponse"}}}}},"operationId":"getV1Procurement"}},"/v1/conformance":{"get":{"tags":["Developer Metadata"],"summary":"Get public API conformance and smoke contract","description":"Public conformance suites, smoke commands, pass criteria, launch gates, and evidence artifacts for partner and production readiness.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperConformanceResponse"}}}}},"operationId":"getV1Conformance"}},"/v1/data-processing":{"get":{"tags":["Developer Metadata"],"summary":"Get public API data-processing packet","description":"Public data-processing purposes, minimization rules, restricted-data boundaries, data-subject request support policy, retention, subprocessors, and signed-DPA gates.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperDataProcessingResponse"}}}}},"operationId":"getV1DataProcessing"}},"/v1/compliance":{"get":{"tags":["Developer Metadata"],"summary":"Get public API compliance-readiness map","description":"Public compliance-readiness mapping across common enterprise review areas, current evidence artifacts, certification boundaries, and signed-term gates.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperComplianceResponse"}}}}},"operationId":"getV1Compliance"}},"/v1/ai-governance":{"get":{"tags":["Developer Metadata"],"summary":"Get public API AI governance and acceptable-use packet","description":"Public acceptable-use boundaries, prohibited and restricted use cases, output-quality controls, human-review requirements, and escalation triggers for model-backed routes.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperAiGovernanceResponse"}}}}},"operationId":"getV1AiGovernance"}},"/v1/changelog":{"get":{"tags":["Developer Metadata"],"summary":"Get the public API changelog","description":"Public version and release notes for the developer platform, including current docs/discovery work and next enterprise gates.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperChangelogResponse"}}}}},"operationId":"getV1Changelog"}},"/v1/webhooks":{"get":{"tags":["Developer Metadata"],"summary":"Get the partner webhook contract","description":"Public release-gate contract for signed partner callbacks. The internal delivery worker exists behind ops auth; partner-facing activation still requires approved endpoint configuration and production smoke.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperWebhooksResponse"}}}}},"operationId":"getV1Webhooks"}},"/v1/errors":{"get":{"tags":["Developer Metadata"],"summary":"Get the public API error catalog","description":"Support-grade catalog of API error codes, retry guidance, partner actions, and escalation signals.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeveloperErrorsResponse"}}}}},"operationId":"getV1Errors"}},"/v1/postman":{"get":{"tags":["Developer Metadata"],"summary":"Get an importable Postman collection","description":"Public Postman Collection v2.1 asset generated from the documented v1 endpoint catalog. Set the apiKey collection variable before calling paid routes.","security":[],"responses":{"200":{"description":"Public developer metadata response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostmanCollectionResponse"}}}}},"operationId":"getV1Postman"}},"/v1/audience/insights":{"post":{"summary":"Generate audience insight and campaign-fit scoring","description":"Business-facing customer intelligence from birth data. Charges credits only after successful generation. An Idempotency-Key is required to prevent duplicate usage records.","x-tool-functions":["customer.profile.score","campaign.fit.evaluate","message.angle.generate","chart.quality.report","erlewine.context.attach"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerProfileRequest"},"examples":{"retailEmail":{"value":{"customers":[{"id":"cust_123","dob":"1990-07-23","tob":"14:30","pob":"New York, US"}],"campaign_context":{"product_category":"relationship coaching membership","tone":"warm direct","channel":"email"}}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerProfileResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1AudienceInsights"}},"/v1/experiences/future-partner-vision":{"post":{"summary":"Generate a paid future partner vision","description":"AI experience endpoint for partner apps. Charges 8 credits only after a structured JSON vision passes the response contract.","x-tool-functions":["partner.vision.generate","love.signature.extract","timing.romance.window","image.prompt.partner","quality.experience.enforce"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturePartnerVisionRequest"},"examples":{"default":{"value":{"subject":{"id":"user_123","dob":"1990-07-23","tob":"14:30","pob":"New York, US"},"intent":"future long-term partner","context":{"relationship_status":"single","desired_tone":"direct, cinematic, grounded"},"include_image_prompt":true}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturePartnerVisionResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1ExperiencesFuturePartnerVision"}},"/v1/experiences/love-reveal":{"post":{"summary":"Generate a paid love reveal","description":"AI experience endpoint for a specific relationship question. Charges 5 credits and returns structured evidence plus the next action.","x-tool-functions":["love.reveal.generate","question.intent.classify","tarot.symbols.attach","relationship.context.ground","quality.experience.enforce"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoveRevealRequest"},"examples":{"default":{"value":{"question":"Is this connection coming back or should I move on?","subject":{"id":"user_123","dob":"1990-07-23"},"context":{"relationship_status":"separated","desired_tone":"clear and compassionate"},"include_tarot_symbols":true}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoveRevealResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1ExperiencesLoveReveal"}},"/v1/experiences/crystal-ball":{"post":{"summary":"Generate a paid crystal ball vision","description":"AI experience endpoint for a cinematic symbolic vision with concrete interpretation and optional image-generation prompt.","x-tool-functions":["vision.crystal.generate","symbols.interpret","image.prompt.crystal","quality.experience.enforce"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrystalBallVisionRequest"},"examples":{"default":{"value":{"question":"What is the hidden opportunity around this career change?","topic":"career","style":"cinematic, concise, grounded","generate_image_prompt":true}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrystalBallVisionResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1ExperiencesCrystalBall"}},"/v1/oracle/ask":{"post":{"summary":"Generate a paid oracle answer","description":"Lady Avalon oracle answer with strict JSON, metered auth, and no legacy MCP dependency.","x-tool-functions":["oracle.ask.generate","sun.sign.derive","quality.experience.enforce"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OracleAskRequest"},"examples":{"default":{"value":{"question":"What is the real opportunity in front of me right now?","birth_date":"1990-07-23","topic":"career","context":{"desired_tone":"direct and grounded"}}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OracleAskResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1OracleAsk"}},"/v1/tarot/draw":{"post":{"summary":"Draw and interpret a tarot spread","description":"Draws cards from the local 78-card tarot corpus, locks the response to the drawn cards, and returns a structured interpretation.","x-tool-functions":["tarot.spread.draw","tarot.meanings.apply","tarot.output.lock"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TarotDrawRequest"},"examples":{"default":{"value":{"question":"What do I need to know about this relationship?","spread_type":"three_card","topic":"love","seed":"partner-reading-001"}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TarotDrawResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1TarotDraw"}},"/v1/past-life/reading":{"post":{"summary":"Generate a paid past-life reading","description":"AstraGate-style past-life reading with scene, karmic pattern, present-life echo, healing action, and empowerment.","x-tool-functions":["pastlife.reading.generate","astragate.persona.apply","quality.experience.enforce"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PastLifeReadingRequest"},"examples":{"default":{"value":{"subject":{"id":"user_123","dob":"1990-07-23"},"focus":"soul_mission","question":"What old pattern am I here to complete?"}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PastLifeReadingResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1PastLifeReading"}},"/v1/charts/natal":{"post":{"summary":"Calculate a geocentric tropical natal chart","description":"Returns raw natal chart data from the owned western sidecar. This is the geocentric tropical chart layer, not the heliocentric StarTypes layer, and it does not call AstrologyAPI.","x-tool-functions":["chart.natal.calculate","planet.positions.list","houses.resolve","aspects.list","birth.input.validate"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NatalChartRequest"},"examples":{"fullChart":{"value":{"subject":{"id":"subject_123","dob":"1990-07-23","tob":"14:30","pob":"New York, US"}}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NatalChartResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1ChartsNatal"}},"/v1/charts/current-sky":{"post":{"summary":"Calculate owned current-sky positions","description":"Returns first-party geocentric tropical positions, house cusps, aspects, and lunar phase for a supplied moment and location.","x-tool-functions":["chart.current_sky.calculate","planet.positions.list","houses.resolve","lunar.phase.extract"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentSkyRequest"},"examples":{"default":{"value":{"datetime":"2026-06-17T12:00:00.000Z","location":"Greenwich, GB","options":{"house_system":"placidus","zodiac":"tropical"}}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentSkyResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1ChartsCurrentSky"}},"/v1/charts/synastry":{"post":{"summary":"Calculate a geocentric tropical synastry chart","description":"Returns raw interchart aspects and deterministic relationship signals from the owned western sidecar. This does not call an external astrology API.","x-tool-functions":["chart.synastry.calculate","interchart.aspects.rank","relationship.signals.extract","calculation.basis.report"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynastryChartRequest"},"examples":{"default":{"value":{"subject":{"id":"person_a","dob":"1990-07-23","tob":"14:30","pob":"New York, US"},"partner":{"id":"person_b","dob":"1992-11-08","tob":"09:15","pob":"Los Angeles, US"},"max_aspects":40}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynastryChartResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1ChartsSynastry"}},"/v1/compatibility/score":{"post":{"summary":"Score relationship compatibility","description":"Uses owned synastry aspect math plus deterministic weighting to return a compatibility score, tier, strengths, and risk flags. StarTypes remains background-only when requested.","x-tool-functions":["compatibility.score.calculate","love.578.evaluate","synastry.signals.weight","helio.background.compare"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompatibilityScoreRequest"},"examples":{"default":{"value":{"subject":{"id":"person_a","dob":"1990-07-23","tob":"14:30","pob":"New York, US"},"partner":{"id":"person_b","dob":"1992-11-08","tob":"09:15","pob":"Los Angeles, US"},"context":{"relationship_type":"dating"},"scoring_profile":"balanced","include_helio_background":false}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompatibilityScoreResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1CompatibilityScore"}},"/v1/charts/transits":{"post":{"summary":"Calculate geocentric tropical transit positions and aspects","description":"Returns raw transit chart data from the owned western sidecar for ephemeris and timing workflows. When a subject is supplied, it also returns transit-to-natal aspects.","x-tool-functions":["chart.transits.calculate","transit.positions.list","transit.aspects.rank","mundane.signal.seed"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitChartRequest"},"examples":{"currentTransits":{"value":{"transit_datetime":"2026-06-17T12:00:00.000Z","transit_location":"Greenwich, GB","max_aspects":30}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitChartResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1ChartsTransits"}},"/v1/lunar/phase":{"post":{"summary":"Calculate owned lunar phase context","description":"Returns the Sun-Moon lunar phase and source positions from the owned western sidecar without generated horoscope prose or third-party fallback.","x-tool-functions":["lunar.phase.calculate","planet.positions.list","calculation.basis.report"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LunarPhaseRequest"},"examples":{"default":{"value":{"datetime":"2026-06-17T12:00:00.000Z","location":"Greenwich, GB"}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LunarPhaseResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1LunarPhase"}},"/v1/horoscope/daily":{"post":{"summary":"Generate a daily horoscope","description":"Daily horoscope API using owned transit substrate and zodiac context. Requires sign or subject.","x-tool-functions":["horoscope.daily.generate","transit.daily.seed","zodiac.knowledge.apply"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyHoroscopeRequest"},"examples":{"default":{"value":{"sign":"leo","date":"2026-06-17","sections":["theme","love","work","action"]}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyHoroscopeResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1HoroscopeDaily"}},"/v1/timing/windows":{"post":{"summary":"Generate practical timing windows","description":"Date-bounded timing windows for launches, love, career, money, content, and spiritual objectives.","x-tool-functions":["timing.windows.generate","transit.window.seed","strategy.timing.apply"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimingWindowsRequest"},"examples":{"default":{"value":{"topic":"launch","start_date":"2026-06-17","end_date":"2026-07-17","objective":"Find the best window to announce a paid API beta","max_windows":3}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimingWindowsResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1TimingWindows"}},"/v1/world/signals/jobs":{"post":{"summary":"Create an async Beyond The Veil world signal job","description":"Production path for deep world-signal forecasts. Validates auth, reserves credits, creates a Convex job, and returns a status URL. Billable usage is written only after the worker stores a complete quality-gated forecast.","x-tool-functions":["mundane.forecast.job.create","credits.reserve","job.status.poll","mundane.forecast.generate","usage.bill.on_success"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MundaneForecastRequest"},"examples":{"marketsDeep":{"value":{"topic":"markets","window_days":14,"depth":"deep"}}}}}},"responses":{"202":{"description":"Job accepted and reserved. Poll status_url until complete or failed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldSignalJobCreateResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"403":{"description":"Endpoint not allowed for this key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_FORBIDDEN","message":"Request could not be completed"}}}}}}},"409":{"description":"Idempotency key conflict","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"IDEMPOTENCY_CONFLICT","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Convex job storage failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1WorldSignalsJobs"}},"/v1/world/signals/jobs/{jobId}":{"get":{"summary":"Get async world signal job status","description":"Poll a queued, running, failed, or complete world-signal job. Polling does not bill usage. Complete jobs include the final forecast envelope under data.result.","x-tool-functions":["job.status.poll","usage.bill.on_success"],"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Current job status","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorldSignalJobStatusResponse"}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"403":{"description":"Endpoint not allowed for this key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_FORBIDDEN","message":"Request could not be completed"}}}}}}},"404":{"description":"Job not found for this key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"NOT_FOUND","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Convex job storage failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"getV1WorldSignalsJobsByJobId"}},"/v1/world/signals":{"post":{"summary":"Generate Beyond The Veil world signal intelligence","description":"Returns BTV-style world forecast intelligence with BTV article RAG metadata, deterministic verified signatures, optional live ephemeris signatures, and deterministic verified historical analog metadata.","x-tool-functions":["mundane.forecast.generate","ephemeris.transits.rank","signature.stack.apply","historical.analog.select","quality.gates.enforce"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MundaneForecastRequest"},"examples":{"marketsDeep":{"value":{"topic":"markets","window_days":14,"depth":"deep"}},"cultureModerate":{"value":{"topic":"culture","window_days":30,"depth":"moderate"}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MundaneForecastResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1WorldSignals"}},"/v1/mundane/hot-zones":{"post":{"summary":"Rank mundane hot zones","description":"Ranks supplied regions as hot zones for a topic and window using Beyond The Veil style mundane intelligence.","x-tool-functions":["hotzones.score","mundane.region.rank","watch.items.generate"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MundaneHotZonesRequest"},"examples":{"default":{"value":{"topic":"markets","regions":["United States","Europe","China","Middle East"],"window_days":30,"depth":"moderate"}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MundaneHotZonesResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1MundaneHotZones"}},"/v1/mundane/analyze-event":{"post":{"summary":"Analyze a mundane event","description":"Analyzes a supplied world event through mundane astrology and returns forward-looking implications and watch windows.","x-tool-functions":["mundane.event.analyze","event.signature.extract","forecast.implications.generate"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MundaneEventAnalysisRequest"},"examples":{"default":{"value":{"event":"A central bank unexpectedly signals a policy reversal while markets are fragile.","event_date":"2026-06-17","topic":"markets","window_days":30}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MundaneEventAnalysisResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1MundaneAnalyzeEvent"}},"/v1/helio/patterns":{"post":{"summary":"Lookup heliocentric tropical StarTypes patterns","description":"Returns a deterministic heliocentric tropical StarTypes lookup with attribution to Michael Erlewine's contributions, source work, and interpretations. This endpoint is heliocentric tropical only and is meant for background evaluation, not geocentric natal houses, Ascendant work, or lead prediction.","x-tool-functions":["startypes.lookup","helio.pattern.components","erlewine.source.credit","background.signal.guard"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required stable key for retry-safe usage logging and billing. Reuse it only when retrying the same request body.","schema":{"type":"string","maxLength":160}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HelioPatternRequest"},"examples":{"singleSubject":{"value":{"subjects":[{"id":"subject_123","dob":"1990-07-23"}],"context":{"use_case":"audience segmentation experiment"}}}}}}},"responses":{"200":{"description":"Successful API response","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HelioPatternResponse"}}}},"400":{"description":"Invalid request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_REQUEST","message":"Request could not be completed"}}}}}}},"401":{"description":"Missing or invalid API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"AUTH_REQUIRED","message":"Request could not be completed"}}}}}}},"402":{"description":"Not enough credits","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"CREDITS_EXHAUSTED","message":"Request could not be completed"}}}}}}},"429":{"description":"Rate limited","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"RATE_LIMITED","message":"Request could not be completed"}}}}}}},"500":{"description":"Unexpected internal failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"UPSTREAM_FAILED","message":"Request could not be completed"}}}}}}},"502":{"description":"Upstream or model-contract failure","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"INVALID_RESPONSE","message":"Request could not be completed"}}}}}}},"503":{"description":"Platform configuration unavailable","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-API-Version":{"$ref":"#/components/headers/ApiVersion"},"Cache-Control":{"$ref":"#/components/headers/CacheControl"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"default":{"value":{"request_id":"req_example","error":{"code":"SERVER_MISCONFIGURED","message":"Request could not be completed"}}}}}}}},"operationId":"postV1HelioPatterns"}}}}