Швидкий старт

П’ять хвилин від реєстрації до повної натальної карти в JSON. Покриває install SDK, перший запит, заголовки відповіді, автентифікацію та обробку помилок.

// швидкий старт

Отримай API-ключ за 60 секунд

10 000 кредитів/міс назавжди безкоштовно. Без картки.

1. 01
   Зареєструйся

   Email + пароль. Один акаунт для всіх продуктів AstroWay.
2. 02
   Створи ключ

   У dashboard натисни «Створити ключ». aw_live_ або aw_test_ (пісочниця).
3. 03
   Зроби запит

   POST /v1/chart з header X-Api-Key. Повна натальна карта у JSON.

Зареєструватись — безкоштовно→Швидкий старт

1. Згенеруй API ключ

   Зайди в dashboard і натисни Generate key. Безкоштовний тариф дає 10 000 кредитів/міс назавжди — без введення картки. Ключі починаються з:

   • aw_live_* — production, реальні чарджі
   • aw_test_* — sandbox, без списання кредитів, детермінована відповідь

   Обережно

   Ключ — це секрет. Не комітіть його в git, не вставляйте у фронтенд-код. Для фронтенду використовуй проксі-backend або короткоживучі session-токени (Phase 3).

2. Постав SDK

   API — звичайний REST + JSON, тож SDK не обов’язковий. MCP сервер (@astroway/mcp) вже зрелізений для AI-агентських інтеграцій. TypeScript і Python SDK у roadmap (auto-gen з OpenAPI 3.1) — поки що native HTTP.

   cURL

   # SDK не потрібен — лише curl та ключ:
   export AW_KEY="aw_test_demo_replaceme"

   TypeScript

   # native fetch — Node 18+ або браузер. SDK у roadmap.
   # Альтернатива: openapi-typescript-codegen з нашого OpenAPI 3.1
   export AW_KEY="aw_test_demo_replaceme"

   Python

   pip install requests   # або httpx — SDK у roadmap
   export AW_KEY="aw_test_demo_replaceme"

   PHP

   composer require guzzlehttp/guzzle
   # SDK у roadmap, поки що — Guzzle + raw HTTP

   MCP

   # Для AI-агентів — Claude Desktop, Cursor IDE, Windsurf,
   # VS Code (llm CLI), GPT з MCP через OpenAI Realtime API,
   # або будь-який MCP-сумісний клієнт:
   npx -y @astroway/mcp   # 700+ tools, OpenAPI auto-sync

