POSTalphaChart Calculation

Natal Chart Calculation

Return a geocentric tropical natal chart from the Kerykeion/Swiss sidecar for partners that need raw chart data, not generated interpretation.

POST /v1/charts/natalQuickstartOpenAPI JSON
Credits

2 credits per chart

Minimum Plan

Core Compute+

Billing Lane

No AI core

SDK Helper

natalChart / natal_chart

Inputs
  • +subject id
  • +date of birth
  • +time of birth
  • +place or coordinates
Outputs
  • +sun sign
  • +raw chart payload
  • +calculation basis
  • +sidecar metadata
Tool Functions

Capabilities behind this endpoint

5 functions
chart.natal.calculate

Computes a full geocentric tropical natal chart.

planet.positions.list

Returns the sidecar planet/sign/degree payload when provided by the sidecar.

houses.resolve

Returns house data when provided by the configured sidecar response.

aspects.list

Returns natal aspect data when provided by the configured sidecar response.

birth.input.validate

Rejects requests missing time plus place or coordinates.

Full Natal Chart request
{
  "subject": {
    "id": "subject_123",
    "dob": "1990-07-23",
    "tob": "14:30",
    "pob": "New York, US"
  }
}
Full Natal Chart response
{
  "request_id": "req_...",
  "data": {
    "subject_id": "subject_123",
    "calculation_basis": {
      "frame": "geocentric",
      "zodiac": "tropical",
      "system": "Kerykeion sidecar"
    },
    "sun_sign": "Leo",
    "chart": { "planets": [], "houses": [], "aspects": [] }
  },
  "usage": { "lane": "core", "credits": 2, "billableUnits": 1 }
}
curl
curl https://theleokingai.com/api/v1/charts/natal \
  -X POST \
  -H "Accept: application/json" \
  -H "x-api-key: $LEOKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: natal-chart-subject-123-v1" \
  -d '{
  "subject": {
    "id": "subject_123",
    "dob": "1990-07-23",
    "tob": "14:30",
    "pob": "New York, US"
  }
}'
Node SDK
import { TheLeoKingApi } from "@theleoking/ai-api";

const api = new TheLeoKingApi({
  apiKey: process.env.LEOKING_API_KEY,
  baseUrl: "https://theleokingai.com/api"
});

const result = await api.natalChart(
  {
  "subject": {
    "id": "subject_123",
    "dob": "1990-07-23",
    "tob": "14:30",
    "pob": "New York, US"
  }
},
  "natal-chart-subject-123-v1"
);

console.log(result.request_id);
console.log(result.usage.credits);
Python SDK
import os
from theleoking_ai_api import TheLeoKingApi

api = TheLeoKingApi(
    api_key=os.environ["LEOKING_API_KEY"],
    base_url="https://theleokingai.com/api",
)

result = api.natal_chart(
    {
        "subject": {
            "id": "subject_123",
            "dob": "1990-07-23",
            "tob": "14:30",
            "pob": "New York, US",
        },
    },
    idempotency_key="natal-chart-subject-123-v1",
)

print(result["request_id"])
print(result["usage"]["credits"])
Error Behavior
HTTPCodePartner Action
400INVALID_REQUESTFix the payload shape, enum value, required field, or request body before retrying.
401AUTH_REQUIREDSend x-api-key from a trusted server environment. Do not expose keys in browser code.
401AUTH_INVALIDCheck the key prefix, rotate compromised keys, and verify the target environment.
402CREDITS_EXHAUSTEDUpgrade the plan, add credits, or switch to a lower-cost Core Compute route.
403AUTH_FORBIDDENUse a key scoped for this endpoint or upgrade to the required plan.
404NOT_FOUNDVerify the job id, environment, API key, and whether the job belongs to the same workspace.
409IDEMPOTENCY_CONFLICTReuse idempotency keys only for the same logical operation and identical request payload.
429RATE_LIMITEDBack off, retry later, reduce concurrency, or request enterprise limits.
Related Endpoints
POSTalpha
Transit Chart Calculation
/v1/charts/transits
POSTalpha
Current Sky
/v1/charts/current-sky
POSTalpha
Lunar Phase
/v1/lunar/phase