The OpenAPI spec, Postman and MCP

What the spec is

A complete description of the API, for software

astronest-v1.json is an OpenAPI 3.1.0 document: the industry-standard format tools read to understand an API. It is the same information as the reference, in a form your tools can use directly. It contains:

• 13 endpoints, each with its summary, credit cost (x-credits), required fields and a working example request.
• 39 schemas for every request and response object, such as BirthData, ChartResponse and EphemerisPosition.
• 8 error responses with their codes, and the authentication scheme (a bearer API key).

Base URL https://www.astronest.ai/api/developer. The spec is checked against the running API on every change, so a price, endpoint or required field in it matches what the API actually does.

Postman and API clients

Try every endpoint in two minutes

Postman, using our ready-made collection

1. Create a sandbox key at /developer: free, with no time limit, returning fixed sample responses (free terms).
2. In Postman choose Import and paste https://www.astronest.ai/postman/astronest-v1.postman_collection.json.
3. Open the collection's Variables tab and set apiKey to your key.
4. Open any request and press Send. Every request carries a working example body; with a sandbox key the response is a fixed sample and nothing is charged.

Postman, Insomnia, Bruno or Hoppscotch, from the spec

Import https://www.astronest.ai/openapi/astronest-v1.json as an OpenAPI 3.1 file. Set the authorization to Bearer token with your key. Importing the spec URL (rather than a downloaded copy) lets your tool pick up new endpoints when you re-import.

Generate a client library

A typed client in your language, without hand-writing calls

OpenAPI Generator builds a client from the spec for more than 50 languages. A few common ones:

# TypeScript (fetch)
npx @openapitools/openapi-generator-cli generate -i https://www.astronest.ai/openapi/astronest-v1.json -g typescript-fetch -o ./astronest-client

# Python
npx @openapitools/openapi-generator-cli generate -i https://www.astronest.ai/openapi/astronest-v1.json -g python -o ./astronest_client

# Java · Go · C#: use -g java, -g go or -g csharp

Only want the types? For TypeScript:

npx openapi-typescript https://www.astronest.ai/openapi/astronest-v1.json -o astronest.d.ts

Configure the generated client with your key as a bearer token, and call it from your server: keys are secret, and the API sends no CORS headers, so browser calls fail by design.

AI coding assistants

Let your assistant write the integration

Give Claude, ChatGPT, Copilot or Cursor the spec URL and ask for the integration you need, for example:

Using the OpenAPI spec at https://www.astronest.ai/openapi/astronest-v1.json, write a server-side function that
calls POST /v1/chart with a birthData object and returns the ascendant
and the current daśā. Read the API key from ASTRONEST_API_KEY.

The spec gives the assistant the exact field names, required fields and error codes, so it does not have to guess.

MCP server for AI apps

AstroNest as tools for Claude, Cursor and other AI apps

The Model Context Protocol lets an AI app call AstroNest directly. Our MCP server exposes every endpoint as a tool, generated from this same spec, and bills each call to your key exactly as a direct API call. Server URL (Streamable HTTP):

https://www.astronest.ai/api/developer/mcp

Claude Code

claude mcp add --transport http astronest https://www.astronest.ai/api/developer/mcp \
  --header "Authorization: Bearer YOUR_ASTRONEST_KEY"

Cursor, VS Code and other clients with remote MCP support

{
  "mcpServers": {
    "astronest": {
      "url": "https://www.astronest.ai/api/developer/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ASTRONEST_KEY"
      }
    }
  }
}

VS Code uses the same shape under a servers key, with "type": "http".

Claude Desktop and clients that only run local servers

{
  "mcpServers": {
    "astronest": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.astronest.ai/api/developer/mcp",
        "--header",
        "Authorization: Bearer YOUR_ASTRONEST_KEY"
      ]
    }
  }
}

Tools

Start with a sandbox key: every tool answers with its documented sample and nothing is charged. Discovery (listing the tools) needs no key; calling a tool does. With a live key, tool calls spend your one-time 100 free credits first, then paid credits; when both are used up, tools return credits_exhausted until you buy a pack. Give an agent its own key with a monthly credit limit (set on the key in the portal) so a loop of calls cannot spend your whole balance.

Versioning

What can change, and how you will hear about it

• The version is in the path: /v1/…. Within v1 we add endpoints, optional fields and response fields; we do not remove or rename them.
• Write your client to ignore response fields it does not know, so additions never break it.
• The API is in beta. If a breaking change is ever needed, we will try to give notice to everyone with a key before it ships.

Feedback and support

Tell us what is missing or broken

Use Support & feedback in the developer portal for bugs, feature requests, documentation gaps and billing questions. Include the requestId from the response for anything about a specific call. Replies appear in the same place in the portal.