POSTbackgroundHelio Tropical

Helio Tropical StarTypes

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

POST /v1/helio/patternsQuickstart OpenAPI JSON

Credits

1 credit per subject

Minimum Plan

Core Compute+

Billing Lane

No AI core

SDK Helper

helioPatterns / helio_patterns

Inputs

+subject id
+birth date
+experiment context

Outputs

+pattern code
+pattern signature
+components
+Michael Erlewine attribution
+guardrails

Tool Functions

Capabilities behind this endpoint

4 functions

startypes.lookup

Looks up the date-level helio tropical StarTypes row.

helio.pattern.components

Returns pattern components, color code, and geometry labels.

erlewine.source.credit

Returns public source credit and rights bucket metadata.

background.signal.guard

Labels StarTypes as experimental background context only.

StarTypes Lookup request

{
  "subjects": [
    { "id": "subject_123", "dob": "1990-07-23" }
  ],
  "context": {
    "use_case": "audience segmentation experiment"
  }
}

StarTypes Lookup 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": { "lane": "core", "credits": 1, "billableUnits": 1 }
}

curl

curl https://theleokingai.com/api/v1/helio/patterns \
  -X POST \
  -H "Accept: application/json" \
  -H "x-api-key: $LEOKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: helio-startypes-subject-123-v1" \
  -d '{
  "subjects": [
    { "id": "subject_123", "dob": "1990-07-23" }
  ],
  "context": {
    "use_case": "audience segmentation experiment"
  }
}'

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.helioPatterns(
  {
  "subjects": [
    { "id": "subject_123", "dob": "1990-07-23" }
  ],
  "context": {
    "use_case": "audience segmentation experiment"
  }
},
  "helio-startypes-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.helio_patterns(
    {
        "subjects": [
            {
                "id": "subject_123",
                "dob": "1990-07-23",
            },
        ],
        "context": {
            "use_case": "audience segmentation experiment",
        },
    },
    idempotency_key="helio-startypes-subject-123-v1",
)

print(result["request_id"])
print(result["usage"]["credits"])

Error Behavior

HTTP	Code	Partner Action
400	`INVALID_REQUEST`	Fix the payload shape, enum value, required field, or request body before retrying.
401	`AUTH_REQUIRED`	Send x-api-key from a trusted server environment. Do not expose keys in browser code.
401	`AUTH_INVALID`	Check the key prefix, rotate compromised keys, and verify the target environment.
402	`CREDITS_EXHAUSTED`	Upgrade the plan, add credits, or switch to a lower-cost Core Compute route.
403	`AUTH_FORBIDDEN`	Use a key scoped for this endpoint or upgrade to the required plan.
404	`NOT_FOUND`	Verify the job id, environment, API key, and whether the job belongs to the same workspace.
409	`IDEMPOTENCY_CONFLICT`	Reuse idempotency keys only for the same logical operation and identical request payload.
429	`RATE_LIMITED`	Back off, retry later, reduce concurrency, or request enterprise limits.