PDF Reports

Generate print-ready astrology reports as PDFs — fully white-labelled with your own brand name, logo and website. Every report is computed from a real birth chart, written up by AI, and delivered as a hosted PDF your users can download.

How it works

One endpoint handles every report. You send the report type plus birth details, and the API returns a download URL immediately. The PDF itself is built in the background across a few calls — see the batch flow below for how to drive it to completion.

The download URL is stable: it is returned on the very first call and never changes, so you can store it against the user's record straight away. If the user opens it before the PDF is finished, they see a “preparing your report” page that refreshes itself.

Available reports

Pass one of these values as report_type. The exact list available to your account, along with live pricing, is shown on the Reports page in your dashboard.

Dual-chart reports need birth details for two people; single-chart reports need one. See the endpoint reference for the exact field names.

The batch flow

Reports are long documents with many AI-written sections, so they are built in batches rather than in one blocking request. The pattern is simple:

• First call — creates the report, processes the first batch of sections, and returns the download URL with status: "processing".
• Repeat the same call — identical body, same birth details. Each call processes the next batch.
• Final call — once all sections are done the PDF is rendered and saved, and the response comes back with status: "ready".

The URL is identical in every response, so store it after the first call and simply keep calling until the status flips to ready. Each response also carries a progress object (done, total, percent) you can wire straight into a progress bar. A typical report is complete within two to three minutes.

Downloading

The download URL serves the PDF once it exists. Before that it shows a self-refreshing “preparing” page, so it is always safe to show your user. To check status from code instead, add &format=json to the URL — you get back a small JSON status object rather than a file or a page.

Links stay valid for 7 days. If your users need the PDF for longer, copy it into your own storage while the link is live. Full details are in the endpoint reference.

Authentication

Send your API key in the X-Api-Key header, the same as every other StarsAPI endpoint.

White-label branding

Every PDF carries your branding, not ours. Brand values are resolved in three layers, with the first match winning:

• Request fields — pass brand_name, brand_tagline, brand_url or brand_logo_url in the request body. Useful if you serve several client brands from one API key.
• Account settings — set once under Brand Settings in your dashboard and applied to every PDF automatically.
• Neutral default — if neither is set, the cover falls back to a generic, unbranded title.

Billing

Reports are charged to your wallet balance, not your API request credits. Each report type has its own price, visible on the Reports page. A report is charged once, on the first call — the follow-up batch calls that finish the same report are free.

If your wallet balance is too low, the request fails before any work is done and nothing is charged.

Common errors

See also

• Generate report — endpoint reference
• Authentication
• Error reference