# Промпти для AI-білдерів

Білдер напише код швидше за вас. Чого він не знає, так це двох речей про конкретний API: куди покласти ключ і чому запит із браузера не проходить. Обидві коштують години налагодження, і обидві знімаються одним абзацом у промпті.

Нижче спершу цей абзац, потім сім рецептів.

## Правило, яке треба вставити перед будь-яким рецептом

Скопіюйте цей блок у білдер **до** тексту рецепта. Він не про стиль коду, він про те, що інакше не запрацює.

```text title="house rules"
AstroWay API house rules. Apply these to every request you generate.

1. The API key is a server secret. Never put aw_live_* or aw_test_* into client
   code, into a VITE_* or NEXT_PUBLIC_* variable, or into a fetch that runs in
   the browser. Create a server route and call the API from there.
2. The browser cannot call https://api.astroway.info/v1/* directly. Those
   responses carry no access-control-allow-origin header, so a fetch from your
   app's origin fails on CORS. Two prefixes do answer a browser and neither
   needs a key: /v1/public/* returns JSON you can use, and /v1/embed/* returns
   a finished HTML page meant for an iframe, not for fetch.
3. The auth header is exactly "X-Api-Key: <key>". Authorization: Bearer is
   rejected with 401, and so is an api_key query parameter.
4. Send the birth time zone as an IANA name: "timezone": "Europe/Kyiv". Do not
   compute a UTC offset yourself. Kyiv in May 1990 was UTC+4, not the +3 it is
   today, and a wrong offset moves every house cusp.
5. Every response is {"ok": true, "data": {...}} or {"ok": false, "error":
   {"code": "...", "message": "..."}}. Read data on success and show
   error.message to the user on failure. Do not assume a bare object.
6. Planet positions arrive as ecliptic longitude in degrees, with no sign name.
   Derive it: SIGNS[Math.floor(longitude / 30)] where SIGNS runs Aries,
   Taurus, Gemini, Cancer, Leo, Virgo, Libra, Scorpio, Sagittarius,
   Capricorn, Aquarius, Pisces. Degrees inside the sign are longitude % 30.
7. Responses carry X-Credits-Used and X-Credits-Remaining. Log both on the
   server so the cost of a feature is visible before the bill is.
8. Ask for the fields you will render. Every endpoint takes ?fields= as a
   comma-separated list of dotted paths and ?precision= as decimal places:
   POST /v1/chart?fields=planets.name,planets.longitude,houses.cusp&precision=2
   answers in 559 bytes where the full response is 32,410. Same credits, and
   the tokens are yours to pay either way.
9. Get a free key at https://api.astroway.info/dashboard/sign-up and use an
   aw_test_* sandbox key while building: it spends no credits.
```

<Aside type="caution">
Пункт 2 виміряний, а не припущений: сторінка-проба на сторонньому origin отримує відповідь від `/v1/public/*`, а `POST /v1/chart` блокується браузером. Публічний ключ `pk_*` цього не змінює, він відкриває лише `/v1/public/*` і `/v1/embed/*`.
</Aside>

## 1. Натальна карта з колесом

Дві відповіді на одну дію користувача: дані карти і готовий SVG.

| Ендпоінт | Кредитів |
|---|---|
| `/v1/chart` | 20 |
| `/v1/render/wheel-western` | 10 |

```text title="prompt"
Build a single-page app: a birth data form (date, time, city with latitude and
longitude, IANA time zone) that renders a natal chart.

Server route POST /api/chart does two calls to AstroWay, in parallel:
  POST https://api.astroway.info/v1/chart
  POST https://api.astroway.info/v1/render/wheel-western
Both take the same body:
  { "date": "1990-05-15", "time": "14:30:00", "timezone": "Europe/Kyiv",
    "latitude": 50.45, "longitude": 30.52 }
Both need the X-Api-Key header.

/v1/chart returns data.planets (array with name, longitude, isRetrograde),
data.houses.cusps (array of 12 longitudes) and data.aspects (array with
planet1, planet2 and a type object carrying name, symbol and color).
/v1/render/wheel-western returns data.svg as a string.

The page shows the SVG at the top, then a table of planets with sign and
degree derived from longitude, then the aspect list using type.symbol and
type.color. Mark retrograde planets with an R.

Do not call AstroWay from the browser. The page calls /api/chart only.
```

