API Versioning

AstroAPI versions breaking changes with a compatibility date instead of a version number in the URL. The endpoint paths never change; you pin a date, and you keep receiving exactly the behaviour that was current on that date.

Your Version

Send the compatibility date you built against in the X-Api-Version header:

GET /api/modules HTTP/1.1
Host: api.astroapi.cloud
X-Api-Key: your_api_key
X-Api-Version: 2026-01-01

A response that was shaped by a compatibility date tells you which one:

X-Api-Version: 2026-01-01
Vary: X-Api-Version

Endpoints whose output does not depend on the version leave both headers off. GET /api/modules returns the same body on every date, so there is nothing to report and nothing for a cache to keep apart. Send an explicit X-Api-Version and it is echoed back on any endpoint, so you can always confirm a value was accepted.

To read back the version your organization resolves to, use GET /api/org/api-version; its effectiveApiVersion is the date that applies when a request carries no header of its own.

If you send no header, requests use your organization's pinned version, and if you have not pinned one, the baseline of 2026-01-01. New behaviour is never applied to you automatically — an integration written today keeps working unchanged no matter what we ship later.

Changelog

Each breaking change is listed here with the date it takes effect. Pinning a date gives you every change on or before it.

Date	Change
2026-09-03	aspects on POST /api/calc/transit is grouped: one entry per transiting planet, aspect and natal planet, with the interpretation text once and every pass of the period under occurrences. Previously one entry per pass, each repeating the text. See Transits.

The baseline 2026-01-01 is the oldest version we serve. Pinning an earlier date is accepted and resolves to the baseline.

Pinning Your Organization

Rather than adding a header to every call, pin your organization once. All unversioned requests then use that date.

curl -X PATCH "https://api.astroapi.cloud/api/org/api-version" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_api_key" \
  -d '{
    "data": {
      "type": "organizations",
      "attributes": { "apiVersion": "2026-01-01" }
    }
  }'

Read back the current pin, along with the range you can choose from:

curl "https://api.astroapi.cloud/api/org/api-version" \
  -H "X-Api-Key: your_api_key"

{
  "data": {
    "type": "organizations",
    "id": "org_123",
    "attributes": {
      "apiVersion": "2026-01-01",
      "effectiveApiVersion": "2026-01-01",
      "baselineApiVersion": "2026-01-01",
      "latestApiVersion": "2026-01-01"
    }
  }
}

Send "apiVersion": null to clear the pin and fall back to the baseline.

Upgrading Safely

The header always wins over the organization pin, which makes a safe rollout possible:

1. Read the changelog above and check which changes fall between your current date and the new one.
2. Send the new date in X-Api-Version on a few requests, or in your staging environment, and verify the responses.
3. When you are satisfied, pin your organization to the new date and drop the header again.

Because the header overrides the pin per request, you can also do the reverse: pin your organization forward and temporarily send an older date from a service you have not migrated yet.

Browser and Embed Clients

Contexts that cannot set request headers — <img>, <iframe> and <script> embeds, signed chart URLs — accept the date as a query parameter instead:

https://api.astroapi.cloud/api/chart/image.svg?api_version=2026-01-01&...

The header takes precedence when both are present. For fetch() and XHR, use the header; X-Api-Version is allowed by CORS and exposed on responses, so you can read back which version was applied.

Validation

A malformed value returns 400 Bad Request rather than quietly falling back:

{
  "error": "Invalid X-Api-Version: \"v2\". Expected a date in YYYY-MM-DD format."
}

The value must be a real calendar date in YYYY-MM-DD form. A well-formed date outside the supported range is clamped rather than rejected: earlier than the baseline resolves to the baseline, later than the newest change resolves to the newest behaviour.

Caching

Responses whose body can differ per version are marked Vary: X-Api-Version, so a shared cache or CDN in front of your integration will keep those versions apart. Responses that are the same on every date carry no Vary, which lets a cache serve one entry for all of your callers instead of one per date. If you cache API responses yourself, include the compatibility date in the cache key for the endpoints that carry the header.

What Counts as a Breaking Change

Changes that get a date and appear in the changelog:

• Removing or renaming a field in a response
• Changing the type or shape of an existing field
• Making an optional field required, or an omitted field always present
• Changing the meaning of an existing value
• Removing an endpoint or changing its semantics

Changes that ship without a version, because they cannot break a correct client:

• Adding a new endpoint
• Adding a new optional request parameter
• Adding a new field to a response
• Adding a new value to an enum you only read
• Bug fixes that bring behaviour in line with documentation

Write your integration to ignore unknown response fields. Additive changes arrive on every version, including yours.