# The Leo King Business Intelligence API - Full AI Docs Map

## Canonical Links

- Human docs: https://theleokingai.com/api-docs
- API product page: https://theleokingai.com/api-platform
- API console: https://theleokingai.com/api-console
- API Lab: https://theleokingai.com/api-console/lab
- Billing console: https://theleokingai.com/api-console/billing
- OpenAPI JSON: https://theleokingai.com/api/v1/openapi
- Endpoint index: https://theleokingai.com/api/v1
- Examples and cookbooks: https://theleokingai.com/api/v1/examples
- Access-control packet: https://theleokingai.com/api/v1/access-control
- Onboarding and launch readiness: https://theleokingai.com/api/v1/onboarding
- Public status: https://theleokingai.com/api/v1/status
- Versioning and limits: https://theleokingai.com/api/v1/versioning
- Changelog: https://theleokingai.com/api/v1/changelog
- Support policy: https://theleokingai.com/api/v1/support
- SDK readiness: https://theleokingai.com/api/v1/sdks
- Migration guides: https://theleokingai.com/api/v1/migrations
- Procurement packet: https://theleokingai.com/api/v1/procurement
- Conformance contract: https://theleokingai.com/api/v1/conformance
- Data-processing packet: https://theleokingai.com/api/v1/data-processing
- Compliance map: https://theleokingai.com/api/v1/compliance
- AI governance: https://theleokingai.com/api/v1/ai-governance
- Webhook contract: https://theleokingai.com/api/v1/webhooks
- Error catalog: https://theleokingai.com/api/v1/errors
- Postman collection: https://theleokingai.com/api/v1/postman

## Base URLs

- Dedicated API Gateway: https://api.theleokingai.com (Current production API host with clean /v1 routing.)
- Legacy Website API: https://theleokingai.com/api (Backward-compatible website host for existing alpha integrations.)
- Local Development: http://localhost:3000/api (Local Next.js development server.)

## API Contract

- Authentication header: x-api-key
- Retry and billing header: Idempotency-Key
- Versioning policy: 90 days for beta/public metadata routes; 180 days target for paid production routes once enterprise terms are signed.
- Rate limits: Sliding window backed by Upstash Redis or Vercel marketplace Redis aliases.; 60 seconds per organization, key, endpoint, and plan limit.
- Rate-limit headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After, X-RateLimit-Reset-At
- Support packet: request_id, endpoint, UTC timestamp, key prefix only, idempotency key hash, response status and error code, sanitized payload shape, production or preview environment
- Launch gates: Dedicated Gateway Reachability, Partner Server Key Handling, Usage Ledger Reconciliation, AI Output Quality Sampling, Support And Incident Drill, Signed Enterprise Boundary
- Key custody: API keys are server-to-server credentials. Store them in a backend secret manager or server-only environment variable; never ship them to browser, mobile, analytics, screenshots, or client logs.
- Success envelope: request_id, data, usage, meta
- Error envelope: request_id, error.code, error.message, error.details
- Billing lanes: core, ai, ops
- Production rule: no fallback-looking AI output can be treated as a successful billable response.
- StarTypes policy: heliocentric tropical background/evaluation signal only.

## Public Cookbooks

### Core Chart Compute
- Audience: High-volume apps that need first-party astrology facts without AI spend.
- Goal: Calculate deterministic chart, transit, lunar, synastry, compatibility, or helio background data and store it for repeated product use.
- Routes: /v1/charts/natal, /v1/charts/current-sky, /v1/charts/transits, /v1/lunar/phase, /v1/helio/patterns
- Proof: usage.lane is core, tokens are absent, meta reports owned calculation basis where applicable

### Commerce Audience Intelligence
- Audience: Shopify, CRM, email, SMS, and funnel teams scoring audiences before campaign sends.
- Goal: Score customer fit, message angle, and timing against a product or campaign context.
- Routes: /v1/audience/insights, /v1/customer/profile
- Proof: usage.lane is ai, chart quality metadata is present, fallback-looking output fails instead of billing

### Async World Signals
- Audience: Media, market, geopolitical, insurance, crypto, and research teams that need deeper BTV-style forecasts.
- Goal: Create a deep forecast job, poll until complete, and bill only after a quality-gated result is stored.
- Routes: /v1/world/signals/jobs, /v1/world/signals/jobs/{jobId}, /v1/world/signals
- Proof: create returns 202, polling does not bill usage, completed jobs include quality-gated forecast envelope

### Dating Compatibility Stack
- Audience: Dating, wellness, coaching, and relationship apps.
- Goal: Run no-AI synastry and compatibility first, then offer premium love products only when the user pays for interpretation.
- Routes: /v1/charts/synastry, /v1/compatibility/score, /v1/experiences/love-reveal, /v1/experiences/future-partner-vision
- Proof: core routes avoid model tokens, premium routes expose AI usage, relationship output includes structured sections

## Onboarding And Launch Readiness

Public JSON: https://theleokingai.com/api/v1/onboarding

### Dedicated Gateway Reachability
- Status: live
- Owner: platform
- Required evidence: `npm run smoke:api-gateway -- --base-url https://api.theleokingai.com --final` passes and returns the current contractVersion.
- Failure mode: Block launch if the dedicated gateway, OpenAPI, status, docs, or metadata aliases do not resolve through the public host.

### Partner Server Key Handling
- Status: beta
- Owner: shared
- Required evidence: Partner confirms keys are stored server-side only, scoped to the expected organization/routes, and never shipped to browser/mobile clients.
- Failure mode: Block production traffic if keys are exposed in client code, screenshots, support tickets, or analytics events.

### Usage Ledger Reconciliation
- Status: beta
- Owner: platform
- Required evidence: Buyer-path smoke proves response `request_id`, usage lane, credits, and Convex usage event agree for the same call.
- Failure mode: Block paid launch when usage response fields and ledger rows disagree or cannot be traced by request_id.

### AI Output Quality Sampling
- Status: beta
- Owner: shared
- Required evidence: Inspect 1-3 fresh production AI outputs after deploy for required sections, model metadata, depth, and no fallback-looking copy.
- Failure mode: Block publication or partner demo if output quality is unverified, generic, missing required sections, or fallback-looking.

### Support And Incident Drill
- Status: live
- Owner: shared
- Required evidence: Partner can provide request_id, endpoint, UTC timestamp, key prefix only, idempotency hash, sanitized payload shape, and severity.
- Failure mode: Block enterprise launch if support evidence requires raw secrets, complete private payloads, payment details, or a private DPA process that is not signed.

### Signed Enterprise Boundary
- Status: enterprise
- Owner: shared
- Required evidence: Order form, DPA/addendum when applicable, custom SLA/support exhibit, limits, allowlists, and launch checklist are signed before custom commitments.
- Failure mode: Do not promise custom retention, residency, allowlists, private endpoints, dedicated response windows, or audit export packages from public metadata alone.

Handoff artifacts:

- Production Smoke Evidence: Gateway readiness, public metadata compatibility, OpenAPI freshness, and post-deploy release proof. Redaction boundary: Include URL, status, contractVersion, deployment URL, commit SHA, and timestamps; do not include secrets or private payloads.
- Partner Integration Matrix: Mapping environments, server owners, endpoint scopes, expected volume, retry policy, and escalation contacts before traffic ramps. Redaction boundary: Use role/team contacts and endpoint scopes; do not publish personal phone numbers, raw keys, or customer payload samples.
- Usage And Billing Proof: Confirming credits, lane, billable units, idempotency behavior, and ledger traceability before paid production use. Redaction boundary: Use request_id, organization id, key prefix only, endpoint, credits, and timestamps; never expose key hashes or payment identifiers.
- AI Quality Evidence: Proving generated-output routes meet product contract after deploy or generation-logic changes. Redaction boundary: Use sanitized prompts/outputs or customer-approved examples; do not export complete private payloads without signed support terms.
- Rollback And Disable Plan: Knowing how to pause keys, downgrade traffic, disable AI publication, roll back a deploy, and communicate incidents. Redaction boundary: Include runbook names and owners; keep admin tokens, provider dashboards, and private incident contacts out of public packets.

## Access Control And Key Management

Public JSON: https://theleokingai.com/api/v1/access-control

Authentication header: x-api-key

Browser boundary: Browser and mobile clients must call a partner backend. Direct public-client calls to paid API routes are unsupported because keys, scopes, usage, and support evidence must stay server-controlled.

Enterprise boundary: Public access-control metadata is review guidance, not a custom security contract. Customer-specific key custody, allowlists, private data terms, and audit export packages require signed terms.

Environments:

- Production Gateway: https://api.theleokingai.com; key prefix lk_live_; Use production-scoped keys only from trusted server environments and verify usage ledger evidence before enterprise demos.
- Legacy Website API Host: https://theleokingai.com/api; key prefix lk_live_; Do not create new public integrations on the legacy host unless compatibility testing requires it.
- Local Development: http://localhost:3000/api; key prefix lk_dev_; Local keys and fixture payloads must not be reused as production credentials or customer evidence.

