API ready
Cmd K

Documentation

Build from facts, then compose.

Astro AI exposes deterministic astrology facts through curated product routes and a broader typed calculator registry. Use this guide for intent and examples; use the reference for every route-level detail.

119/v1 operations
65POST workflows
41GET resources
235+calculator contracts

The mental model

There are three surfaces, and they should not be used interchangeably.

Curated product routes

Use routes like /v1/charts, /v1/panchang/day, /v1/dashas/vimshottari, and /v1/compatibility/ashtakoot when the app needs a stable product workflow.

Calculator registry

Use /v1/calculators and /v1/calculators/{calculator_id}:run when you need long-tail VedAstro-mapped calculations without waiting for a bespoke endpoint.

Safety and provenance

Prediction prose, external providers, and sensitive rows are gated. The API favors evidence, warnings, and provenance over hidden generation.

Saved product state

Use /v1/people, /v1/calculation-runs, and /v1/library-items when your app needs durable profiles, source results, saved reports, calendar windows, lessons, or notes.

Authentication and envelopes

Local development is open by default. Production deployments should set ASTRO_AI_API_KEYS and send either Authorization: Bearer ASTRO_AI_API_KEY or x-api-key: ASTRO_AI_API_KEY. URL query-string keys are rejected.

Every success response has the same outer shape. { "data": { ...typed payload }, "meta": { "request_id": "req_...", "calculator_version": "2026-05-23", "input": {}, "warnings": [] } }

When ASTRO_AI_RATE_LIMIT_PER_MINUTE is configured, /v1 routes return RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After where applicable.

Birth input

Most calculation endpoints use the same civil date-time, coordinates, timezone, and convention config.

{
  "year": 1998,
  "month": 5,
  "date": 20,
  "hours": 14,
  "minutes": 25,
  "seconds": 0,
  "latitude": 13.0827,
  "longitude": 80.2707,
  "timezone": 5.5,
  "config": {
    "ayanamsa": "lahiri",
    "observation_point": "topocentric",
    "house_system": "placidus"
  }
}

Use decimal UTC offsets in timezone. The current convention defaults are Lahiri ayanamsa and topocentric observation. Keep the original user-entered location elsewhere if your product needs provenance.

Recommended workflows

1Chart-first apps

Call POST /v1/charts, then add divisional charts, rendering, or reading facts only when needed.

 2Calendar views

Call POST /v1/panchang/day and optionally combine it with /v1/muhurta/windows.

 3Agent readings

Call POST /v1/readings/facts for auditable facts before any LLM or UI copy layer.

 4Teacher flows

Call POST /v1/teacher/answer for source-backed explanations, then /v1/teacher/lesson-plan for saved study sequences.

 5Saved Match Finder

Call POST /v1/match-runs to store facts-only compatibility context between two saved people.

 6Advanced calculations

Discover calculators, inspect schemas, then run one calculator or a batch with explicit internal/experimental gates.

Examples we ran

These snippets were checked against the local FastAPI app using the shared Chennai sample birth payload.

POST /v1/charts

Chart facts

Use this first. The local run returned Virgo rising and chart planets in typed sidereal positions.

curl -s http://127.0.0.1:8000/v1/charts -H "Content-Type: application/json" -d @birth.json
{
  "data": {
    "object": "chart",
    "ascendant": {
      "sign": "Virgo",
      "degree_in_sign": 7.98468889
    },
    "planets": [
      {
        "name": "Sun",
        "sign": "Taurus",
        "nakshatra": "Krittika"
      },
      {
        "name": "Moon",
        "sign": "Aquarius",
        "nakshatra": "Shatabhisha"
      }
    ]
  },
  "meta": {
    "calculator_version": "2026-05-23",
    "warnings": []
  }
}
POST /v1/panchang/day

Panchang day

The same sample produced a weekday, lunar day, nakshatra, yoga, karana, sunrise, and sunset.

curl -s http://127.0.0.1:8000/v1/panchang/day -H "Content-Type: application/json" -d @birth.json
{
  "data": {
    "object": "panchang_day",
    "weekday": "Wednesday",
    "tithi": {
      "name": "Krishna Navami",
      "ends_at": "1998-05-20T19:28:25+05:30"
    },
    "nakshatra": {
      "name": "Shatabhisha",
      "ends_at": "1998-05-20T14:53:27+05:30"
    },
    "sunrise": "1998-05-20T05:43:25+05:30",
    "sunset": "1998-05-20T18:27:30+05:30"
  }
}
POST /v1/dashas/vimshottari

Vimshottari timing

The local run anchored the sequence to Shatabhisha with Rahu as the starting lord.

curl -s http://127.0.0.1:8000/v1/dashas/vimshottari -H "Content-Type: application/json" -d @birth.json
{
  "data": {
    "object": "vimshottari_dasha",
    "birth_nakshatra": "Shatabhisha",
    "starting_lord": "Rahu",
    "periods": [
      {
        "lord": "Rahu",
        "end": "1998-10-25T01:04:28.176966+00:00"
      },
      {
        "lord": "Jupiter",
        "end": "2014-10-24T22:11:40.176966+00:00"
      },
      {
        "lord": "Saturn",
        "end": "2033-10-24T12:46:28.176966+00:00"
      }
    ]
  }
}
POST /v1/compatibility/ashtakoot

Ashtakoot compatibility

The pair example returned a beta scored 8-kuta report with visible factor scores.

curl -s http://127.0.0.1:8000/v1/compatibility/ashtakoot -H "Content-Type: application/json" -d @pair.json
{
  "data": {
    "object": "ashtakoot_report",
    "total_points": 15,
    "max_points": 36,
    "percentage": 41.6667,
    "factors": [
      {
        "name": "Nadi Kuta",
        "score": 8,
        "max_score": 8
      },
      {
        "name": "Rasi Kuta",
        "score": 7,
        "max_score": 7
      }
    ]
  }
}
POST /v1/teacher/answer

