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. Get an API key

1. Sign up at app.astrolinkers.com and confirm your e-mail.
2. In the dashboard, create an API key and copy it — it is shown once.
3. Export it:

export ASTROLINKERS_API_KEY="ak_live_..."

Every request sends it as a bearer token. The Free plan is enough for this guide and may be used in commercial products within its limits (Rate limits, Terms). See Authentication for scopes.

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 $ASTROLINKERS_API_KEY"

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 $ASTROLINKERS_API_KEY" \
    -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 ten talents, each scored by how strongly the chart carries the talent's graha.

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

{
    "chart_id": "019e32b5-...",
    "scores": [
        { "skill_id": "drive",         "value": 1.0,   "level": "very_high", "lead_planet": "mars",    "contributing_rules": ["mars_able_drive"] },
        { "skill_id": "communication", "value": 0.5,   "level": "moderate",  "lead_planet": "mercury", "contributing_rules": ["jupiter_in_air_communication", "moon_in_air_communication"] },
        { "skill_id": "leadership",    "value": 0.343, "level": "low",       "lead_planet": "sun",     "contributing_rules": [] }
    ]
}

Every score names its lead_planet and the rules that fired (contributing_rules, with descriptions in evidence), so you can explain why a talent came out where it did.

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 $ASTROLINKERS_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
        \"chart_id\": \"$CHART_ID\",
        \"locale\": \"en\",
        \"tone\": \"corporate\",
        \"use_llm_rewrite\": false
    }"

On paid plans, use_llm_rewrite: true lets an LLM rephrase the templates in the chosen tone (corporate, coach, plain, vedic_traditional). On Free it answers 403 plan_feature_unavailable — see Paid (LLM) endpoints.

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 $ASTROLINKERS_API_KEY" \
    -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 $ASTROLINKERS_API_KEY"

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.