Key lifecycle:

- Create Server-Side Key: Create the key from the customer console, approved internal smoke flow, or signed enterprise onboarding path. Evidence: Key has organization id, key prefix, status, endpoint scope, plan/credit state, and creation audit event.
- Store In Backend Secret Manager: Put the raw key in a backend secret manager or server-only environment variable before making requests. Evidence: Partner confirms the key is absent from browser bundles, mobile clients, analytics events, source control, and support screenshots.
- Validate Scope Before Launch: Run a scoped smoke request and verify the endpoint, usage lane, credit charge, and Convex ledger row match expectations. Evidence: Buyer-path smoke proves the same request_id in response and usageEvents before paid traffic ramps.
- Rotate On Exposure Or Staff Change: Rotate any key that appears outside server-only storage or after relevant operator/offboarding changes. Evidence: Audit trail shows old key revoked and replacement key created with equivalent intended scope.
- Revoke Or Pause On Incident: Disable compromised, over-limit, expired, or out-of-contract keys before route execution. Evidence: Auth validation returns a non-billable auth/scope error and support packet uses key prefix only.
- Negotiate Enterprise Controls: Move IP allowlists, private endpoint terms, dedicated network review, or audit export packages into signed terms. Evidence: Signed order form or security exhibit names the customer-specific controls and evidence cadence.

Requirements:

- Server-Side Custody: Call API routes from a trusted backend and keep raw keys out of public clients, logs, screenshots, and support tickets. Platform evidence: Docs, SDKs, support packet rules, and auth errors all require `x-api-key` from server-controlled contexts.
- Endpoint Scope: Request only the endpoints and traffic volume the key is scoped to use. Platform evidence: Key validation checks status, organization, endpoint access, credit state, and plan limits before execution.
- Environment Separation: Keep production keys and evidence separate from local fixtures and legacy-host compatibility testing. Platform evidence: Public metadata publishes canonical base URLs, key prefixes, and gateway smoke commands.
- Rotation And Revocation: Report exposed key prefixes only and rotate keys when custody changes or exposure is suspected. Platform evidence: Console audit trail and access-control packet define rotation triggers and non-billable failure behavior.
- Rate-Limit Cooperation: Respect 429 responses, back off with Retry-After, and coordinate load tests before traffic spikes. Platform evidence: Versioning and limits route publishes rate-limit algorithm, headers, and plan limits.
- Enterprise Network Controls: Do not assume customer-specific network controls from public docs; include them in signed enterprise terms. Platform evidence: Procurement, security, access-control, and launch-readiness packets all mark allowlists as signed-term work.

## Support And Escalation

Public JSON: https://theleokingai.com/api/v1/support

### Developer Metadata Support
- Status: live
- Audience: Developers evaluating the public docs, OpenAPI, Postman, SDK source, examples, status, and errors catalog.
- Availability: Public docs and metadata are self-serve and cacheable.
- First response: Best-effort while the API is in alpha.
- Scope: docs questions, schema clarification, public route discovery, integration packet review
- Escalation: Move to partner support when a real API key, paid route, or buyer-path smoke is involved.

### Partner Beta Support
- Status: beta
- Audience: Approved beta partners using scoped server-side keys and paid routes.
- Availability: Business-hours review with production incident escalation when live API behavior is degraded.
- First response: One business day for integration blockers; faster for production-impacting incidents.
- Scope: key setup, credit behavior, route contract issues, usage proof, AI quality failures
- Escalation: Include the support packet and route through incident policy when production impact is confirmed.

### Enterprise Contract Support
- Status: enterprise
- Audience: Signed enterprise customers with custom limits, private terms, audit exports, or dedicated support windows.
- Availability: Defined by signed terms after monitoring, support window, and escalation contacts are approved.
- First response: Contract-specific after enterprise support terms are signed.
- Scope: custom limits, allowlists, DPA/security review, audit exports, dedicated incident response
- Escalation: Use signed contact paths and include request_id, key prefix only, endpoint, UTC timestamp, and sanitized payload shape.

Support never needs: raw API keys, bearer tokens, webhook signing secrets, payment details, full private prompts, complete birth data payloads unless a signed support process requires it

## SDK Package Readiness

Public JSON: https://theleokingai.com/api/v1/sdks

### @theleoking/ai-api
- Language: node
- Status: release_gate
- Source: sdk/node
- Install: npm install @theleoking/ai-api
- Local build: npm --prefix sdk/node run build
- Helper surface: public metadata helpers, core chart compute helpers, AI experience helpers, async world-signal job helpers, webhook signature helpers
- Release gates: package namespace approval, dist files rebuilt from TypeScript source, SDK contract tests pass, OpenAPI route coverage reviewed, production docs and support policy approved

### theleoking-ai-api
- Language: python
- Status: release_gate
- Source: sdk/python
- Install: pip install theleoking-ai-api
- Local build: python -m compileall sdk\python\theleoking_ai_api
- Helper surface: public metadata helpers, core chart compute helpers, AI experience helpers, async world-signal job helpers, webhook signature helpers
- Release gates: package namespace approval, Python package metadata review, SDK contract tests pass, compileall syntax check passes, production docs and support policy approved

SDK release policy: npm and PyPI publication is gated until package names, production domain, support policy, docs, env readiness, and Dave's explicit release approval are all current.

## Migration And Deprecation Guides

Public JSON: https://theleokingai.com/api/v1/migrations

Policy: Breaking changes require a changelog entry, OpenAPI update, migration guide, support path, and the notice window defined in /api/v1/versioning before removal.

### Move From Website API Host To Dedicated Gateway
- Status: live
- Audience: Alpha partners using https://theleokingai.com/api directly.
- From: https://theleokingai.com/api/v1/*
- To: https://api.theleokingai.com/v1/*
- Timeline: Available now; legacy website host remains backward compatible during alpha.
- Validation: GET https://api.theleokingai.com/v1 returns the API index., GET https://api.theleokingai.com/openapi.json rewrites to /api/v1/openapi., Buyer-path smoke proves usage ledger rows for paid routes before production traffic moves.

### Move Customer Profile Alias To Audience Insights
- Status: beta
- Audience: Commerce, CRM, funnel, and audience-scoring partners using the early customer profile alias.
- From: POST /v1/customer/profile
- To: POST /v1/audience/insights
- Timeline: No removal date is scheduled. A dated migration window must be published before any alias sunset.
- Validation: OpenAPI documents /v1/audience/insights as the canonical route., The legacy alias remains listed under /api/v1/versioning until a migration window is published., Output quality must remain business-grade and fallback-looking responses must fail.

### Move Mundane Forecast Alias To World Signals
- Status: beta
- Audience: BTV, media, market, geopolitical, research, and forecast partners.
- From: POST /v1/mundane/forecast
- To: POST /v1/world/signals or POST /v1/world/signals/jobs
- Timeline: No removal date is scheduled. Async job adoption is recommended before high-volume deep forecast use.
- Validation: Async create returns 202 with status_url and reserved credits., Completed jobs include data.result, usage, and meta., Quality gates reject generic, incomplete, or fallback-looking forecasts before billing.

## Procurement And Compliance Review

Public JSON: https://theleokingai.com/api/v1/procurement

Audience: enterprise buyers, procurement reviewers, security reviewers, legal reviewers, technical evaluators

Buyer packet: Company and product summary for The Leo King Business Intelligence API., Dedicated production gateway and public OpenAPI contract., Security packet, data-retention notes, and current subprocessor scope., Compliance-readiness map with current evidence links and certification boundaries., Public SLA targets, incident policy, and support escalation boundary., Versioning, deprecation, migration, and rate-limit policy., SDK package readiness, release gates, examples, and onboarding checklist., Support packet fields required for production triage.

Unavailable until signed terms: custom DPA or private data-processing terms, contractual SLA response windows, dedicated support contacts, IP allowlists, long-range audit export packages, custom retention schedules, private endpoint scopes or customer-specific model terms

### Security Controls
- Status: live
- Owner: platform
- Requirement: Publish API-key handling, data minimization, rate-limit, and no-fallback-success controls.
- Evidence: Security packet exposes public controls and partner expectations.
- Public link: https://theleokingai.com/api/v1/security

### Data Handling
- Status: live
- Owner: shared
- Requirement: Review retention boundaries and restrict support packets to sanitized operational evidence.
- Evidence: Security and support routes publish data-retention categories plus never-include fields.
- Public link: https://theleokingai.com/api/v1/support

### Compliance Mapping
- Status: live
- Owner: shared
- Requirement: Map public controls to common enterprise review categories without claiming certifications that are not published.
- Evidence: Compliance map identifies current evidence, framework-style mappings, and signed-term boundaries.
- Public link: https://theleokingai.com/api/v1/compliance