Teacher answer

The Teacher route composed classical citations and chart facts without generating prediction prose.

curl -s http://127.0.0.1:8000/v1/teacher/answer -H "Content-Type: application/json" -d @teacher.json
{
  "data": {
    "object": "teacher_answer",
    "mode": "source_backed_teacher_outline",
    "has_birth_context": true,
    "answer_outline": [
      {
        "id": "classical-grounding",
        "citation_ids": [
          "brihat-parashara-hora-sastra#bphs-vimshottari-dasha"
        ]
      },
      {
        "id": "chart-evidence",
        "source_calculator_ids": [
          "chart.planets",
          "dasha.vimshottari.active"
        ]
      }
    ],
    "safety": {
      "llm_generation": false,
      "prediction_prose": false
    }
  }
}
POST /v1/teacher/lesson-plan

Teacher lesson plan

The lesson-plan route turned the same citation and chart-fact policy into a saved study sequence.

curl -s http://127.0.0.1:8000/v1/teacher/lesson-plan -H "Content-Type: application/json" -d @teacher-lesson.json
{
  "data": {
    "object": "teacher_lesson_plan",
    "mode": "source_backed_lesson_sequence",
    "lesson_count": 4,
    "lessons": [
      {
        "object": "teacher_lesson",
        "id": "lesson-1",
        "citation_ids": [
          "brihat-parashara-hora-sastra#bphs-vimshottari-dasha"
        ]
      }
    ],
    "save_hint": {
      "body": {
        "kind": "teacher_lesson_plan"
      }
    },
    "safety": {
      "llm_generation": false,
      "prediction_prose": false
    }
  }
}
POST /v1/calculators:batch

Calculator batch

The batch run executed julian-day and chart.planets with one shared birth payload.

curl -s http://127.0.0.1:8000/v1/calculators:batch -H "Content-Type: application/json" -d @batch.json
{
  "data": {
    "object": "calculator_batch",
    "cost_units": 2,
    "results": [
      {
        "id": "julian-day",
        "calculator_id": "time.julian_day",
        "status": "ok"
      },
      {
        "id": "planets",
        "calculator_id": "chart.planets",
        "status": "ok"
      }
    ]
  }
}
POST /v1/names/generate

Name suggestions

The deterministic name helper ranked local candidates and included numerology evidence.

curl -s http://127.0.0.1:8000/v1/names/generate -H "Content-Type: application/json" -d @names.json
{
  "data": {
    "object": "name_suggestions",
    "generation_mode": "deterministic_local_candidates",
    "candidates": [
      {
        "name": "Aarav",
        "name_number": 11,
        "ruling_planet": "Moon"
      },
      {
        "name": "Dev",
        "name_number": 15,
        "ruling_planet": "Venus"
      }
    ],
    "warnings": [
      "This is not an LLM generation endpoint."
    ]
  }
}

Endpoint map

Use this as the human index. The full reference page expands every route with parameters, request examples, returns, and caveats.

Charts 2 operations

Birth-chart and divisional-chart calculation surfaces.

 Panchang 1 operations

Day-level lunar calendar factors for a birth or event time.

 Muhurta 1 operations

Transparent timing windows and hora-style timing helpers.

 Good Time Finder 1 operations

Guided task-aware muhurta ranking with citations and transparent scoring evidence.

 Birth Time Finder 1 operations

Guided birth-time candidate ranking with uncertainty bands and transparent rectification evidence.

 Dashas 4 operations

Deterministic dasha timelines and active-period lookup.

 Life Timeline 1 operations

Evidence-first life-map timelines composed from dasha, event windows, and Ashtakavarga research signals.

 Reports 1 operations

Source-backed product reports assembled from deterministic calculator facts.

 Readings 2 operations

Facts-first bundles for downstream reading products.

 Predictions 3 operations

Gated prediction metadata and source-backed fact matches.

 Compatibility 2 operations

Relationship and match-context calculation surfaces.

 Strength 1 operations

Planet-strength reports with research-grade caveats.

 Ashtakavarga 1 operations

Bindu charts, reductions, and life-map evidence.

 Rendering 3 operations

SVG payloads for chart, kundali, and sky-chart views.

 Calculator Registry 10 operations

Discover, inspect, and execute calculator contracts.

 Classical Texts 5 operations

Citation-backed classical text catalog and deterministic retrieval outlines.

 Teacher 2 operations

Source-backed teaching outlines and lesson plans that combine classical citations and optional chart facts without LLM prose.

 Search 4 operations

Local lexical search over calculators, docs, and reference metadata.

 Geo & Time 5 operations

Coordinate, timezone, address, IP, and standard-time helpers.

 Autofill 5 operations

Product-facing suggestions for birth, marriage, and location workflows.

 Rectification 3 operations

Evidence scans for candidate birth times.

 Names 1 operations

Deterministic name suggestions and number-aware naming helpers.

 Time Ranges 3 operations

VedAstro-style time range presets, counts, and CSV lists.

 Product State 50 operations

Saved people, calculation history, product-library snapshots, client sessions, and journal events for reusable workflows.

 External Providers 3 operations

Explicitly configured external-provider gates.

 Safety 1 operations

Catalog of intentionally rejected sensitive or internal rows.

 Coverage 1 operations

VedAstro implementation coverage and clone-decision ledger.

 Hermes Astro 2 operations

Astro AI API operations.

OpenAPI and Swagger

/openapi is Swagger UI for trying the contract. /openapi.json is the raw schema for SDK generation. /reference is the authored endpoint reference.