Перевірте після генерації: SVG вставлено як розмітку, а не в `<img src>`; час відправлено рядком `HH:mm:ss`; ключ не потрапив у бандл (пошук по `aw_` у зібраних файлах має нічого не знайти).

## 2. Сумісність двох карт

Одне число і його складові, без пояснювального тексту. `/v1/synastry/attraction-score`, **50 кредитів** за пару.

```text title="prompt"
Build a compatibility page: two birth-data forms side by side, one button.

Server route POST /api/compat calls
  POST https://api.astroway.info/v1/synastry/attraction-score
with body { "chart1": {...}, "chart2": {...} }, where each chart is
  { "date", "time", "timezone", "latitude", "longitude" }.

The response has data.score (a number), data.components (the parts that made
it) and data.notes. Render score as a large number with a progress ring, then
components as labelled bars, then notes as a list.

Never show the score without the components: a single number with no reason
behind it is the thing users distrust.
```

## 3. Щоденний гороскоп, взагалі без ключа

Єдиний рецепт, де серверний маршрут не потрібен: цей ендпоінт відповідає браузеру і не коштує кредитів.

```text title="prompt"
Add a daily horoscope block to the page. Call this directly from the browser,
no key and no server route needed:

  GET https://api.astroway.info/v1/public/horoscope/daily?sign=leo&lang=en

Response: data.sign, data.date, data.period, data.horoscope (the text),
data.disclaimer and data.language. Render a sign picker with the twelve signs,
remember the choice in localStorage, and always show data.disclaimer under the
text.

The first request for a date that has not been generated yet can take a while,
so show a skeleton, not a spinner that looks stuck.
```

<Aside type="note">
Ліміт тут на IP, 30 запитів на годину для безключових викликів. Для сторінки з одним блоком гороскопу цього вистачає; для списку з дванадцяти знаків одразу - ні.
</Aside>

## 4. Human Design

Тип, стратегія, авторитет, профіль, центри й канали одним викликом `/v1/human-design`, **50 кредитів**.

```text title="prompt"
Build a Human Design page: birth data form, then the chart summary.

Server route POST /api/hd calls
  POST https://api.astroway.info/v1/human-design
with { "date", "time", "timezone", "latitude", "longitude" }.

The response has data.type, data.strategy, data.notSelfTheme, data.authority,
data.profile, data.definition, data.cross, data.centers, and the activation
arrays data.personalityActivations and data.designActivations.

Lay it out as: type and strategy as the headline, authority and profile as two
cards, centers as a list with defined ones filled and undefined ones outlined,
activations in a collapsible table. Birth time matters here more than anywhere
else, so refuse to submit without it and say why.
```

## 5. PDF-звіт під брендом користувача

Для тих, хто продає звіти, а не показує екрани. `/v1/reports/natal`, **5000 кредитів** за документ, і посилання живе 24 години.

```text title="prompt"
Build a report generator: birth data form plus a branding form (company name,
report title, accent colour), and a Generate button.

Server route POST /api/report calls
  POST https://api.astroway.info/v1/reports/natal
with
  { "chart": { "date", "time", "timezone", "latitude", "longitude" },
    "whitelabel": { "companyName": "...", "reportName": "...",
                    "themeColor": "#7c3aed", "footerText": "..." } }

The response has data.url, data.page_count, data.byte_length and
data.expires_at. The URL is valid for 24 hours only, so the server must
download the PDF immediately and store it on your side, then hand the user
your own link. Never give the AstroWay URL to the end user.

Show page_count and a download button. One report costs 5000 credits: put a
confirmation step before the call, not after.
```

Повний каталог із шістнадцяти звітів, що в кожному і скільки сторінок: [Reports API](/products/reports-api/).

## 6. Календар транзитів на місяць

Список подій у вікні дат, з якого виходить і стрічка, і календар. `/v1/transit-calendar`, **100 кредитів** за вікно.

