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?

The full spec includes every route the application serves — including internal endpoints like authentication, billing webhooks, and OAuth dance routes. Those aren't useful in a customer SDK and produce ugly client method names like auth_callback_oauth_callback_get.

The SDK-filtered spec excludes routes under these prefixes:

• /v1/auth/
• /v1/oauth/
• /v1/billing/
• /v1/account/
• /v1/keys/
• /v1/internal/

It also applies stable operation IDs from a curated 118-entry mapping, producing client methods like getNatalChart() instead of chart_post_v1_astro_chart_post.

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.