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

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

<GetApiKeyBlock />

<Steps>

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

   Зайди в [dashboard](https://api.astroway.info/dashboard/sign-up) і натисни **Generate key**. Безкоштовний тариф дає **10 000 кредитів/міс назавжди** — без введення картки. Ключі починаються з:

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

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

2. ### Постав SDK

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

   <Tabs syncKey="lang">
     <TabItem label="cURL">
       ```bash frame="terminal"
       # SDK не потрібен — лише curl та ключ:
       ```
     </TabItem>
     <TabItem label="TypeScript">
       ```bash frame="terminal"
       # native fetch — Node 18+ або браузер. SDK у roadmap.
       # Альтернатива: openapi-typescript-codegen з нашого OpenAPI 3.1
       ```
     </TabItem>
     <TabItem label="Python">
       ```bash frame="terminal"
       pip install requests   # або httpx — SDK у roadmap
       ```
     </TabItem>
     <TabItem label="PHP">
       ```bash frame="terminal"
       composer require guzzlehttp/guzzle
       # SDK у roadmap, поки що — Guzzle + raw HTTP
       ```
     </TabItem>
     <TabItem label="MCP">
       ```bash frame="terminal"
       # Для 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
       ```
     </TabItem>
   </Tabs>

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

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

   <Tabs syncKey="lang">
     <TabItem label="cURL">
       ```bash frame="terminal" title="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"
         }'
       ```
     </TabItem>
     <TabItem label="TypeScript">
       ```ts title="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, ... }
       ```
     </TabItem>
     <TabItem label="Python">
       ```python title="first_request.py"
       # requests або httpx — SDK у roadmap.

       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])
       ```
     </TabItem>
     <TabItem label="PHP">
       ```php title="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'];
       ```
     </TabItem>
   </Tabs>

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

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

   <Tabs>
     <TabItem label="JSON">
       ```json title="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"
         }
       }
       ```
     </TabItem>
     <TabItem label="HTTP Headers">
       ```http
       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
       ```
     </TabItem>
   </Tabs>

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

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

   ```bash frame="terminal"
   curl https://api.astroway.info/v1/keys/usage \
     -H "X-Api-Key: $AW_KEY"
   ```

</Steps>

## Authentication

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

```bash frame="terminal"
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/](/authentication/).

## Errors

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

```json title="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/](/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/](/rate-limits-credits/).

## Далі

- [Автентифікація](/authentication/) — best practices, ротація ключів, sandbox mode
- [Кредити та ліміти](/rate-limits-credits/) — таблиця вартості, rate limiting, overage
- [Приклади: натальна карта](/examples/natal/) — детальний розбір `/v1/chart`
- [Готові інтеграції на GitHub](https://github.com/astroway/examples) — Discord/Slack-боти, OpenAI tools, Cloudflare, FastAPI на офіційних SDK
- [Повна API reference](/docs/api/) — усі {siteMeta.endpoints} ендпоінтів з playground