```text title="prompt"
Build a month view of transits.

Server route POST /api/transits calls
  POST https://api.astroway.info/v1/transit-calendar
with
  { "natal": { "date", "time", "timezone", "latitude", "longitude" },
    "startDate": "2026-10-01", "endDate": "2026-10-31" }

The response has data.count and data.events, plus the echoed startDate,
endDate and maxOrb. Render events on a month grid, one dot per day with
events, and a day panel listing that day's events.

One call covers the whole window, so fetch the month once and filter in the
client. Do not call the API per day: that is thirty-one calls and thirty-one
times the credits for the same answer.
```

## 7. Розклад таро

Найдешевший спосіб додати щоденну взаємодію. `/v1/tarot/rider-waite/draw/three-card`, **10 кредитів** за розклад, або нуль для щоденної карти.

```text title="prompt"
Add a three-card tarot spread.

Server route POST /api/tarot calls
  POST https://api.astroway.info/v1/tarot/rider-waite/draw/three-card
with an optional { "seed": 7 }. The response has data.spread, data.seed and
data.drawn.

Pass a seed derived from the user id and today's date, so the same person gets
the same spread all day and a new one tomorrow. Without a seed every reload
deals a new hand, which reads as a slot machine.

For a zero-cost daily card the browser can call
  GET https://api.astroway.info/v1/public/tarot/daily
directly, no key.
```

## Вісім білдерів, одна різниця

Рецепти вище однакові для всіх. Різниця тільки в тому, де живе серверний маршрут і куди покласти ключ.

| Білдер | Де живе серверний виклик | Куди покласти ключ |
|---|---|---|
| Lovable | edge function у Supabase | Secrets проєкту Supabase |
| Bolt | server function | панель Secrets у Bolt |
| v0 | route handler Next.js на Vercel Functions | environment variable у Vercel, типом Secret |
| Replit | звичайний серверний процес | Replit Secrets, **і окремо ще раз у Deployments** |
| Cursor, Claude Code, Devin Desktop, Copilot | той, що у вашому стеку | `.env` поза git плюс сховище вашого хостингу |

**Чотири окремі пастки, кожна коштує вечора.**

- **Lovable і Bolt збирають фронтенд через Vite**, а Vite віддає браузеру будь-яку змінну з префіксом `VITE_`. Ключ туди не кладуть навіть тимчасово: він опиниться в бандлі, який роздається всім.
- **Bolt показує превʼю всередині WebContainer**, а це справжній браузер зі справжнім CORS, який там не вимикається. Серверна функція тут не «краще», а єдиний спосіб, щоб виклик узагалі відбувся.
- **v0 вшиває `NEXT_PUBLIC_*` у бандл на етапі збірки.** Змінити значення в дашборді замало: поки немає нового деплою, застосунок працює зі старим ключем. Ротація ключа це ротація плюс перезбірка.
- **Replit тримає секрети робочої області й секрети Deployments окремо.** Те, що працювало в редакторі, після публікації падає з порожнім ключем, поки ви не додасте його ще раз у панелі Deployments.

Чотири останні рядки таблиці це не платформи, а агенти у вашому репозиторії, і в кожного свій мережевий список дозволів для власної пісочниці. Коли агент захоче перевірити щойно написаний код, виклик до `api.astroway.info` може бути заблокований, поки домен не додано. Для них є і коротший шлях: підключіть наш MCP і агент викличе API сам, без вашого коду. Інструкції на [Налаштування агента](/agent-setup/).

<Aside type="note">
Windsurf із 2 червня 2026 називається Devin Desktop, користувачів перевели автоматично, документація переїхала на `docs.devin.ai`. Усе, що ви знайдете сьогодні під назвою Windsurf, написане до цієї дати.
</Aside>

## Якщо ваш агент говорить function calling, а не MCP

Візьміть готові визначення інструментів і передайте моделі напряму. Вони генеруються з OpenAPI-документа, тож схема, яку заповнює модель, це та сама, яку перевіряє ендпоінт.

<Code lang="bash" title="terminal" code={`curl "https://api.astroway.info/v1/agent/tools?format=openai&select=starter" \\
  -H "X-Api-Key: aw_live_YOUR_KEY"`} />

`format` приймає `openai` і `anthropic`, `select` звужує каталог до стартового набору замість усіх інструментів.