Getting started

This walk-through ends with a real natal chart + talent profile in your terminal. Roughly five minutes if you already have a token.

On Python or TypeScript? Use the official SDK instead — typed requests, typed responses, typed errors, streaming, automatic retries. See SDKs and snippets for the install commands and a quickstart in each language. The cURL flow below is the "any language" path and stays useful for debugging.

1. Authenticate

The API verifies tokens issued by your identity provider (JWKS) or signed with a static RS256 / ES256 / EdDSA public key. See Authentication for the full flow.

For dev / staging you'll be issued a bearer token directly. Export it:

export ASTRO_TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

2. Create a chart

If you only have a place name, resolve it first:

curl "https://api.astrolinkers.com/v1/geolocation/places?query=Novosibirsk" \
    -H "Authorization: Bearer $ASTRO_TOKEN"

Use the selected candidate's latitude, longitude, and timezone when asking the user to confirm the final birth moment.

POST /v1/charts accepts a birth moment + lat/lon and returns a fully computed chart — planets in signs, house cusps, ayanamsha applied if Vedic.

curl -X POST https://api.astrolinkers.com/v1/charts \
    -H "Authorization: Bearer $ASTRO_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "birth": {
            "moment": "1984-12-21T18:16:00+07:00",
            "latitude": 55.0084,
            "longitude": 82.9357
        },
        "system": "western",
        "house_system": "placidus"
    }'

Response (abridged):

{
    "id": "019e32b5-99da-71e3-a198-1fcea798e912",
    "system": "western",
    "house_system": "placidus",
    "ayanamsha": null,
    "computed_at": "2026-05-16T21:28:45.199836Z",
    "birth": { "moment": "1984-12-21T18:16:00+07:00", "latitude": 55.0084, "longitude": 82.9357 },
    "planets": [
        { "planet": "sun",  "sign": "sagittarius", "longitude": 269.78, "degree_in_sign": 29.78, "speed_per_day": 1.0149, "is_retrograde": false },
        { "planet": "moon", "sign": "sagittarius", "longitude": 256.63, "degree_in_sign": 16.63, "speed_per_day": 14.31, "is_retrograde": false }
    ],
    "houses": [
        { "house": 1, "sign": "cancer", "longitude": 106.78 }
    ]
}

Save the id — you'll use it everywhere else.

export CHART_ID="019e32b5-99da-71e3-a198-1fcea798e912"

3. Get the talent profile

GET /v1/charts/{id}/profile/talent returns the per-skill score breakdown derived from a deterministic rule ontology.

curl https://api.astrolinkers.com/v1/charts/$CHART_ID/profile/talent \
    -H "Authorization: Bearer $ASTRO_TOKEN"

{
    "chart_id": "019e32b5-...",
    "scores": [
        { "skill_id": "sales_negotiation", "value": 0.50, "contributing_rules": ["mercury_in_fire_sales", "venus_in_air_sales"] },
        { "skill_id": "resilience",        "value": 0.45, "contributing_rules": ["mars_in_fixed_resilience", "saturn_in_water_resilience"] },
        { "skill_id": "management",        "value": 0.25, "contributing_rules": ["jupiter_in_earth_management"] }
    ]
}

Every score carries contributing_rules so you can explain why a skill came out where it did — no black box.

4. Generate a written interpretation

POST /v1/interpretations composes statements from a template library — one per skill, with kind chosen by the band the score falls into (strength ≥ 0.6, recommendation 0.4–0.59, risk < 0.4).

curl -X POST https://api.astrolinkers.com/v1/interpretations \
    -H "Authorization: Bearer $ASTRO_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{
        \"chart_id\": \"$CHART_ID\",
        \"locale\": \"en\",
        \"tone\": \"corporate\",
        \"use_llm_rewrite\": false
    }"

Set use_llm_rewrite: true to let the configured LLM provider rephrase the templates in the chosen tone (corporate, coach, plain, vedic_traditional). Costs are tracked per tenant — see LLM cost caps.

5. Order a PDF report (async)

PDF rendering is offloaded to a worker. The endpoint returns immediately with status: pending and an id you poll until the artifact is ready.

REPORT=$(curl -X POST https://api.astrolinkers.com/v1/reports \
    -H "Authorization: Bearer $ASTRO_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"chart_id\": \"$CHART_ID\", \"profile\": \"natal_basic\", \"format\": \"pdf\"}")
echo "$REPORT" | jq -r .id

Poll:

curl https://api.astrolinkers.com/v1/reports/$REPORT_ID \
    -H "Authorization: Bearer $ASTRO_TOKEN"

When status == "ready" the body carries an artifact_url — a short-lived signed URL for the rendered PDF.

Next steps

• Skip the raw HTTP by using an official SDK (Python or TypeScript).
• Read the endpoint reference for full request / response schemas.
• Read Errors for the uniform error envelope.
• Read Rate limits for per-tenant quotas and the LLM cost cap that backs the paid tier.