The Leo King API Docs

Developer documentation for selling and integrating the Business API: auth, credits, payloads, idempotency, error handling, and endpoint contracts.

OpenAPI JSONCustomer Console
Quick StartAuthenticationEndpointsErrors

Quick Start

Every request is server-to-server, authenticated with `x-api-key`, and tracked through successful usage events. Use an idempotency key for retries.

curl
curl https://api.theleokingai.com/v1/audience/insights \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: $LEOKING_API_KEY" \
  -H "Idempotency-Key: campaign-2026-06-15-cust-123" \
  -d '{
    "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"
    }
  }'
Node fetch
const response = await fetch("https://api.theleokingai.com/v1/world/signals", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.LEOKING_API_KEY,
    "Idempotency-Key": "world-signals-markets-2026-06-15"
  },
  body: JSON.stringify({
    topic: "markets",
    window_days: 14,
    depth: "deep"
  })
});

if (!response.ok) {
  throw new Error(await response.text());
}

const payload = await response.json();

Authentication

Customer login uses Clerk for the console. API calls use scoped API keys because partner apps call these routes from trusted backends, not browsers.

Production Gateway
https://api.theleokingai.com

Use this once the production API domain is mapped.

Website API
https://www.theleokingai.com/api

Same Next.js API routes through the public website host.

Local Development
http://localhost:3000/api

Local Next.js development server.

Headers
  • Content-Type: application/json
  • x-api-key: lk_live_...
  • Idempotency-Key: stable-retry-key

Endpoints

These are the business-facing endpoint names. The API does not call AstrologyAPI. Deterministic chart, helio lookup, ephemeris, local RAG, and model quality gates are owned by this stack.

POST/v1/audience/insights2 credits per customer

Audience Insights

Generate customer-level buyer archetypes, campaign fit, timing notes, and message angles from birth data and campaign context.

1-50 customers per request
dob is required
tob/pob or coordinates improve chart quality
Request
{
  "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"
  }
}
Response
{
  "request_id": "req_...",
  "data": {
    "results": [
      {
        "customer_id": "cust_123",
        "personality": {
          "sun_sign": "Leo",
          "buyer_archetype": "premium loyalist"
        },
        "campaign_fit": {
          "score": 0.86,
          "send": true,
          "reasoning": "High receptivity window"
        }
      }
    ]
  },
  "usage": {
    "credits": 2,
    "billableUnits": 1
  },
  "meta": {
    "model": "gpt-5.4-mini"
  }
}
POST/v1/world/signals5 credits per forecast

World Signals

Generate Beyond The Veil style mundane intelligence with deterministic ephemeris context, BTV RAG metadata, and quality controls.

topic must match the supported set
window_days supports 1-90
depth supports surface through rabbit_hole
Request
{
  "topic": "markets",
  "window_days": 14,
  "depth": "deep"
}
Response
{
  "request_id": "req_...",
  "data": {
    "forecasts": [
      {
        "headline": "Markets hold a volatile repricing window",
        "forecast_window": {
          "start": "2026-06-15",
          "end": "2026-06-29",
          "specificity": "two-week window"
        },
        "confidence": 7
      }
    ]
  },
  "usage": {
    "credits": 5,
    "billableUnits": 1
  },
  "meta": {
    "model": "gpt-5.4-mini",
    "ephemeris": {
      "enabled": true,
      "mode": "required"
    }
  }
}
POST/v1/helio/patterns1 credit per subject

Helio Patterns

Lookup heliocentric tropical StarTypes patterns with attribution to Michael Erlewine's contributions, source work, and interpretations as a background/evaluation signal.

1-50 subjects per request
dob is required
date-level short lookup; birth time and location are not used
Request
{
  "subjects": [
    {
      "id": "subject_123",
      "dob": "1990-07-23"
    }
  ],
  "context": {
    "use_case": "audience segmentation experiment"
  }
}
Response
{
  "request_id": "req_...",
  "data": {
    "profiles": [
      {
        "subject_id": "subject_123",
        "calculation_basis": {
          "frame": "heliocentric",
          "zodiac": "tropical",
          "prediction_role": "background_evaluation"
        },
        "startype": {
          "pattern_code": "82",
          "pattern_signature": "8-B-TRINESQUARE/18-G-TRINE"
        }
      }
    ]
  },
  "usage": {
    "credits": 1,
    "billableUnits": 1
  },
  "meta": {
    "model": "startypes-short-helio-ephemeris-v1"
  }
}

Errors

Errors are returned as JSON envelopes with `request_id` so support, usage logs, and partner systems can trace failures without exposing secrets.

HTTPCodeMeaning
400INVALID_REQUESTRequest body failed schema validation or could not be parsed.
401AUTH_REQUIRED / AUTH_INVALIDMissing or invalid `x-api-key` header.
402CREDITS_EXHAUSTEDThe API key does not have enough credits for the request.
429RATE_LIMITEDToo many requests for the current key or environment policy.
502INVALID_RESPONSE / UPSTREAM_FAILEDGeneration, ephemeris, RAG, or usage logging failed quality gates.
Error envelope
{
  "request_id": "req_...",
  "error": {
    "code": "CREDITS_EXHAUSTED",
    "message": "Not enough credits for this request",
    "details": {
      "requiredCredits": 10,
      "creditsRemaining": 4
    }
  }
}

Production Notes

StarTypes now has a dedicated helio tropical endpoint, with Michael Erlewine's contributions, source work, and interpretations credited in the product surface. Keep it as a background/evaluation layer unless a future product explicitly promotes that signal after testing.

API OverviewAsk About Integration