Prompts para builders de IA

Um builder escreve código mais depressa do que tu. O que ele não sabe são duas coisas sobre uma API concreta: onde pôr a chave e porque é que um pedido a partir do navegador não passa. Ambas custam horas de depuração, e ambas se resolvem com um parágrafo no prompt.

Abaixo vem primeiro esse parágrafo, depois sete receitas.

A regra a colar antes de qualquer receita

Copia este bloco para o builder antes do texto da receita. Não é sobre estilo de código, é sobre aquilo que de outro modo não vai funcionar.

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/* with that key.
   The one exception is a publishable pk_live_* key created for your app's
   origin: responses to that origin carry access-control-allow-origin, and
   the key works only from origins on its own list. Two prefixes answer any
   browser with no 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.

Cuidado

O ponto 2 foi medido, não suposto: uma página de teste numa origin externa recebe resposta de /v1/public/*, e POST /v1/chart é bloqueado pelo navegador. Uma chave pública pk_* não muda isto, abre apenas /v1/public/* e /v1/embed/*.

1. Mapa natal com roda

Duas respostas para uma ação do utilizador: os dados do mapa e um SVG pronto.

Endpoint	Créditos
/v1/chart	20
/v1/render/wheel-western	10

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.

Verifica depois da geração: o SVG foi inserido como markup, e não num <img src>; a hora foi enviada como string HH:mm:ss; a chave não foi parar ao bundle (uma pesquisa por aw_ nos ficheiros compilados não deve encontrar nada).

2. Compatibilidade de dois mapas

Um número e as suas componentes, sem texto explicativo. /v1/synastry/attraction-score, 50 créditos por par.

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. Horóscopo diário, sem chave nenhuma

A única receita em que não é preciso rota de servidor: este endpoint responde ao navegador e não custa créditos.

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.

Nota

O limite aqui é por IP, 30 pedidos por hora para chamadas sem chave. Para uma página com um bloco de horóscopo chega; para uma lista dos doze signos de uma vez, não.

4. Human Design

Tipo, estratégia, autoridade, perfil, centros e canais numa só chamada a /v1/human-design, 50 créditos.

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. Relatório PDF com a marca do utilizador

Para quem vende relatórios, e não mostra ecrãs. /v1/reports/natal, 5000 créditos por documento, e a ligação vive 24 horas.

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.

O catálogo completo dos dezasseis relatórios, o que tem cada um e quantas páginas: Reports API.

6. Calendário de trânsitos do mês

Uma lista de eventos numa janela de datas, a partir da qual se faz tanto um feed como um calendário. /v1/transit-calendar, 100 créditos por janela.

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. Tiragem de tarot

A forma mais barata de acrescentar uma interação diária. /v1/tarot/rider-waite/draw/three-card, 10 créditos por tiragem, ou zero para a carta do dia.

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.

Oito builders, uma diferença

As receitas acima são iguais para todos. A única diferença é onde vive a rota de servidor e onde pôr a chave.

Builder	Onde vive a chamada de servidor	Onde pôr a chave
Lovable	edge function no Supabase	Secrets do projeto Supabase
Bolt	server function	painel Secrets do Bolt
v0	route handler Next.js em Vercel Functions	environment variable no Vercel, do tipo Secret
Replit	processo de servidor normal	Replit Secrets, e mais uma vez à parte em Deployments
Cursor, Claude Code, Devin Desktop, Copilot	o que houver na tua stack	.env fora do git mais o armazenamento do teu alojamento

Quatro armadilhas distintas, cada uma custa uma noite.

• O Lovable e o Bolt compilam o frontend com Vite, e o Vite entrega ao navegador qualquer variável com o prefixo VITE_. A chave não vai para lá nem temporariamente: acabaria num bundle distribuído a toda a gente.
• O Bolt mostra a pré-visualização dentro de um WebContainer, e isso é um navegador verdadeiro com CORS verdadeiro, que ali não se desliga. Uma server function aqui não é “melhor”, é a única forma de a chamada sequer acontecer.
• O v0 embute NEXT_PUBLIC_* no bundle na fase de build. Mudar o valor no dashboard não chega: enquanto não houver um novo deploy, a aplicação funciona com a chave antiga. Rodar a chave é rodar mais recompilar.
• O Replit guarda os secrets do workspace e os secrets de Deployments em separado. O que funcionava no editor falha depois da publicação com uma chave vazia, até a acrescentares outra vez no painel Deployments.

As quatro últimas linhas da tabela não são plataformas, mas agentes no teu repositório, e cada um tem a sua própria lista de rede permitida para a sua sandbox. Quando o agente quiser testar o código que acabou de escrever, a chamada a api.astroway.info pode ficar bloqueada até o domínio ser acrescentado. Para eles há também um caminho mais curto: liga o nosso MCP e o agente chama a API sozinho, sem código teu. Instruções em Configuração do agente.

Nota

O Windsurf chama-se Devin Desktop desde 2 de junho de 2026, os utilizadores foram migrados automaticamente e a documentação mudou-se para docs.devin.ai. Tudo o que encontrares hoje com o nome Windsurf foi escrito antes dessa data.

Se o teu agente fala function calling e não MCP

Obtém as definições de ferramentas prontas e passa-as diretamente ao modelo. São geradas a partir do documento OpenAPI, por isso o esquema que o modelo preenche é o mesmo que o endpoint valida.

terminal

curl "https://api.astroway.info/v1/agent/tools?format=openai&select=starter" \
-H "X-Api-Key: aw_live_YOUR_KEY"

format aceita openai e anthropic, select restringe o catálogo ao conjunto inicial em vez de todas as ferramentas.