### AI Governance
- Status: live
- Owner: shared
- Requirement: Review generated-output quality gates, acceptable-use boundaries, restricted use cases, and escalation triggers before production launch.
- Evidence: AI governance packet defines allowed, restricted, prohibited, human-review, and support-evidence boundaries.
- Public link: https://theleokingai.com/api/v1/ai-governance

### Subprocessor Review
- Status: beta
- Owner: platform
- Requirement: Expose current infrastructure, auth, billing, model, sidecar, rate-limit, and monitoring subprocessors.
- Evidence: Security packet lists current subprocessors and the data scope for each.
- Public link: https://theleokingai.com/api/v1/security

### SLA And Incidents
- Status: live
- Owner: platform
- Requirement: Publish current availability targets, measurement boundary, incident fields, and postmortem policy.
- Evidence: SLA and incidents routes expose public targets and current incident history status.
- Public link: https://theleokingai.com/api/v1/sla

### Versioning And Migration
- Status: live
- Owner: platform
- Requirement: Document compatibility guarantees, breaking-change artifacts, migration guides, and sunset requirements.
- Evidence: Versioning and migrations routes publish lifecycle policy and route-specific migration guides.
- Public link: https://theleokingai.com/api/v1/migrations

### Operational Proof
- Status: beta
- Owner: shared
- Requirement: Run env gate, gateway smoke, buyer-path usage proof, and AI output-quality sampling before launch.
- Evidence: Observability route and onboarding route publish production proof requirements.
- Public link: https://theleokingai.com/api/v1/observability

### Legal Terms
- Status: enterprise
- Owner: shared
- Requirement: Move DPA, custom retention, dedicated support, allowlists, and contractual SLA into signed terms.
- Evidence: Procurement packet identifies what public metadata does and does not contractually promise.
- Public link: https://theleokingai.com/api/v1/procurement

## Conformance And Smoke Contract

Public JSON: https://theleokingai.com/api/v1/conformance

Required before: publishing SDK packages, approving enterprise procurement packets, raising rate limits, launching a signed partner integration, declaring AI generation logic healthy after deploy

Launch gates: Production env guard prints READY FOR PUSH/DEPLOY for the target environment., Public metadata routes, OpenAPI, Postman, docs, llms files, sitemap, and robots discovery all agree., SDK source, generated dist, README snippets, and public endpoint catalog stay in sync., Dedicated gateway smoke passes against https://api.theleokingai.com., Buyer-path smoke proves a paid route writes usage ledger evidence for the exact request_id., Fresh AI outputs created after deploy satisfy required sections, depth, metadata, and no fallback-looking copy.

Evidence retention: Keep smoke outputs, request_id, endpoint, UTC timestamp, key prefix only, commit SHA, deployment URL, and sanitized payload shape for support and procurement review.

### Local Contract Suite
- Status: live
- Owner: platform
- Target: Source, route handlers, OpenAPI, docs, SDK helpers, robots, sitemap, and gateway config.
- Command: npm run test -- --run tests/api-v1.test.ts tests/api-reference-docs.test.ts tests/robots.test.ts tests/api-gateway-config.test.ts tests/sdk-contract.test.ts
- Proves: Public API metadata, docs discovery, gateway rewrites, and SDK helpers agree before deploy.
- Pass criteria: All focused API-platform tests pass., OpenAPI exposes public metadata routes without API-key auth., Docs, sitemap, robots, SDK source, and README helper lists include the same public metadata surfaces.
- Evidence artifacts: Vitest focused suite output, changed file diff, OpenAPI route assertions

### SDK Source And Dist
- Status: live
- Owner: platform
- Target: Node TypeScript source/dist and Python source package.
- Command: npm --prefix sdk/node run build && python -m compileall sdk\python\theleoking_ai_api
- Proves: SDK public metadata helpers, authenticated route helpers, webhook helpers, and generated Node dist compile.
- Pass criteria: Node TypeScript build emits dist/index.js and dist/index.d.ts., Python package compiles with no syntax errors., Generated Python __pycache__ is removed before handoff.
- Evidence artifacts: Node SDK build output, Python compileall output, SDK contract test output

### Production Build
- Status: live
- Owner: platform
- Target: Next.js app routes, static API metadata, docs page, and TypeScript.
- Command: npm run build
- Proves: The app compiles, route handlers type-check, and static public metadata routes are generated.
- Pass criteria: Next build completes successfully., Static metadata routes include /api/v1/status, /api/v1/openapi, /api/v1/procurement, and /api/v1/conformance., No route handler or docs TypeScript errors are present.
- Evidence artifacts: Next build output, route list, TypeScript output

### Production Env Gate
- Status: live
- Owner: platform
- Target: Vercel production env names, Clerk Convex JWT template, and deploy preconditions.
- Command: npm run prod:env:production
- Proves: Required production env surfaces exist before push/deploy and Clerk JWT template is configured.
- Pass criteria: Vercel production check prints READY FOR PUSH/DEPLOY., Clerk prod check prints READY FOR PUSH/DEPLOY., Sensitive values are presence-checked without printing raw secrets.
- Evidence artifacts: env guard timestamp, masked checklist, Clerk template check output

### Dedicated Gateway Smoke
- Status: live
- Owner: platform
- Target: https://api.theleokingai.com public gateway routing and discovery metadata.
- Command: npm run smoke:api-gateway -- --mode final
- Proves: Dedicated gateway DNS, root JSON, OpenAPI, Postman, status, and docs discovery work in production.
- Pass criteria: Gateway root returns the API index., OpenAPI and Postman routes resolve through clean gateway paths., Public metadata routes return current contractVersion.
- Evidence artifacts: inference-smoke/api-gateway-smoke.json, HTTP status codes, contractVersion

### Buyer Path Usage Smoke
- Status: beta
- Owner: shared
- Target: Paid route response envelope, credit accounting, and Convex usageEvents reconciliation.
- Command: npm run smoke:buyer-path -- --base-url https://api.theleokingai.com --output inference-smoke/buyer-path-gateway-core-YYYYMMDD.json
- Proves: A scoped key can call a paid route and the exact request_id appears in the usage ledger.
- Pass criteria: Response includes request_id, data, usage, and meta., Usage lane, credits, billable units, and model metadata match route expectations., Convex usageEvents contains the exact request_id before enterprise demo or launch.
- Evidence artifacts: buyer-path smoke JSON, request_id, Convex usageEvents proof

### AI Output Quality Sampling
- Status: beta
- Owner: shared
- Target: Fresh production AI outputs after generation, prompt, model, RAG, or provider changes.
- Command: Inspect 1-3 fresh live outputs created after the deploy timestamp.
- Proves: AI value quality is preserved, not merely that status codes and pipelines succeeded.
- Pass criteria: Required sections are present for the selected product contract., Metadata, model/provider trace, depth, and forward-looking analysis are present where promised., No placeholder, generic fallback, local path leak, malformed schema, or thin copy is published.
- Evidence artifacts: request_id list, output timestamps, quality notes, incident link if failed

## Data Processing

Public JSON: https://theleokingai.com/api/v1/data-processing

Scope: Public data-processing review metadata for API buyers. It describes current API handling boundaries and does not replace signed customer-specific DPA terms.

DPA boundary: A signed DPA or data-processing addendum is required before custom retention, regional residency, regulated-data commitments, private endpoint scopes, or customer-specific processor terms are promised.

Restricted data: raw API keys, bearer tokens, webhook secrets, provider credentials, payment card or bank account data, government identifiers, health records or protected medical data, children's data without a signed, reviewed use case, regulated or high-risk data categories not approved in signed terms

### Core Astrology Compute
- Status: beta
- Purpose: Calculate deterministic chart, transit, compatibility, lunar, and helio background data for partner products.
- Data categories: partner subject id, birth date, birth time when supplied, birth place or coordinates, event datetime/location
- Lawful basis boundary: Partner is responsible for end-user notice, consent, and lawful basis for collecting and sending birth or event data.
- Retention source: API Request Metadata and Birth Data Payloads entries in the public retention policy.
- Partner responsibility: Store only the deterministic output needed for the product and avoid sending unrelated identity fields.

### AI Intelligence And Experiences
- Status: beta
- Purpose: Generate audience intelligence, premium spiritual experiences, oracle/tarot interpretation, and world-signal analysis.
- Data categories: partner customer id, campaign context, route-specific prompt/context, generated output, model/provider metadata
- Lawful basis boundary: Partner controls prompts and user-facing context; platform quality gates prevent fallback-shaped output from being treated as success.
- Retention source: Generated AI Outputs and Support Evidence entries in the public retention policy.
- Partner responsibility: Do not send private prompts, sensitive personal data, or regulated data unless the signed use case permits it.