3. Зроби перший запит

   Розрахунок натальної карти для 24 серпня 1991, 16:30 EEST, Київ:

   cURL

   first-request.sh

   curl -X POST https://api.astroway.info/v1/chart \
     -H "X-Api-Key: $AW_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "date": "1991-08-24",
       "time": "16:30:00",
       "timezoneOffset": 3,
       "latitude": 50.4501,
       "longitude": 30.5234,
       "houseSystem": "P"
     }'

   TypeScript

   first-request.ts

   // native fetch — Node 18+ / Bun / Deno / browser. TS SDK у roadmap.
   const r = await fetch('https://api.astroway.info/v1/chart', {
     method: 'POST',
     headers: {
       'X-Api-Key': process.env.AW_KEY!,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({
       date: '1991-08-24',
       time: '16:30:00',
       timezoneOffset: 3,
       latitude: 50.4501,
       longitude: 30.5234,
       houseSystem: 'P',
     }),
   });
   
   const { data: chart } = await r.json();
   console.log(chart.planets[0]); // { id: 0, name: 'Sun', longitude: 151.12, ... }

   Python

   first_request.py

   # requests або httpx — SDK у roadmap.
   import os, requests
   
   r = requests.post(
       'https://api.astroway.info/v1/chart',
       headers={'X-Api-Key': os.environ['AW_KEY']},
       json={
           'date': '1991-08-24',
           'time': '16:30:00',
           'timezoneOffset': 3,
           'latitude': 50.4501,
           'longitude': 30.5234,
           'houseSystem': 'P',
       },
   )
   chart = r.json()['data']
   print(chart['planets'][0])

   PHP

   first-request.php

   <?php
   use GuzzleHttp\Client;
   
   $aw = new Client(['base_uri' => 'https://api.astroway.info/v1/']);
   $r = $aw->post('chart', [
       'headers' => ['X-Api-Key' => getenv('AW_KEY')],
       'json' => [
           'date' => '1991-08-24',
           'time' => '16:30:00',
           'timezoneOffset' => 3,
           'latitude' => 50.4501,
           'longitude' => 30.5234,
           'houseSystem' => 'P',
       ],
   ]);
   
   $chart = json_decode($r->getBody(), true);
   echo $chart['planets']['sun']['sign'];

4. Розбери відповідь

   Кожна відповідь — JSON з планетами, будинками, аспектами та meta-блоком (cache hit, credits, engine version).

   JSON

   response.json

   {
     "planets": {
       "sun":  { "sign": "virgo",     "longitude": 1.123847,  "house": 9 },
       "moon": { "sign": "libra",     "longitude": 14.892731, "house": 10 },
       "asc":  { "sign": "capricorn", "longitude": 7.402891  },
       "mc":   { "sign": "libra",     "longitude": 28.117203 }
     },
     "houses":  [ /* 12 cusps */ ],
     "aspects": [ /* 24 items, computed orbs */ ],
     "meta": {
       "engine":     "swisseph",
       "precision":  "sub-arcsecond",
       "credits_used": 20,
       "cache":      "MISS"
     }
   }

   HTTP Headers

   HTTP/2 200
   content-type: application/json
   x-credits-used: 20
   x-credits-remaining: 9980
   x-credits-reset: 2026-06-01T00:00:00Z
   x-ratelimit-limit: 600
   x-ratelimit-remaining: 599
   x-request-id: req_01HZ4M2N8K3PQRTV
   x-cache: MISS

5. Перевір баланс

   Dashboard показує usage в реальному часі: api.astroway.info/dashboard. Або через API:

   curl https://api.astroway.info/v1/usage \
     -H "X-Api-Key: $AW_KEY"

Authentication

AstroWay API автентифікує запити через заголовок X-Api-Key. Bearer-токени та query-string ключі не підтримуються.

curl -H "X-Api-Key: aw_live_..." https://api.astroway.info/v1/health

Тип ключа	Префікс	Поведінка
Production	aw_live_*	Виставляє реальні кредити з акаунту
Sandbox	aw_test_*	Детермінована мокова відповідь, без charge
Restricted (Pro+)	aw_live_* з обмеженням	Обмежений на конкретні endpoints / IP / RPS

Ключі обертаються без downtime — старий ключ продовжує працювати 24 години після генерації нового. Деталі: /authentication/.

Errors

Усі помилки повертаються у форматі ok: false + об’єкт error. Поле error.code (UPPER_SNAKE_CASE) стабільне для скриптів — свіч по ньому, не по message.

error-response.json

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed: date: Invalid input: expected string, received undefined",
    "details": [
      { "path": "date", "message": "Invalid input: expected string, received undefined" }
    ]
  }
}

Найчастіші коди:

• INVALID_INPUT (400) — провалена Zod-валідація; details містить масив { path, message }
• INVALID_API_KEY (401) — ключ не існує або revoked
• PLAN_UPGRADE_REQUIRED (402) — потрібен вищий тариф або add-on пак
• CREDITS_EXHAUSTED (429) — місячний бюджет кредитів вичерпано
• RATE_LIMIT (429) — перевищено RPM; повертається з заголовком Retry-After: <sec>
• internal_calc_error (500) — помилка ефемерид; авто-retry на стороні SDK

Повний список і semantic: /errors/.

Rate limits

Тариф	Quota
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	custom

Перевищення → 429 з Retry-After (sec). Офіційні SDK мають exponential-backoff retries за замовчуванням. Деталі: /rate-limits-credits/.

Далі

• Автентифікація — best practices, ротація ключів, sandbox mode
• Кредити та ліміти — таблиця вартості, rate limiting, overage
• Приклади: натальна карта — детальний розбір /v1/chart
• Готові інтеграції на GitHub — Discord/Slack-боти, OpenAI tools, Cloudflare, FastAPI на офіційних SDK
• Повна API reference — усі 714 ендпоінтів з playground