OpenAPI Specification

Asterwise serves two OpenAPI 3.1 specifications. Use whichever fits your toolchain.

The two specs

Spec	URL	Use case
Full spec	https://api.asterwise.com/openapi.json	Documentation, API exploration, complete reference
SDK-filtered spec	https://api.asterwise.com/openapi-sdk.json	Code generation (OpenAPI Generator, openapi-typescript, etc.)

Both are auto-generated from the live FastAPI application, so they stay in sync with deployed behavior.

Why two specs?

Both specs describe the same public API: the same paths, request and response schemas and error codes. The website's own routes (sign-in, API keys, billing, account, OAuth) are in neither.

The difference is the operation IDs, which code generators turn into method names:

• Full spec: FastAPI's default IDs, such as get_atmakaraka_v1_astro_atmakaraka_post.
• SDK-filtered spec: short, stable IDs from a curated mapping that covers all 122 operations, such as natal_chart and atmakaraka. The official SDKs are generated from it, which is where natalChart() (TypeScript) and natal_chart() (Python) come from.

Generate clients from the SDK-filtered spec. Use either spec for reading or for API tools that don't care about method names.

Quick start

Download

# Full spec
curl -O https://api.asterwise.com/openapi.json

# SDK-filtered spec
curl -O https://api.asterwise.com/openapi-sdk.json

OpenAPI Generator

# Generate a Python client
openapi-generator-cli generate \
  -i https://api.asterwise.com/openapi-sdk.json \
  -g python \
  -o ./asterwise-client \
  --additional-properties=packageName=asterwise_client

# Generate a Go client
openapi-generator-cli generate \
  -i https://api.asterwise.com/openapi-sdk.json \
  -g go \
  -o ./asterwise-client \
  --additional-properties=packageName=asterwise

# Generate a Java client
openapi-generator-cli generate \
  -i https://api.asterwise.com/openapi-sdk.json \
  -g java \
  -o ./asterwise-client

openapi-typescript

# Generate TypeScript types only
npx openapi-typescript https://api.asterwise.com/openapi-sdk.json -o ./asterwise.d.ts

Insomnia

1. Open Insomnia
2. Application > Preferences > Data > Import Data > From URL
3. Paste https://api.asterwise.com/openapi.json
4. Click Fetch and Import

Spec metadata

The OpenAPI document declares:

• OpenAPI version: 3.1.0
• API title: Asterwise API
• API version: 2026-03-01
• Server URL: https://api.asterwise.com
• Auth scheme: HTTP Bearer (with aw_ prefix on tokens)

Already-published Asterwise SDKs

If you're working in Python or TypeScript, you don't need to generate a client — Asterwise publishes maintained SDKs:

• Python SDK — pip install asterwise
• TypeScript SDK — npm install asterwise

Both are built from the SDK-filtered spec and ship with typed ErrorCode enums that narrow correctly inside conditional branches.

Schema stability

Field additions, new endpoints, and new error codes appear in the OpenAPI spec as soon as they ship. The versioning contract still applies — additive changes are non-breaking, and breaking changes would require v2.