### Billing And Entitlement
- Status: beta
- Purpose: Meter credits, plan state, scoped key access, request rate, subscription state, and usage reconciliation.
- Data categories: organization id, API key hash/prefix, endpoint, credits, billing lane, subscription state, request_id
- Lawful basis boundary: Billing provider handles payment instruments; this API surface tracks entitlement and usage state for subscribed API access.
- Retention source: Billing And Entitlement Records and API Request Metadata entries in the public retention policy.
- Partner responsibility: Never send payment card or bank account data to API routes or support channels.

### Support, Incident, And Conformance Evidence
- Status: live
- Purpose: Triage integration issues, incidents, output-quality regressions, conformance evidence, and procurement review.
- Data categories: request_id, endpoint, UTC timestamp, key prefix only, idempotency key hash, sanitized payload shape, deployment metadata
- Lawful basis boundary: Support evidence should be operational metadata. Raw secrets and complete private payloads are not needed for normal support.
- Retention source: Support Evidence entry in the public retention policy and conformance evidence retention policy.
- Partner responsibility: Redact raw payloads, secrets, payment details, and complete birth data unless a signed support process requires them.

Data-subject request support packet: organization id, partner subject id, request_id list when available, endpoint list, UTC date range, requested action, signed support/DPA reference when private data is involved

## Compliance Map

Public JSON: https://theleokingai.com/api/v1/compliance

Scope: Public compliance-readiness mapping for API buyers. It maps current public controls to common review areas and does not replace customer-specific legal, privacy, security, or audit review.

No certification claim: This public packet is a readiness and evidence map only. It does not claim SOC 2 or ISO 27001 certification, HIPAA or PCI eligibility, GDPR compliance determination, or regulated-data approval unless those artifacts are separately published in signed customer review materials.

Mapped frameworks: SOC 2-style security, availability, confidentiality, and privacy review areas, GDPR/data-processing review readiness, OWASP API security review readiness, Enterprise procurement and vendor-risk review, Operational resilience, SLA, and incident-review readiness, AI output-quality and fallback-prevention governance

Requires signed terms: SOC 2 report or bridge letter sharing when available, customer-specific DPA or data-processing addendum, HIPAA, PCI, children data, regulated-data, or regional residency commitments, long-range audit export packages or private logs, IP allowlists, private endpoints, custom network controls, or dedicated security exhibits, contractual SLA/support response windows

### SOC 2-Style Security Review
- Status: live
- Scope: Security, confidentiality, access control, change evidence, and incident review areas.
- Controls: server-side API-key custody, scoped endpoint access, secret redaction boundaries, support packet minimization, security.txt vulnerability contact, incident publication policy
- Evidence links: https://theleokingai.com/api/v1/security, https://theleokingai.com/api/v1/access-control, https://theleokingai.com/api/v1/support, https://theleokingai.com/api/v1/incidents
- Reviewer action: Review public controls, confirm partner-side key custody, and move report sharing or private audit evidence into signed terms.
- Boundary: Public docs are readiness evidence; formal SOC 2 report access requires separate availability and signed review terms.

### SOC 2-Style Availability Review
- Status: beta
- Scope: Gateway availability, status publication, operational smoke, and support escalation readiness.
- Controls: public SLA targets, incident history policy, gateway smoke, production env gate, buyer-path usage proof, rollback and disable plan
- Evidence links: https://theleokingai.com/api/v1/sla, https://theleokingai.com/api/v1/status, https://theleokingai.com/api/v1/observability, https://theleokingai.com/api/v1/onboarding, https://theleokingai.com/api/v1/conformance
- Reviewer action: Run the conformance suite and live smoke checks before any enterprise demo or production launch claim.
- Boundary: Contractual availability targets require signed customer terms and dedicated monitoring.

### GDPR/Data Processing Review Readiness
- Status: live
- Scope: Processing purposes, data minimization, restricted data, retention, subprocessors, and DSR support.
- Controls: published processing purposes, restricted-data list, data-minimization rules, subprocessor scope, DSR support packet, signed-DPA boundary
- Evidence links: https://theleokingai.com/api/v1/data-processing, https://theleokingai.com/api/v1/security, https://theleokingai.com/api/v1/procurement
- Reviewer action: Confirm partner lawful basis, user notices, and whether customer-specific DPA terms are required before production traffic.
- Boundary: Public packet does not create a DPA, residency promise, or regulated-data authorization.

### OWASP API Security Review Readiness
- Status: beta
- Scope: Authentication, authorization, rate limiting, input validation, error handling, and secret exposure boundaries.
- Controls: x-api-key auth, endpoint scope checks, rate-limit policy, standard error envelope, idempotency conflict behavior, browser/CORS key-exposure boundary
- Evidence links: https://theleokingai.com/api/v1/access-control, https://theleokingai.com/api/v1/versioning, https://theleokingai.com/api/v1/errors, https://theleokingai.com/api/v1/openapi
- Reviewer action: Generate clients from OpenAPI, enforce server-side key storage, and verify 401/403/409/429 handling in partner code.
- Boundary: Custom network controls, mTLS-style controls, and allowlists require signed enterprise terms.

### Enterprise Procurement And Vendor Risk
- Status: live
- Scope: Buyer packet, legal/security/ops review, signed-term gates, support boundaries, and durable evidence links.
- Controls: buyer packet, review checklist, legal boundary, operational proof, support tiers, signed-term gates
- Evidence links: https://theleokingai.com/api/v1/procurement, https://theleokingai.com/api/v1/support, https://theleokingai.com/api/v1/conformance, https://theleokingai.com/api/v1/sdks, https://theleokingai.com/api/v1/migrations
- Reviewer action: Use the public procurement packet first, then request signed artifacts for private retention, DPA, SLA, audit, or allowlist commitments.
- Boundary: Public metadata accelerates vendor review but is not a master services agreement, DPA, or security exhibit.

### AI Output Quality Governance
- Status: beta
- Scope: Generation quality, fallback prevention, output sampling, model/provider metadata, and incident escalation.
- Controls: no fallback success rule, fresh live output sampling, quality-gate failure handling, model/token visibility, AI incident severity policy, support escalation packet
- Evidence links: https://theleokingai.com/api/v1/conformance, https://theleokingai.com/api/v1/observability, https://theleokingai.com/api/v1/errors, https://theleokingai.com/api/v1/incidents
- Reviewer action: Inspect 1-3 fresh generated outputs created after deploy timestamps when generation logic, model, RAG, or provider settings change.
- Boundary: Passing builds and HTTP status checks do not prove AI product quality.

Evidence artifacts:

- Security Packet: Security and confidentiality review starter evidence. Public link: https://theleokingai.com/api/v1/security
- Access-Control Packet: Authentication, authorization, and key-management review. Public link: https://theleokingai.com/api/v1/access-control
- Data-Processing Packet: Privacy, data-processing, and DPA scoping review. Public link: https://theleokingai.com/api/v1/data-processing
- Conformance Contract: Production readiness and acceptance evidence. Public link: https://theleokingai.com/api/v1/conformance
- Observability Proof: Operational readiness and smoke-evidence review. Public link: https://theleokingai.com/api/v1/observability
- SLA And Incident Policy: Availability and resilience review. Public link: https://theleokingai.com/api/v1/sla
- Procurement Packet: Vendor-risk and legal handoff review. Public link: https://theleokingai.com/api/v1/procurement

## AI Governance And Acceptable Use

Public JSON: https://theleokingai.com/api/v1/ai-governance

Scope: Public AI governance and acceptable-use metadata for API buyers. It covers generated-output quality, display boundaries, restricted use cases, and escalation paths for model-backed routes.

Acceptable-use boundary: The API may support entertainment, media, wellness, relationship, audience-intelligence, timing, and world-signal workflows when partners present output as guidance or analysis, not deterministic fact, diagnosis, legal advice, financial instruction, or emergency direction.

Output-quality policy: Model-backed routes must satisfy route-specific schemas, required sections, metadata, and no-fallback-looking language before a response is treated as successful or billable.

Human-review boundary: High-impact, public, paid, regulated, crisis, or strategic decisions should include partner-side human review before output is published or acted upon.

Model transparency: AI endpoints expose usage lane, credits, model/provider metadata when available, token visibility when model-backed generation runs, and request_id for support traceability.

Prohibited uses: medical diagnosis, treatment, emergency response, or mental-health crisis handling, legal, tax, investment, credit, insurance, employment, housing, or eligibility decisions as deterministic instruction, government benefit, law-enforcement, surveillance, biometric, or identity-verification decisions, automated decisions that materially affect a person's rights or access to essential services without signed review and human oversight, deception, impersonation, harassment, manipulation, or content presented as guaranteed prophecy or factual certainty, sending raw secrets, payment instruments, government identifiers, health records, children's data, or regulated data without signed approval

Restricted uses: public market, geopolitical, campaign, or business strategy outputs used outside editorial/research context, relationship, dating, compatibility, or wellness products that could create sensitive user-facing claims, batch audience intelligence that affects segmentation, offers, outreach, or pricing, regulated-data, minors, crisis, workplace, hiring, credit, insurance, or high-impact use cases, custom model/data terms, private endpoint scopes, or customer-specific output retention

### Entertainment, Wellness, And Personal Insight
- Status: beta
- Allowed use: Horoscope, tarot, oracle, love, timing, compatibility, and spiritual-experience products with clear interpretive framing.
- Restricted use: Sensitive relationship, crisis, addiction, grief, fertility, medical, legal, or financial claims require product review and may need signed terms.
- Prohibited use: Do not present output as diagnosis, guaranteed prophecy, emergency guidance, or factual certainty about a person's future.
- Partner responsibility: Use visible user-facing framing, escalation paths, and human review for sensitive public experiences.

### Audience Intelligence And Campaign Strategy
- Status: beta
- Allowed use: Segment-level campaign-fit, tone, timing, and creative-angle guidance for marketing teams.
- Restricted use: Individual pricing, eligibility, employment, credit, insurance, housing, political persuasion, or sensitive profiling requires signed review and may be disallowed.
- Prohibited use: Do not use outputs as the sole basis for consequential decisions about a person or protected class.
- Partner responsibility: Keep segmentation human-reviewed, disclose appropriate use internally, and avoid sending unnecessary personal data.

### World Signals, Markets, And Public Research
- Status: beta
- Allowed use: Editorial, research, scenario planning, media analysis, trend monitoring, and strategic briefing workflows.
- Restricted use: Trading, investment, insurance, legal, public safety, emergency, or policy decisions require independent review and signed customer terms.
- Prohibited use: Do not present forecasts as investment advice, legal advice, guaranteed outcomes, or emergency instructions.
- Partner responsibility: Label forecasts as interpretive intelligence and verify facts, market data, and operational decisions outside the API.

### Core Astrology Compute
- Status: live
- Allowed use: Deterministic chart, transit, lunar, compatibility, synastry, and helio background calculation for partner products.
- Restricted use: High-volume, regulated, minors, or sensitive personalization should be reviewed for data minimization and consent.
- Prohibited use: Do not infer protected traits, medical states, legal status, or eligibility from chart data.
- Partner responsibility: Collect the minimum birth/event data required and keep user notices, consent, and downstream storage under partner control.

Controls:

- No Fallback Success: Fallback-looking, malformed, thin, missing-section, or placeholder output must fail instead of publishing as success. Evidence: Conformance, observability, error catalog, and incident policy classify output-quality failures as product regressions. Public link: https://theleokingai.com/api/v1/conformance
- Route-Specific Quality Gates: Generated output must satisfy the route's schema, required sections, product depth, model metadata, and route-specific constraints. Evidence: Endpoint catalog and tests enforce structured outputs, quality gates, and INVALID_RESPONSE behavior. Public link: https://theleokingai.com/api/v1/openapi
- Human Review Boundary: Partner reviewers should inspect output before publication, customer delivery, or operational use where reliance risk is meaningful. Evidence: AI governance, conformance, onboarding, and support packets require fresh output sampling and escalation for degraded content. Public link: https://theleokingai.com/api/v1/ai-governance
- Restricted Use Escalation: Move restricted workflows into signed review or decline the use case before production traffic. Evidence: Procurement, compliance, data-processing, and AI governance packets mark these uses as signed-term review. Public link: https://theleokingai.com/api/v1/procurement
- Transparent Support Evidence: Use request_id, endpoint, UTC timestamp, key prefix only, model/provider metadata, and sanitized payload/output shape. Evidence: Support and access-control packets define required support evidence and never-include fields. Public link: https://theleokingai.com/api/v1/support
- Data Minimization: Send only route-required data and keep secrets, payment data, regulated data, and unnecessary identifiers out of prompts and support evidence. Evidence: Data-processing and security packets publish minimization, restricted data, retention, and subprocessor boundaries. Public link: https://theleokingai.com/api/v1/data-processing

## Developer Platform Status

- REST API Gateway: live - Server-to-server /api/v1 routes with API-key auth and standard envelopes.
- OpenAPI Contract: live - Machine-readable OpenAPI 3.1 contract for generated clients and review.
- Human Developer Docs: live - Discoverable docs page, quickstart, examples, endpoint reference, plans, and enterprise path.
- API Console And Lab: beta - Private console for keys, usage, billing, endpoint testing, workspace audit history, and visible audit CSV export.
- Core Compute: beta - No-AI chart, sky, transit, lunar, synastry, compatibility, and helio background routes.
- AI Intelligence: beta - Audience intelligence, premium experiences, oracle/tarot, horoscope, and world signals.
- Usage Ledger: beta - Request id, endpoint, credits, billing lane, model, token metadata, and idempotency tracking.
- SDK Packages: release_gate - Node and Python source exists; public npm/PyPI publication is still gated.
- Partner Webhooks: next - Signed callbacks for async completion, usage, quality, billing, and entitlement events.
- SLA And Incident History: live - Public SLA target and incident-history contract for discovery, procurement, and partner review.
- Security And Trust Packet: live - Public security controls, well-known security contact, data handling boundaries, subprocessor notes, and enterprise review packet.
- Access Control Packet: live - Public key custody, scope model, environment separation, rotation/revocation, browser boundary, and allowlist policy.
- Observability Proof: beta - Gateway smoke, production env gates, buyer-path usage proof, readiness checks, and AI output quality sampling.
- Buyer Onboarding: beta - Server-key setup, first request, idempotency, error handling, usage proof, launch-readiness gates, handoff artifacts, and escalation packet.
- Versioning And Limits: live - Public lifecycle, compatibility, deprecation, sunset, and rate-limit contract for v1 partners.
- Migration Guides: live - Public route migration, deprecation artifact, legacy alias, validation, and partner checklist guidance.
- Examples And Cookbooks: live - Public endpoint examples, SDK snippets, and partner workflow cookbooks generated from the API catalog.
- Support And Escalation: live - Public support tiers, support packet requirements, severity routing, and enterprise escalation boundaries.
- Procurement And Compliance Packet: live - Public buyer-review checklist, security/legal/ops review boundaries, signed-term gates, and durable trust links.
- Conformance And Smoke Contract: live - Public acceptance suites, commands, pass criteria, evidence artifacts, and launch gates for partner and production readiness.
- Data Processing Packet: live - Public data-use purposes, minimization rules, restricted-data boundary, DSR support policy, and signed-DPA gates.
- Compliance Map: live - Public compliance-readiness mapping across SOC 2-style, GDPR/data-processing, OWASP API, procurement, resilience, and AI quality review areas.
- AI Governance And Acceptable Use: live - Public generated-output governance, acceptable-use boundaries, restricted use cases, human-review policy, and escalation triggers.

## Public Changelog

### v1 alpha (Current)
Public security, observability, onboarding, SLA, and incident contracts are linked through the docs, OpenAPI, gateway, and trust page.
- Security packet, observability proof, and onboarding JSON routes added to the public metadata contract.
- Authenticated API console now exposes org-bound, redacted audit trail groundwork for key and workspace events.
- Partner webhook signature verification now has a concrete HMAC-SHA256 contract and test-backed helper.
- Versioning, deprecation, sunset, and rate-limit policy are now published as public developer metadata.
- Examples and partner cookbooks are now published as public developer metadata generated from the endpoint catalog.
- Support tiers, escalation rules, and support packet requirements are now published as public developer metadata.
- SDK package readiness, install commands, helper surface, and release gates are now published as public developer metadata.
- Migration guides and deprecation artifact requirements are now published as public developer metadata.
- Procurement review packet, signed-term gates, and buyer evidence checklist are now published as public developer metadata.
- Conformance suites, smoke commands, launch gates, and evidence artifacts are now published as public developer metadata.
- Data-processing purposes, minimization rules, restricted-data boundaries, and DSR support policy are now published as public developer metadata.
- Launch-readiness gates and partner handoff artifacts are now published through the onboarding contract.
- Access-control policy, API-key custody, environment boundaries, lifecycle steps, and allowlist gates are now published as public developer metadata.
- Compliance-readiness mappings, evidence artifacts, certification boundaries, and signed-term gates are now published as public developer metadata.
- AI governance, acceptable-use boundaries, restricted-use escalation, human-review policy, and no-fallback-success controls are now published as public developer metadata.
- API docs now expose trust controls, data handling, subprocessor scope, production proof, and buyer onboarding steps.
- Dedicated gateway smoke and buyer-path smoke are documented as production evidence.
- Trust page now links enterprise buyers to the API security and observability packet.

### v1 alpha docs (Shipped)
Docs were made easier to find from navigation, API product CTAs, redirects, sitemap, OpenAPI, and AI-readable docs files.
- Public docs entry added to the main navigation.
- Legacy docs, docs/api, developer, developers, and reference URLs redirect to /api-docs or the endpoint reference section.
- robots.txt and sitemap.xml expose public docs, API metadata, security.txt, and AI-readable docs while paid route prefixes remain crawler-blocked.
- llms.txt and llms-full.txt publish API context for AI coding assistants.
- OpenAPI, endpoint index, status, changelog, and webhook contract are linked together.

### v1 alpha foundation (Live beta)
Business API routes, OpenAPI, console, API Lab, billing surface, usage ledger, async world-signal jobs, and SDK source are in place.
- Standard request envelope and error envelope established.
- Core compute and AI billing lanes separated.
- Convex usage ledger records request id, endpoint, credits, lane, and model metadata.
- Node and Python source clients are available before package publication.

### self-serve beta (Next)
Publish SDK packages, generated endpoint pages, stronger examples, and buyer-path onboarding once release approval is complete.
- Publish npm and PyPI packages after approval.
- Generate typed clients from the OpenAPI contract.
- Add CI contract tests for SDK examples.
- Expand docs by partner vertical and endpoint use case.

### enterprise beta (Planned)
Ship signed partner webhooks, public status/incident history, audit exports, private contracts, allowlists, and custom endpoint templates.
- Signed webhook delivery worker and replay-safe verification docs.
- Public status and incident history backed by internal readiness checks.
- Downloadable audit exports, audit retention terms, and security documentation.
- Private contract controls for custom limits and dedicated evals.

## Partner Webhook Contract

Partner-facing delivery is roadmap/enterprise work until the signed callback worker ships. Contract discovery is public at https://theleokingai.com/api/v1/webhooks.

### world_signal.job.completed
- Status: next
- Category: async_job
- Delivery: Signed HTTPS POST
- When: After async job completion and usage write confirmation.
- Payload fields: id, type, created_at, request_id, job_id, status, data, usage, meta
- Idempotency: Use event id as the webhook idempotency key.
- Signature: TheLeoKing-Signature: t=<unix_seconds>,v1=<hex HMAC-SHA256 over timestamp.raw_body>.
- Retry: Planned exponential retry with dead-letter visibility after final failure.

### world_signal.job.failed
- Status: next
- Category: async_job
- Delivery: Signed HTTPS POST
- When: After terminal failed status is written.
- Payload fields: id, type, created_at, request_id, job_id, status, error
- Idempotency: Use event id as the webhook idempotency key.
- Signature: TheLeoKing-Signature: t=<unix_seconds>,v1=<hex HMAC-SHA256 over timestamp.raw_body>.
- Retry: Planned exponential retry with dead-letter visibility after final failure.

### usage.recorded
- Status: next
- Category: usage
- Delivery: Signed HTTPS POST
- When: After the usage ledger accepts the request event.
- Payload fields: id, type, created_at, request_id, endpoint, lane, credits, model, tokens
- Idempotency: Deduplicate on request_id plus event type.
- Signature: TheLeoKing-Signature: t=<unix_seconds>,v1=<hex HMAC-SHA256 over timestamp.raw_body>.
- Retry: Planned retry only after ledger write succeeds.

### quality.failed
- Status: next
- Category: quality
- Delivery: Signed HTTPS POST
- When: After model/schema/output validation fails for an AI route.
- Payload fields: id, type, created_at, request_id, endpoint, quality_gate, error
- Idempotency: Deduplicate on request_id plus quality_gate.
- Signature: TheLeoKing-Signature: t=<unix_seconds>,v1=<hex HMAC-SHA256 over timestamp.raw_body>.
- Retry: Planned low retry count because this is diagnostic, not a user deliverable.

### entitlement.updated
- Status: enterprise
- Category: entitlement
- Delivery: Signed HTTPS POST
- When: After customer entitlement state is committed.
- Payload fields: id, type, created_at, organization_id, plan, endpoint_access, limits
- Idempotency: Deduplicate on event id and organization id.
- Signature: TheLeoKing-Signature: t=<unix_seconds>,v1=<hex HMAC-SHA256 over timestamp.raw_body>.
- Retry: Planned retry until partner acknowledges or event moves to dead letter.

### billing.subscription.updated
- Status: enterprise
- Category: billing
- Delivery: Signed HTTPS POST
- When: After billing provider webhook processing updates local entitlement state.
- Payload fields: id, type, created_at, organization_id, subscription_status, plan, effective_at
- Idempotency: Deduplicate on provider event id plus organization id.
- Signature: TheLeoKing-Signature: t=<unix_seconds>,v1=<hex HMAC-SHA256 over timestamp.raw_body>.
- Retry: Planned retry after internal billing state is consistent.

## Error Catalog

Public JSON: https://theleokingai.com/api/v1/errors

- 400 INVALID_REQUEST: The request body failed schema validation, JSON parsing, or endpoint-specific preconditions. Retryable: no. Partner action: Fix the payload shape, enum value, required field, or request body before retrying.
- 401 AUTH_REQUIRED: The request did not include an API key. Retryable: no. Partner action: Send x-api-key from a trusted server environment. Do not expose keys in browser code.
- 401 AUTH_INVALID: The supplied API key could not be validated. Retryable: no. Partner action: Check the key prefix, rotate compromised keys, and verify the target environment.
- 402 CREDITS_EXHAUSTED: The key or workspace does not have enough credits for the requested endpoint. Retryable: no. Partner action: Upgrade the plan, add credits, or switch to a lower-cost Core Compute route.
- 403 AUTH_FORBIDDEN: The key is valid but is not allowed to call this endpoint or billing lane. Retryable: no. Partner action: Use a key scoped for this endpoint or upgrade to the required plan.
- 404 NOT_FOUND: The requested resource, usually an async job id, was not found for this key. Retryable: no. Partner action: Verify the job id, environment, API key, and whether the job belongs to the same workspace.
- 409 IDEMPOTENCY_CONFLICT: The same Idempotency-Key was reused with a different request body. Retryable: no. Partner action: Reuse idempotency keys only for the same logical operation and identical request payload.
- 429 RATE_LIMITED: The request exceeded the current key, plan, endpoint, or environment rate limit. Retryable: yes. Partner action: Back off, retry later, reduce concurrency, or request enterprise limits.
- 502 INVALID_RESPONSE: A model, sidecar, RAG, or generation path failed the response contract or quality gate. Retryable: yes. Partner action: Retry with the same Idempotency-Key only if the original request did not produce a billable success.
- 502 UPSTREAM_FAILED: A required upstream provider, sidecar, or internal service failed before a valid API response was produced. Retryable: yes. Partner action: Retry after a delay or use async jobs for longer-running work.
- 503 SERVER_MISCONFIGURED: A required production environment variable, provider mode, or internal integration is missing or malformed. Retryable: no. Partner action: Treat as a platform incident and contact support with request_id.

## Importable Tooling

- Postman Collection v2.1: https://theleokingai.com/api/v1/postman
- Required collection variables: baseUrl, apiKey
- Paid routes require x-api-key. POST routes include Idempotency-Key.

## Product Families

### Experience APIs
Productized spiritual experiences that partners can drop into apps, creator platforms, membership funnels, and media workflows.
- /v1/experiences/future-partner-vision
- /v1/experiences/love-reveal
- /v1/experiences/crystal-ball
- /v1/tarot/draw
- /v1/oracle/ask
- /v1/past-life/reading

### Relationship APIs
Dating, compatibility, synastry, and 5-7-8 love intelligence built on owned chart math plus David Palmer's relationship frameworks.
- /v1/charts/synastry
- /v1/compatibility/score
- /v1/experiences/love-reveal
- /v1/experiences/future-partner-vision

### Chart Core APIs
Owned geocentric tropical calculations for natal, transits, synastry, composite, solar return, progressions, geo, and timezone workflows.
- /v1/charts/natal
- /v1/charts/current-sky
- /v1/charts/transits
- /v1/charts/synastry
- /v1/lunar/phase

### World Intelligence APIs
Beyond The Veil style mundane forecasting, hot zones, timing windows, and event analysis with deterministic ephemeris context.
- /v1/world/signals/jobs
- /v1/world/signals
- /v1/mundane/hot-zones
- /v1/mundane/analyze-event
- /v1/timing/windows

### Proprietary Knowledge APIs
Michael Erlewine StarTypes, source attribution, spiritual knowledge, love frameworks, and retrieval-backed interpretation layers.
- /v1/helio/patterns

## Billing Lanes

### Core Compute
No-AI astrology infrastructure: geocentric tropical chart math, transit tables, synastry scoring, compatibility scoring, and helio tropical StarTypes lookup.

Cost basis: Lowest-cost path for high-volume chart facts, compatibility checks, timing context, and product workflows that do not need generated interpretation.

Credit policy: 1-4 core credits per request. Usage tracks endpoint, request id, and credit spend without generative AI token charges.

Endpoints:
- /v1/charts/natal
- /v1/charts/current-sky
- /v1/charts/transits
- /v1/charts/synastry
- /v1/lunar/phase
- /v1/compatibility/score
- /v1/helio/patterns

### AI Intelligence
Premium interpretation routes that combine owned astrology math, curated spiritual context, product-specific prompts, and polished synthesis.

Cost basis: Premium path for polished, display-ready spiritual products and partner experiences.

Credit policy: 4-10 AI credits per completed response. Incomplete or rejected responses are not treated as successful billable output.

Endpoints:
- /v1/audience/insights
- /v1/experiences/future-partner-vision
- /v1/experiences/love-reveal
- /v1/experiences/crystal-ball
- /v1/oracle/ask
- /v1/tarot/draw
- /v1/past-life/reading
- /v1/horoscope/daily
- /v1/timing/windows

### World Signals
High-value mundane astrology and BTV intelligence for markets, culture, geopolitics, and timing windows.

Cost basis: Premium forecast path with world-event context, timing intelligence, citations, freshness checks, and reviewed output contracts.

Credit policy: 5+ AI credits per forecast, higher for deep async jobs. Only completed, structured forecast outputs are billed as successful results.

Endpoints:
- /v1/world/signals
- /v1/world/signals/jobs
- /v1/mundane/hot-zones
- /v1/mundane/analyze-event

### Enterprise Licensing
Custom API bundles, private model/data contracts, dedicated evals, partner-specific endpoint design, and negotiated usage minimums.

Cost basis: Sales-led margin model with committed usage, separate high-cost media AI terms, and partner-specific observability.

Credit policy: Custom credit blocks, SLA, overage terms, and private deployment options.

Endpoints:
- /v1/custom/*
- /v1/enterprise/*

## Pricing Tiers

### Core Compute
- Internal plan: core
- Clerk plan slug: core
- Price: $99/mo
- Credits: 5000
- Limit: 80 requests/min
- Best for: Teams that want the lowest-cost production astrology compute lane without AI spend.
- AI policy: No generative AI is included. Core routes record core credits only and avoid token-based usage charges.

### Basic
- Internal plan: developer
- Clerk plan slug: basic
- Price: $199/mo
- Credits: 10000
- Limit: 120 requests/min
- Best for: Small apps, creators, and pilot integrations.
- AI policy: Core routes avoid generative AI. Light AI routes are opt-in and consume 4-8 AI credits per completed response.

### Pro
- Internal plan: growth
- Clerk plan slug: pro
- Price: $799/mo
- Credits: 50000
- Limit: 240 requests/min
- Best for: Paid apps, agencies, dating/wellness products, and media workflows.
- AI policy: Designed for regular AI endpoint use with usage reviewed by endpoint and product lane.

### Business
- Internal plan: scale
- Clerk plan slug: business
- Price: $2,500/mo
- Credits: 200000
- Limit: 600 requests/min
- Best for: B2B platforms, commerce datasets, large newsletters, and enterprise pilots.
- AI policy: Built for heavy AI usage with cost review before custom content generation expansion.

### Enterprise
- Internal plan: enterprise
- Clerk plan slug: enterprise
- Price: Custom, $10k+/mo target
- Credits: 1000000
- Limit: 1200 requests/min
- Best for: Strategic partners, AI platforms, dating networks, media networks, and licensing deals.
- AI policy: Custom credit pricing, committed usage, and separate terms for high-cost media generation products.

## Endpoint Reference

### POST /v1/audience/insights
- Name: Audience Intelligence
- Status: live
- Group: intelligence
- Credits: 2 credits per customer
- Local path: /api/v1/audience/insights
- Purpose: Generate customer-level buyer archetypes, campaign fit, timing notes, and message angles from birth data and campaign context.
- Inputs: customer birth data, campaign context, channel, tone, product category
- Outputs: buyer archetype, campaign fit score, send/no-send recommendation, message angle, chart quality
- Tool functions: customer.profile.score, campaign.fit.evaluate, message.angle.generate, chart.quality.report, erlewine.context.attach

### POST /v1/experiences/future-partner-vision
- Name: Future Partner Vision
- Status: alpha
- Group: experiences
- Credits: 8 credits per vision
- Local path: /api/v1/experiences/future-partner-vision
- Purpose: Generate a structured future partner profile, relationship scene, attraction pattern, timing window, and optional image prompt from birth data and love context.
- Inputs: birth data, relationship intent, orientation/context, optional photo signal, optional transit window
- Outputs: future partner archetype, meeting scene, chemistry signals, timing windows, image prompt, quality metadata
- Tool functions: partner.vision.generate, love.signature.extract, timing.romance.window, image.prompt.partner, quality.experience.enforce

### POST /v1/experiences/love-reveal
- Name: Love Reveal
- Status: alpha
- Group: experiences
- Credits: 5 credits per reveal
- Local path: /api/v1/experiences/love-reveal
- Purpose: Generate a high-specificity love reading that can blend psychic interpretation, tarot symbolism, owned astrology context, and 5-7-8 relationship logic.
- Inputs: question, relationship context, optional birth data, optional partner birth data, tone
- Outputs: direct answer, emotional dynamic, tarot/love archetypes, astrology support, next action
- Tool functions: love.reveal.generate, question.intent.classify, tarot.symbols.attach, relationship.context.ground

### POST /v1/experiences/crystal-ball
- Name: Crystal Ball Vision
- Status: alpha
- Group: experiences
- Credits: 4 credits per vision
- Local path: /api/v1/experiences/crystal-ball
- Purpose: Generate a cinematic symbolic vision with concrete interpretation, action guidance, and optional image-generation direction.
- Inputs: question, topic, optional birth data, desired tone, visual intensity
- Outputs: vision scene, symbol meanings, prediction or guidance, action line, image prompt
- Tool functions: vision.crystal.generate, symbols.interpret, image.prompt.crystal

### POST /v1/oracle/ask
- Name: Oracle Ask
- Status: alpha
- Group: experiences
- Credits: 2 credits per answer
- Local path: /api/v1/oracle/ask
- Purpose: Answer a direct spiritual question through the paid Lady Avalon API path with strict JSON output, usage metering, and no legacy MCP dependency.
- Inputs: question, topic, optional birth date, situation context, desired tone
- Outputs: direct answer, insight, support signals, next action, caution
- Tool functions: oracle.ask.generate, sun.sign.derive, quality.experience.enforce

### POST /v1/tarot/draw
- Name: Tarot Draw
- Status: alpha
- Group: experiences
- Credits: 2 credits per spread
- Local path: /api/v1/tarot/draw
- Purpose: Draw and interpret tarot spreads from the local 78-card Rider-Waite-Smith corpus with deterministic seed support and paid API metering.
- Inputs: question, spread type, topic, optional seed, image prompt flag
- Outputs: drawn cards, card readings, direct answer, synthesis, next action
- Tool functions: tarot.spread.draw, tarot.meanings.apply, tarot.output.lock

### POST /v1/past-life/reading
- Name: Past-Life Reading
- Status: alpha
- Group: experiences
- Credits: 10 credits per reading
- Local path: /api/v1/past-life/reading
- Purpose: Generate an AstraGate-style past-life reading with structured scene, karmic pattern, present-life echo, healing action, and empowerment.
- Inputs: optional birth data, question, focus, depth
- Outputs: lifetime theme, scene, karmic pattern, present-life echo, healing action
- Tool functions: pastlife.reading.generate, astragate.persona.apply, quality.experience.enforce

### POST /v1/charts/synastry
- Name: Synastry Chart
- Status: alpha
- Group: relationships
- Credits: 3 credits per pair
- Local path: /api/v1/charts/synastry
- Purpose: Return owned geocentric tropical synastry data and relationship aspect overlays without calling an external astrology API.
- Inputs: subject birth data, partner birth data, orb policy, max aspects
- Outputs: interchart aspects, relationship signals, calculation basis, sidecar metadata
- Tool functions: chart.synastry.calculate, interchart.aspects.rank, relationship.signals.extract, calculation.basis.report

### POST /v1/compatibility/score
- Name: Compatibility Score
- Status: alpha
- Group: relationships
- Credits: 4 credits per pair
- Local path: /api/v1/compatibility/score
- Purpose: Score relationship compatibility using synastry, 5-7-8 house activation, love-planet frameworks, and optional StarTypes background comparison.
- Inputs: two birth profiles, relationship context, scoring profile, optional helio background flag
- Outputs: overall score, 5/7/8 sub-scores, chemistry, commitment, risk flags, interpretation
- Tool functions: compatibility.score.calculate, love.578.evaluate, synastry.signals.weight, helio.background.compare

### POST /v1/charts/natal
- Name: Natal Chart Calculation
- Status: alpha
- Group: charts
- Credits: 2 credits per chart
- Local path: /api/v1/charts/natal
- Purpose: Return a geocentric tropical natal chart from the Kerykeion/Swiss sidecar for partners that need raw chart data, not generated interpretation.
- Inputs: subject id, date of birth, time of birth, place or coordinates
- Outputs: sun sign, raw chart payload, calculation basis, sidecar metadata
- Tool functions: chart.natal.calculate, planet.positions.list, houses.resolve, aspects.list, birth.input.validate

### POST /v1/charts/transits
- Name: Transit Chart Calculation
- Status: alpha
- Group: charts
- Credits: 2 credits per chart
- Local path: /api/v1/charts/transits
- Purpose: Return geocentric tropical transit positions and aspects from the owned sidecar for timing, daily horoscope, and ephemeris workflows.
- Inputs: transit datetime, transit location, max aspects
- Outputs: transit chart, ranked aspects, calculation basis, sidecar metadata
- Tool functions: chart.transits.calculate, transit.positions.list, transit.aspects.rank, mundane.signal.seed, daily.horoscope.seed

### POST /v1/charts/current-sky
- Name: Current Sky
- Status: alpha
- Group: charts
- Credits: 1 credit per lookup
- Local path: /api/v1/charts/current-sky
- Purpose: Return the owned geocentric tropical current-sky chart for a supplied moment and location without calling external astrology APIs.
- Inputs: datetime, location or coordinates, house system, active points
- Outputs: planet positions, house cusps, aspects, lunar phase, supported and unsupported western lanes
- Tool functions: chart.current_sky.calculate, planet.positions.list, houses.resolve, lunar.phase.extract

### POST /v1/lunar/phase
- Name: Lunar Phase
- Status: alpha
- Group: charts
- Credits: 1 credit per lookup
- Local path: /api/v1/lunar/phase
- Purpose: Return first-party Sun-Moon lunar phase context for a supplied moment and location without horoscope prose or third-party fallback.
- Inputs: datetime, location or coordinates, house system
- Outputs: lunar phase, Sun position, Moon position, calculation basis
- Tool functions: lunar.phase.calculate, planet.positions.list, calculation.basis.report

### POST /v1/horoscope/daily
- Name: Daily Horoscope
- Status: alpha
- Group: intelligence
- Credits: 1 credit per sign or subject
- Local path: /api/v1/horoscope/daily
- Purpose: Generate personalized daily horoscope output from owned transit substrate, zodiac knowledge, and optional birth profile context.
- Inputs: zodiac sign or birth data, date, tone, delivery channel
- Outputs: daily theme, transit drivers, love/career/money notes, action guidance, metadata
- Tool functions: horoscope.daily.generate, transit.daily.seed, zodiac.knowledge.apply

### POST /v1/timing/windows
- Name: Timing Windows
- Status: alpha
- Group: intelligence
- Credits: 3 credits per run
- Local path: /api/v1/timing/windows
- Purpose: Generate practical timing windows for launches, love, career, money, content, and spiritual work using owned transit substrate.
- Inputs: topic, date range, objective, optional birth data, max windows
- Outputs: ranked windows, astrology signal, best use, caution, strategy
- Tool functions: timing.windows.generate, transit.window.seed, strategy.timing.apply

### POST /v1/world/signals
- Name: World Signals
- Status: live
- Group: intelligence
- Credits: 5 credits per forecast
- Local path: /api/v1/world/signals
- Purpose: Generate Beyond The Veil style mundane intelligence with deterministic ephemeris context, BTV RAG metadata, and quality controls.
- Inputs: topic, window days, depth, BTV corpus, Erlewine mundane context, transit ephemeris
- Outputs: forecast headline, signature stack, historical analog, manifestations, quality metadata
- Tool functions: mundane.forecast.generate, ephemeris.transits.rank, signature.stack.apply, historical.analog.select, quality.gates.enforce

### POST /v1/world/signals/jobs
- Name: World Signals Async Job
- Status: live
- Group: intelligence
- Credits: reserves 5 credits; charges only on complete forecast
- Local path: /api/v1/world/signals/jobs
- Purpose: Create an asynchronous Beyond The Veil world signal forecast job for deep production use, then poll the job URL until the quality-gated forecast is complete.
- Inputs: topic, window days, depth, idempotency key, scoped API key
- Outputs: job id, status URL, reserved credits, job status, completed forecast envelope
- Tool functions: mundane.forecast.job.create, credits.reserve, job.status.poll, mundane.forecast.generate, usage.bill.on_success

### POST /v1/mundane/hot-zones
- Name: Mundane Hot Zones
- Status: alpha
- Group: intelligence
- Credits: 5 credits per run
- Local path: /api/v1/mundane/hot-zones
- Purpose: Rank supplied regions as Beyond The Veil style hot zones for a topic and time window using owned transit context and structured generation.
- Inputs: topic, regions, window days, depth
- Outputs: regional scores, signals, likely manifestations, watch items, synthesis
- Tool functions: hotzones.score, mundane.region.rank, watch.items.generate

### POST /v1/mundane/analyze-event
- Name: Mundane Event Analysis
- Status: alpha
- Group: intelligence
- Credits: 4 credits per analysis
- Local path: /api/v1/mundane/analyze-event
- Purpose: Analyze a supplied world event through mundane astrology and return forward-looking implications, analogs, watch windows, and action guidance.
- Inputs: event, event date, location, topic, window days
- Outputs: event summary, signature stack, analogs, forecast implications, watch window
- Tool functions: mundane.event.analyze, event.signature.extract, forecast.implications.generate

### POST /v1/helio/patterns
- Name: Helio Tropical StarTypes
- Status: background
- Group: helio
- Credits: 1 credit per subject
- Local path: /api/v1/helio/patterns
- Purpose: Lookup heliocentric tropical StarTypes patterns with attribution to Michael Erlewine's contributions, source work, and interpretations as a background/evaluation signal.
- Inputs: subject id, birth date, experiment context
- Outputs: pattern code, pattern signature, components, Michael Erlewine attribution, guardrails
- Tool functions: startypes.lookup, helio.pattern.components, erlewine.source.credit, background.signal.guard

### POST /v1/knowledge/erlewine/context
- Name: Erlewine Context
- Status: planned
- Group: knowledge
- Credits: 1 credit per retrieval
- Local path: /api/v1/knowledge/erlewine/context
- Purpose: Retrieve rights-cleared Michael Erlewine context for controlled interpretation workflows without exposing raw archive internals.
- Inputs: query, endpoint target, rights bucket, top k, source filters
- Outputs: context chunks, source credits, rights metadata, safe summary seeds
- Tool functions: erlewine.context.search, source.credit.format, rights.bucket.filter


## Tool Families

### Experience Generation
Future Partner Vision, Love Reveal, Crystal Ball, tarot, and oracle experiences as product APIs.
- oracle.ask.generate
- partner.vision.generate
- love.reveal.generate
- vision.crystal.generate
- pastlife.reading.generate
- tarot.spread.draw
- tarot.symbols.attach
- quality.experience.enforce

### Owned Chart Core
Geocentric tropical natal, transits, synastry, composite, solar return, progressions, geo, and timezone functions.
- chart.natal.calculate
- chart.current_sky.calculate
- chart.transits.calculate
- chart.synastry.calculate
- lunar.phase.calculate
- chart.composite.calculate
- chart.solar_return.calculate
- chart.progressions.calculate
- geo.timezone.resolve

### Relationship Intelligence
Compatibility scoring built from synastry, 5-7-8 house overlays, love planets, and risk flags.
- compatibility.score.calculate
- love.578.evaluate
- synastry.signals.weight
- relationship.signals.extract
- helio.background.compare

### Business Intelligence
Audience, campaign, and partner intelligence functions built on chart context plus controlled generation.
- customer.profile.score
- campaign.fit.evaluate
- message.angle.generate
- chart.quality.report
- timing.windows.generate
- quality.gates.enforce

### Mundane Forecasting
Beyond The Veil style world-signal functions with deterministic ephemeris and RAG controls.
- mundane.forecast.generate
- mundane.event.analyze
- ephemeris.transits.rank
- signature.stack.apply
- historical.analog.select
- hotzones.score
- watch.items.generate

### Helio StarTypes
Heliocentric tropical Michael Erlewine StarTypes lookup as a background experimental signal.
- startypes.lookup
- helio.pattern.components
- erlewine.source.credit
- background.signal.guard

### Knowledge Retrieval
Curated spiritual, love, mundane, past-life, and Erlewine source context for endpoint-specific synthesis.
- erlewine.context.search
- spiritual.kb.search
- love.framework.retrieve
- btv.article.retrieve
- source.credit.format