Python SDK
Install editable from the repo, then import AstroAI. The package target is astro-ai-client.
.venv/bin/python -m pip install -e ./packages/sdk-pythonThe API for Indian astrology.
Astro AI API Reference
Deterministic chart, panchang, dasha, compatibility, rendering, registry, and safety-gated prediction surfaces through one clean /v1 contract.
Base URL
https://api.astro.ai
Install
.venv/bin/python -m pip install -e ./packages/sdk-python
Example request
from astro_ai_client import AstroAI
client = AstroAI(api_key="ASTRO_AI_API_KEY")
chart = client.chart(
{
"year": 1998,
"month": 5,
"date": 20,
"hours": 14,
"minutes": 25,
"latitude": 13.0827,
"longitude": 80.2707,
"timezone": 5.5,
}
)
print(chart["ascendant"]["sign"])SDK & MCP setup
Use the repo-local SDK packages during development, then point the same clients at a hosted Astro AI deployment when packages and hosting are ready.
TypeScript SDK
Install the local package into an app or run npm run smoke --prefix packages/sdk-typescript. The package target is @astro-ai/sdk.
npm install ./packages/sdk-typescriptPublic MCP
Use the public Streamable HTTP endpoint for curated read-only astrology tools that do not execute arbitrary calculators.
{
"name": "astro-ai-public",
"transport": {
"type": "streamable_http",
"url": "http://127.0.0.1:8000/mcp/public",
"headers": {
"MCP-Protocol-Version": "2025-06-18",
"Accept": "application/json, text/event-stream"
}
}
}Protected MCP
Use the protected endpoint when the client needs saved product state or calculator execution. Keep the bearer token out of browser code.
{
"name": "astro-ai",
"transport": {
"type": "streamable_http",
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"Authorization": "Bearer ASTRO_AI_API_KEY",
"MCP-Protocol-Version": "2025-06-18",
"Accept": "application/json, text/event-stream"
}
}
}Client profiles
The info endpoints return live tool catalogs plus copyable setup profiles for generic MCP clients, Claude Code, and hosted Claude API calls.
GET http://127.0.0.1:8000/mcp/public/info
GET http://127.0.0.1:8000/mcp/infoClaude Code .mcp.json
Use type: "http" for Claude Code remote HTTP servers. Project-scoped files can keep the public read-only tools close to the app repo.
{
"mcpServers": {
"astro-ai-public": {
"type": "http",
"url": "http://127.0.0.1:8000/mcp/public",
"headers": {
"MCP-Protocol-Version": "2025-06-18",
"Accept": "application/json, text/event-stream"
}
}
}
}Claude Code CLI
Use claude mcp add-json when a host expects a single server config object. Replace the token placeholder before connecting protected tools.
claude mcp add-json astro-ai '{"type":"http","url":"http://127.0.0.1:8000/mcp","headers":{"Authorization":"Bearer ASTRO_AI_API_KEY","MCP-Protocol-Version":"2025-06-18","Accept":"application/json, text/event-stream"}}'Claude Messages API
Hosted Claude API MCP calls need a public HTTPS URL. Localhost works for local MCP clients, not hosted API connectors.
{
"mcp_servers": [
{
"type": "url",
"url": "https://api.astro.ai/mcp/public",
"name": "astro-ai-public"
}
],
"tools": [
{
"type": "mcp_toolset",
"mcp_server_name": "astro-ai-public"
}
],
"betas": [
"mcp-client-2025-11-20"
]
}Different MCP hosts use different config wrappers; the stable contract is the endpoint URL plus the headers above. Inspect /mcp/public/info and /mcp/info for the live tool catalog.
119
119 /v1 operations
65
65 POST workflows
41
41 GET resources
235+
235+ calculator contracts
Authentication
Local development is open by default. Production deployments should set ASTRO_AI_API_KEYS and send the key in a header. URL query-string keys are rejected.
Recommended header
Authorization: Bearer ASTRO_AI_API_KEY
The API also accepts x-api-key: ASTRO_AI_API_KEY for clients that cannot set bearer auth. Keep API keys on your backend and never expose them in browser code.
Response envelope
Successful responses return data and meta. The data object is typed per endpoint; meta carries request identity, normalized input, calculator version, warnings, and optional usage.
{
"data": {
"object": "chart",
"ascendant": {
"sign": "Virgo"
}
},
"meta": {
"request_id": "req_abc123",
"calculator_version": "2026.05",
"input": {
"normalized": "request payload"
},
"warnings": []
}
}Errors & rate limits
Errors use the same request ID in error.request_id and meta.request_id. When ASTRO_AI_RATE_LIMIT_PER_MINUTE is configured, limited responses return 429, RateLimit-*, and Retry-After headers.
{
"error": {
"code": "invalid_request",
"message": "request validation failed",
"details": [
{
"path": "body.latitude",
"reason": "Input should be less than or equal to 90"
}
],
"request_id": "req_abc123"
},
"meta": {
"request_id": "req_abc123",
"calculator_version": "2026.05",
"input": {},
"warnings": []
}
}Core concepts
Designed for production API clients and astrology agents that need facts first, provenance always, and predictable contracts.
Facts before prose
Reading endpoints return deterministic facts or traceable summaries. Horoscope prose and sensitive predictions stay behind provenance and safety gates.
Visible calculation lineage
Every warning, source calculator, normalized input, and caveat stays visible to clients.
Registry depth
235+ calculator contracts with stability, compatibility, schemas, and examples.
Curated routes plus registry
Product routes cover common workflows while the calculator registry exposes the broader implementation surface.
Typed envelope
All public endpoints return the same success or error shape, so SDKs and agents can parse results predictably.
Use the product routes first.
The registry is broad by design. Start with high-signal workflows, then drop to raw calculators only when you need exact composition control.
POST
Chart facts
Birth chart, divisions, panchang, dasha, and rendering.
POST Reading contextFacts-only bundles for agents, summaries, and UI layers.
GET Calculator registryDiscover contracts, examples, schemas, and execution gates.
POST Saved product libraryPersist report snapshots, calendar windows, timelines, Teacher answers, Teacher lesson plans, birth-time candidates, and notes.
POST Saved Match FinderStore facts-only compatibility context between two saved people.
GET Parity evidenceSee VedAstro coverage, clone decisions, and safety boundaries.
API Builder
Pick any live OpenAPI operation, inspect the generated example, add an optional bearer token, and send it against this server. Path placeholders stay visible so destructive or account-scoped requests are deliberate.
Select an endpoint to load its generated request example.
Python SDK
TypeScript SDK
Response JSON will appear here.Endpoints
All endpoint examples use the same envelope and authentication model. Search filters the full reference without leaving the page.
Charts
Birth-chart and divisional-chart calculation surfaces.
POST
/v1/charts
Create chart
Create a normalized rasi chart with planets, houses, ascendant, ayanamsa, and source metadata.
Use this when
Start here for any chart, reading, compatibility, or rendering workflow. This is the canonical D1 fact bundle.
Returns
A typed chart object with ayanamsa, observation point, ascendant, planets, houses, signs, degrees, and source metadata.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/charts" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'JSON body
{
"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"
}
}
POST
/v1/charts/divisions/{division}
Create divisional chart
Create a supported divisional chart such as D9, D10, D12, D30, or D60.
Use this when
Use after the base chart when the client needs a specific varga such as D9, D10, D12, D30, or D60.
Returns
A typed chart object with ayanamsa, observation point, ascendant, planets, houses, signs, degrees, and source metadata.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Parameters
division
integer
Required
path parameter.
Example request
cURL
curl -s "https://api.astro.ai/v1/charts/divisions/{division}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'JSON body
{
"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"
}
}Panchang
Day-level lunar calendar factors for a birth or event time.
POST
/v1/panchang/day
Panchang Day
Return weekday, tithi, nakshatra, yoga, karana, and sunrise/sunset context for one input.
Use this when
Use for daily calendar cards, muhurta context, and fact-backed lunar-day UI.
Returns
A panchang_day object with weekday, tithi, nakshatra, yoga, karana, sunrise, sunset, and warnings.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/panchang/day" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'JSON body
{
"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"
}
}Muhurta
Transparent timing windows and hora-style timing helpers.
POST
/v1/muhurta/windows
Muhurta Windows
Return transparent muhurta and hora windows for the requested birth or event time.
Use this when
Use for transparent day-window helpers. The output is timing evidence, not a black-box auspiciousness verdict.
Returns
Named time windows with start/end boundaries and transparent labels.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/muhurta/windows" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'JSON body
{
"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"
}
}Good Time Finder
Guided task-aware muhurta ranking with citations and transparent scoring evidence.
POST
/v1/good-time-finder
Good Time Finder
Rank candidate muhurta windows for a task with panchang context, hora overlap, rejected windows, and citations.
Use this when
Use for a better Good Time Finder workflow: task-aware candidates, visible scoring, citations, and avoidance explanations.
Returns
Ranked candidate windows, rejected windows, scoring breakdowns, panchang summaries, citation IDs, source calculators, and safety policy.
Watch for
Scores are explainable planning context, not lineage-certified success guarantees.
Example request
cURL
curl -s "https://api.astro.ai/v1/good-time-finder" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"start": {
"year": 1998,
"month": 5,
"date": 20,
"hours": 8,
"minutes": 0,
"seconds": 0,
"latitude": 13.0827,
"longitude": 80.2707,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"end": {
"year": 1998,
"month": 5,
"date": 20,
"hours": 20,
"minutes": 0,
"seconds": 0,
"latitude": 13.0827,
"longitude": 80.2707,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"task": "business launch",
"preferred_window_minutes": 60,
"top_k": 5,
"include_classical_citations": true
}'JSON body
{
"start": {
"year": 1998,
"month": 5,
"date": 20,
"hours": 8,
"minutes": 0,
"seconds": 0,
"latitude": 13.0827,
"longitude": 80.2707,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"end": {
"year": 1998,
"month": 5,
"date": 20,
"hours": 20,
"minutes": 0,
"seconds": 0,
"latitude": 13.0827,
"longitude": 80.2707,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"task": "business launch",
"preferred_window_minutes": 60,
"top_k": 5,
"include_classical_citations": true
}Birth Time Finder
Guided birth-time candidate ranking with uncertainty bands and transparent rectification evidence.
POST
/v1/birth-time-finder
Birth Time Finder
Rank candidate birth-time bands from ascendant, house-strength, and Yoni-animal evidence without claiming a final rectification.
Use this when
Use for a better Birth Time Finder workflow: ranked uncertainty bands with visible criteria and evidence scans.
Returns
Ranked birth-time candidates, uncertainty bands, matched criteria, score breakdowns, evidence scans, source calculators, and safety policy.
Watch for
Candidate bands are evidence for review, not a final rectified birth time.
Example request
cURL
curl -s "https://api.astro.ai/v1/birth-time-finder" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"target_ascendant": "Virgo",
"target_house": 1,
"precision_minutes": 30,
"top_k": 5,
"include_evidence_scans": true
}'JSON body
{
"birth": {
"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"
}
},
"target_ascendant": "Virgo",
"target_house": 1,
"precision_minutes": 30,
"top_k": 5,
"include_evidence_scans": true
}Dashas
Deterministic dasha timelines and active-period lookup.
POST
/v1/dashas/chara/active
Dashas Chara Active
Find a research-grade active Chara Dasha period for a specific check time.
Use this when
Use this dashas route when the product needs the specific dashas chara active contract rather than a broader bundle.
Returns
Period chains with lords, start/end times, nesting level, and birth-balance markers.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/dashas/chara/active" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"check_time": "2026-05-22T12:00:00+00:00",
"levels": 2
}'JSON body
{
"birth": {
"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"
}
},
"check_time": "2026-05-22T12:00:00+00:00",
"levels": 2
}
POST
/v1/dashas/vimshottari
Dashas Vimshottari
Return the Vimshottari maha-dasha sequence and birth balance.
Use this when
Use for the top-level life-period sequence and birth balance.
Returns
Period chains with lords, start/end times, nesting level, and birth-balance markers.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/dashas/vimshottari" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'JSON body
{
"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"
}
}
POST
/v1/dashas/vimshottari/active
Dashas Vimshottari Active
Find the active Vimshottari period at a specific check time.
Use this when
Use for an at-a-glance current-period chain at a supplied check time.
Returns
Period chains with lords, start/end times, nesting level, and birth-balance markers.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/dashas/vimshottari/active" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"check_time": "2026-05-22T12:00:00+00:00",
"levels": 2
}'JSON body
{
"birth": {
"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"
}
},
"check_time": "2026-05-22T12:00:00+00:00",
"levels": 2
}
POST
/v1/dashas/vimshottari/timeline
Dashas Vimshottari Timeline
Return nested Vimshottari periods across a bounded timeline.
Use this when
Use when the product needs nested periods across a bounded scan window.
Returns
Period chains with lords, start/end times, nesting level, and birth-balance markers.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/dashas/vimshottari/timeline" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"levels": 2,
"scan_years": 10
}'JSON body
{
"birth": {
"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"
}
},
"levels": 2,
"scan_years": 10
}Life Timeline
Evidence-first life-map timelines composed from dasha, event windows, and Ashtakavarga research signals.
POST
/v1/life-timeline
Life Timeline
Return an evidence-first life timeline from dasha periods, sampled event windows, and optional Ashtakavarga distribution evidence.
Use this when
Use as a safe Life Predictor replacement: evidence rows, confidence labels, and no deterministic event claims.
Returns
Dasha period evidence, sampled event windows, optional Ashtakavarga life-map distribution, source IDs, safety policy, and notes.
Watch for
This is not a prediction engine. Present rows as evidence windows and research signals, never as guaranteed outcomes.
Example request
cURL
curl -s "https://api.astro.ai/v1/life-timeline" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"time_preset": "age18to21",
"dasha_levels": 2,
"include_ashtakavarga": true,
"include_event_windows": true,
"event_tags": [
"Travel",
"Building"
],
"event_precision_hours": 168,
"event_limit": 8
}'JSON body
{
"birth": {
"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"
}
},
"time_preset": "age18to21",
"dasha_levels": 2,
"include_ashtakavarga": true,
"include_event_windows": true,
"event_tags": [
"Travel",
"Building"
],
"event_precision_hours": 168,
"event_limit": 8
}Reports
Source-backed product reports assembled from deterministic calculator facts.
POST
/v1/reports/chart
Reports Chart
Return a source-backed chart report with auditable sections, facts, calculator IDs, and safety policy.
Use this when
Use when a product needs a report-style chart summary while preserving fact citations and no-prediction policy.
Returns
Template-only report sections, audit facts, source calculator IDs, source paths, safety policy, and optional source payloads.
Watch for
Report prose is deterministic template text. Do not display it as an LLM reading or a guaranteed prediction.
Example request
cURL
curl -s "https://api.astro.ai/v1/reports/chart" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"include_sections": [
"chart_orientation",
"timing_context",
"strength_context"
],
"detail_level": "brief",
"include_source_payloads": false
}'JSON body
{
"birth": {
"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"
}
},
"include_sections": [
"chart_orientation",
"timing_context",
"strength_context"
],
"detail_level": "brief",
"include_source_payloads": false
}Readings
Facts-first bundles for downstream reading products.
POST
/v1/readings/facts
Readings Facts
Collect deterministic facts for an agent or reading pipeline without generating prose.
Use this when
Use as the safest input to an agent or reading UI because it returns facts, IDs, and warnings without invented prose.
Returns
Fact bundles or deterministic summaries with cost units, source IDs, and warnings.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/readings/facts" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'JSON body
{
"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"
}
}
POST
/v1/readings/summary
Readings Summary
Return a deterministic reading summary that traces every statement to source facts.
Use this when
Use when the product needs deterministic text sections that remain traceable to source fact IDs.
Returns
Fact bundles or deterministic summaries with cost units, source IDs, and warnings.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/readings/summary" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'JSON body
{
"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"
}
}Predictions
Gated prediction metadata and source-backed fact matches.
POST
/v1/predictions/gate
Predictions Gate
Validate a prediction request and return the gates required before execution.
Use this when
Use this predictions route when the product needs the specific predictions gate contract rather than a broader bundle.
Returns
Provenance metadata or facts-only supported matches. Sensitive prediction prose is intentionally gated.
Watch for
Treat this surface as safety-critical. The native API exposes provenance and supported facts, not broad horoscope prose.
Example request
cURL
curl -s "https://api.astro.ai/v1/predictions/gate" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vedastro_name": "Chapter10Predictions",
"input": {
"time": {
"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"
}
}
},
"include_corpus_summary": false
}'JSON body
{
"vedastro_name": "Chapter10Predictions",
"input": {
"time": {
"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"
}
}
},
"include_corpus_summary": false
}
POST
/v1/predictions/horoscope-matches
Predictions Horoscope Matches
Evaluate the supported facts-only horoscope-prediction subset without returning prose.
Use this when
Use this predictions route when the product needs the specific predictions horoscope matches contract rather than a broader bundle.
Returns
Provenance metadata or facts-only supported matches. Sensitive prediction prose is intentionally gated.
Watch for
Treat this surface as safety-critical. The native API exposes provenance and supported facts, not broad horoscope prose.
Example request
cURL
curl -s "https://api.astro.ai/v1/predictions/horoscope-matches" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"native_sex": "male",
"include_inactive_supported": false,
"limit": 25
}'JSON body
{
"birth": {
"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"
}
},
"native_sex": "male",
"include_inactive_supported": false,
"limit": 25
}
GET
/v1/predictions/provenance
Predictions Provenance
List gated VedAstro prediction metadata and provenance boundaries.
Use this when
Use this predictions route when the product needs the specific predictions provenance contract rather than a broader bundle.
Returns
Provenance metadata or facts-only supported matches. Sensitive prediction prose is intentionally gated.
Watch for
Treat this surface as safety-critical. The native API exposes provenance and supported facts, not broad horoscope prose.
Parameters
vedastro_name
mixed
Optional
query parameter.
limit
integer
Optional
query parameter.
include_corpus_summary
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/predictions/provenance" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"Compatibility
Relationship and match-context calculation surfaces.
POST
/v1/compatibility/ashtakoot
Compatibility Ashtakoot
Return a beta scored Ashtakoot compatibility report for two birth inputs.
Use this when
Use for a scored eight-kuta compatibility report where beta status and factor evidence are visible.
Returns
Compatibility facts, factor scores, or chat-ready context without generating hidden prose.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/compatibility/ashtakoot" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"male": {
"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"
}
},
"female": {
"year": 1998,
"month": 6,
"date": 18,
"hours": 9,
"minutes": 10,
"seconds": 0,
"latitude": 12.9716,
"longitude": 77.5946,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
}
}'JSON body
{
"male": {
"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"
}
},
"female": {
"year": 1998,
"month": 6,
"date": 18,
"hours": 9,
"minutes": 10,
"seconds": 0,
"latitude": 12.9716,
"longitude": 77.5946,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
}
}
POST
/v1/compatibility/match-chat
Compatibility Match Chat
Return facts-only MatchChat context for compatibility workflows.
Use this when
Use as compatibility context for a future chat layer. The endpoint itself does not generate LLM prose.
Returns
Compatibility facts, factor scores, or chat-ready context without generating hidden prose.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/compatibility/match-chat" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"male": {
"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"
}
},
"female": {
"year": 1998,
"month": 6,
"date": 18,
"hours": 9,
"minutes": 10,
"seconds": 0,
"latitude": 12.9716,
"longitude": 77.5946,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"user_question": "Which compatibility factors need attention?",
"include_facts": true
}'JSON body
{
"male": {
"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"
}
},
"female": {
"year": 1998,
"month": 6,
"date": 18,
"hours": 9,
"minutes": 10,
"seconds": 0,
"latitude": 12.9716,
"longitude": 77.5946,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"user_question": "Which compatibility factors need attention?",
"include_facts": true
}Strength
Planet-strength reports with research-grade caveats.
POST
/v1/strength/shadbala
Strength Shadbala
Return research-grade Shadbala evidence for all planets or one selected planet.
Use this when
Use this strength route when the product needs the specific strength shadbala contract rather than a broader bundle.
Returns
Research-grade strength evidence with component caveats and usage cost.
Watch for
Strength formulas are convention-sensitive; use warnings and validation status before production interpretation.
Example request
cURL
curl -s "https://api.astro.ai/v1/strength/shadbala" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"planet": "Sun",
"include_detail": true
}'JSON body
{
"birth": {
"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"
}
},
"planet": "Sun",
"include_detail": true
}Ashtakavarga
Bindu charts, reductions, and life-map evidence.
POST
/v1/ashtakavarga
Ashtakavarga
Return Bhinnashtakavarga, Sarvashtakavarga, optional reductions, and optional life-map evidence.
Use this when
Use this ashtakavarga route when the product needs the specific ashtakavarga contract rather than a broader bundle.
Returns
Bindu charts, Sarvashtakavarga totals, optional reductions, and optional life-map evidence.
Watch for
Many rows are research-stage. Inspect stability and accuracy status when using registry calculators.
Example request
cURL
curl -s "https://api.astro.ai/v1/ashtakavarga" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"include_reductions": true,
"include_life_map": true
}'JSON body
{
"birth": {
"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"
}
},
"include_reductions": true,
"include_life_map": true
}Rendering
SVG payloads for chart, kundali, and sky-chart views.
POST
/v1/render/chart
Render Chart
Return an SVG chart payload optimized for fact visibility.
Use this when
Use when an app needs a lightweight SVG visual without building a chart renderer itself.
Returns
SVG payloads plus metadata for chart, kundali, and sky-chart views.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/render/chart" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'JSON body
{
"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"
}
}
POST
/v1/render/kundali
Render Kundali
Return a layout-compatible North or South Indian kundali SVG payload.
Use this when
Use for North or South Indian kundali layouts backed by the same chart facts.
Returns
SVG payloads plus metadata for chart, kundali, and sky-chart views.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/render/kundali" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"style": "south_indian",
"division": 1
}'JSON body
{
"birth": {
"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"
}
},
"style": "south_indian",
"division": 1
}
POST
/v1/render/sky-chart
Render Sky Chart
Return a sky-chart SVG payload for the requested birth input.
Use this when
Use this rendering route when the product needs the specific render sky chart contract rather than a broader bundle.
Returns
SVG payloads plus metadata for chart, kundali, and sky-chart views.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/render/sky-chart" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'JSON body
{
"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"
}
}Calculator Registry
Discover, inspect, and execute calculator contracts.
GET
/v1/calculation-sets
Calculation Sets
List curated calculator sets for common workflows.
Use this when
Use to discover curated bundles such as basic chart facts or agent reading facts.
Returns
Metadata, schemas, examples, run results, batch results, or curated calculation-set outputs.
Watch for
Internal or experimental calculators require explicit execution options before they run.
Parameters
include_calculator_metadata
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/calculation-sets" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/calculation-sets/{set_id}
Calculation Sets Set Id
Retrieve one curated calculation set and its calculator composition.
Use this when
Use this calculator registry route when the product needs the specific calculation sets set id contract rather than a broader bundle.
Returns
Metadata, schemas, examples, run results, batch results, or curated calculation-set outputs.
Watch for
Internal or experimental calculators require explicit execution options before they run.
Parameters
set_id
string
Required
path parameter.
include_calculator_metadata
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/calculation-sets/{set_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/calculation-sets/{set_id}:run
Run calculation set
Execute a curated calculation set such as basic chart facts or agent reading facts.
Use this when
Use when a supported bundle is a better contract than hand-picking calculator IDs.
Returns
Metadata, schemas, examples, run results, batch results, or curated calculation-set outputs.
Watch for
Internal or experimental calculators require explicit execution options before they run.
Parameters
set_id
string
Required
path parameter.
Example request
cURL
curl -s "https://api.astro.ai/v1/calculation-sets/{set_id}:run" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}'JSON body
{
"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"
}
}
GET
/v1/calculators
Calculators
List public calculator contracts with pagination, filters, and registry fingerprint metadata.
Use this when
Use for discovery before calling the registry runner. Filter by group, stability, schema, or accuracy status.
Returns
Metadata, schemas, examples, run results, batch results, or curated calculation-set outputs.
Watch for
GET registry responses are public in local development but should still be served from your backend in production clients.
Parameters
group
mixed
Optional
query parameter.
stability
mixed
Optional
query parameter.
accuracy_status
mixed
Optional
query parameter.
input_schema_ref
mixed
Optional
query parameter.
order
string
Optional
query parameter.
include_internal
boolean
Optional
query parameter.
limit
integer
Optional
query parameter.
after
mixed
Optional
Return rows after this calculator id.
Example request
curl -s "https://api.astro.ai/v1/calculators" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/calculators/{calculator_id}
Calculators Calculator Id
Retrieve one calculator contract with schemas, examples, stability, and compatibility metadata.
Use this when
Use to inspect one contract before execution, especially stability and schema refs.
Returns
Metadata, schemas, examples, run results, batch results, or curated calculation-set outputs.
Watch for
GET registry responses are public in local development but should still be served from your backend in production clients.
Parameters
calculator_id
string
Required
path parameter.
include_internal
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/calculators/{calculator_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/calculators/{calculator_id}/example
Calculators Calculator Id Example
Return a runnable calculator execution payload for a selected calculator.
Use this when
Use to fetch a runnable sample payload for the selected calculator.
Returns
Metadata, schemas, examples, run results, batch results, or curated calculation-set outputs.
Watch for
GET registry responses are public in local development but should still be served from your backend in production clients.
Parameters
calculator_id
string
Required
path parameter.
include_internal
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/calculators/{calculator_id}/example" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/calculators/{calculator_id}:run
Run calculator
Execute one calculator by ID with explicit internal and experimental gates.
Use this when
Use when a product needs a specific long-tail calculator without a dedicated route.
Returns
Metadata, schemas, examples, run results, batch results, or curated calculation-set outputs.
Watch for
Internal or experimental calculators require explicit execution options before they run.
Parameters
calculator_id
string
Required
path parameter.
Example request
cURL
curl -s "https://api.astro.ai/v1/calculators/{calculator_id}:run" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"birth": {
"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"
}
}
}
}'JSON body
{
"input": {
"birth": {
"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"
}
}
}
}
POST
/v1/calculators:batch
Run calculator batch
Execute multiple calculators with shared input and per-item overrides.
Use this when
Use to reduce client round trips when several calculators share the same birth input.
Returns
Metadata, schemas, examples, run results, batch results, or curated calculation-set outputs.
Watch for
Internal or experimental calculators require explicit execution options before they run.
Example request
cURL
curl -s "https://api.astro.ai/v1/calculators:batch" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"birth": {
"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"
}
}
},
"calculations": [
{
"id": "julian-day",
"calculator": "time.julian_day"
},
{
"id": "planets",
"calculator": "chart.planets"
}
]
}'JSON body
{
"input": {
"birth": {
"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"
}
}
},
"calculations": [
{
"id": "julian-day",
"calculator": "time.julian_day"
},
{
"id": "planets",
"calculator": "chart.planets"
}
]
}
GET
/v1/schemas
Schemas
List strict and documented schema references used by calculator contracts.
Use this when
Use for SDK generation, validation UI, and client-side form builders.
Returns
Metadata, schemas, examples, run results, batch results, or curated calculation-set outputs.
Watch for
Internal or experimental calculators require explicit execution options before they run.
Example request
curl -s "https://api.astro.ai/v1/schemas" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/schemas/{schema_ref}
Schemas Schema Ref
Retrieve one schema reference by ID.
Use this when
Use this calculator registry route when the product needs the specific schemas schema ref contract rather than a broader bundle.
Returns
Metadata, schemas, examples, run results, batch results, or curated calculation-set outputs.
Watch for
Internal or experimental calculators require explicit execution options before they run.
Parameters
schema_ref
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/schemas/{schema_ref}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"Classical Texts
Citation-backed classical text catalog and deterministic retrieval outlines.
GET
/v1/classical-texts
Classical Texts
List the curated classical-text corpus and source policy.
Use this when
Use before RAG-style workflows to show the available source corpus and copyright boundary.
Returns
Catalog records, passage summaries, citation IDs, source paths, source policy, and deterministic retrieval outlines.
Watch for
This is not a copied book corpus. It returns curated paraphrase notes and citation metadata until licensing and OCR policy are complete.
Example request
curl -s "https://api.astro.ai/v1/classical-texts" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/classical-texts/answer
Classical Texts Answer
Return a deterministic retrieval outline with citations for a classical-text query.
Use this when
Use as a no-LLM RAG primitive: it returns an outline and citations rather than free-form doctrine.
Returns
Catalog records, passage summaries, citation IDs, source paths, source policy, and deterministic retrieval outlines.
Watch for
This is not a copied book corpus. It returns curated paraphrase notes and citation metadata until licensing and OCR policy are complete.
Example request
cURL
curl -s "https://api.astro.ai/v1/classical-texts/answer" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "How should Good Time Finder use panchang factors?",
"max_citations": 4
}'JSON body
{
"query": "How should Good Time Finder use panchang factors?",
"max_citations": 4
}
POST
/v1/classical-texts/search
Classical Texts Search
Search curated classical-text passage summaries and citation metadata.
Use this when
Use to retrieve citation rows for source-backed reports, teacher flows, or Good Time Finder explanations.
Returns
Catalog records, passage summaries, citation IDs, source paths, source policy, and deterministic retrieval outlines.
Watch for
This is not a copied book corpus. It returns curated paraphrase notes and citation metadata until licensing and OCR policy are complete.
Example request
cURL
curl -s "https://api.astro.ai/v1/classical-texts/search" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "muhurta tithi nakshatra good time",
"limit": 5,
"topics": [
"muhurta"
]
}'JSON body
{
"query": "muhurta tithi nakshatra good time",
"limit": 5,
"topics": [
"muhurta"
]
}
GET
/v1/classical-texts/{text_id}
Classical Texts Text Id
Retrieve one classical text record and its curated passage notes.
Use this when
Use when a client needs source metadata and passage notes for one classical work.
Returns
Catalog records, passage summaries, citation IDs, source paths, source policy, and deterministic retrieval outlines.
Watch for
This is not a copied book corpus. It returns curated paraphrase notes and citation metadata until licensing and OCR policy are complete.
Parameters
text_id
string
Required
path parameter.
include_passages
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/classical-texts/{text_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/classical-texts/{text_id}/chapters
Classical Texts Text Id Chapters
Retrieve citation-backed study units for one classical text.
Use this when
Use when a Teacher UI needs chapter-like study units without copied book pages.
Returns
Catalog records, passage summaries, citation IDs, source paths, source policy, and deterministic retrieval outlines.
Watch for
This is not a copied book corpus. It returns curated paraphrase notes and citation metadata until licensing and OCR policy are complete.
Parameters
text_id
string
Required
path parameter.
include_passages
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/classical-texts/{text_id}/chapters" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"Teacher
Source-backed teaching outlines and lesson plans that combine classical citations and optional chart facts without LLM prose.
POST
/v1/teacher/answer
Teacher Answer
Return a source-backed teacher outline from classical citations and optional chart facts.
Use this when
Use for Teacher-style product flows where users ask conceptual questions and optionally provide birth context for auditable chart evidence.
Returns
A deterministic answer outline or lesson sequence, classical citation IDs, optional chart report facts, source calculators, and safety policy.
Watch for
Teacher outlines and lesson plans are product scaffolding for learning and explanations, not generated readings or deterministic predictions.
Example request
cURL
curl -s "https://api.astro.ai/v1/teacher/answer" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "How should I understand my Moon nakshatra and current timing?",
"birth": {
"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"
}
},
"max_citations": 4,
"topics": [
"chart",
"dashas"
],
"include_chart_context": true,
"include_classical_context": true,
"detail_level": "brief"
}'JSON body
{
"question": "How should I understand my Moon nakshatra and current timing?",
"birth": {
"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"
}
},
"max_citations": 4,
"topics": [
"chart",
"dashas"
],
"include_chart_context": true,
"include_classical_context": true,
"detail_level": "brief"
}
POST
/v1/teacher/lesson-plan
Teacher Lesson Plan
Return a source-backed teacher lesson sequence from citations and optional chart facts.
Use this when
Use when a client needs a saved study sequence with citations, optional chart facts, and follow-up prompts.
Returns
A deterministic answer outline or lesson sequence, classical citation IDs, optional chart report facts, source calculators, and safety policy.
Watch for
Teacher outlines and lesson plans are product scaffolding for learning and explanations, not generated readings or deterministic predictions.
Example request
cURL
curl -s "https://api.astro.ai/v1/teacher/lesson-plan" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"topic": "Moon nakshatra and current timing",
"birth": {
"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"
}
},
"lesson_count": 4,
"max_citations": 4,
"topics": [
"chart",
"dashas"
],
"goal": "understand_chart"
}'JSON body
{
"topic": "Moon nakshatra and current timing",
"birth": {
"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"
}
},
"lesson_count": 4,
"max_citations": 4,
"topics": [
"chart",
"dashas"
],
"goal": "understand_chart"
}Search
Local lexical search over calculators, docs, and reference metadata.
POST
/v1/search/calculators
Search Calculators
Search implemented calculator metadata.
Use this when
Use this search route when the product needs the specific search calculators contract rather than a broader bundle.
Returns
Ranked local search hits with source, snippet, and score metadata.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/search/calculators" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "moon nakshatra",
"limit": 5
}'JSON body
{
"query": "moon nakshatra",
"limit": 5
}
POST
/v1/search/context
Search Context
Search curated local astrology context for agent workflows.
Use this when
Use when an agent needs a compact, deterministic context pack across docs, calculators, and coverage metadata.
Returns
Ranked local search hits with source, snippet, and score metadata.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/search/context" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "travel event",
"limit": 3
}'JSON body
{
"query": "travel event",
"limit": 3
}
POST
/v1/search/docs
Search Docs
Search local documentation and implementation notes.
Use this when
Use this search route when the product needs the specific search docs contract rather than a broader bundle.
Returns
Ranked local search hits with source, snippet, and score metadata.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/search/docs" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "typed calculator registry",
"limit": 5
}'JSON body
{
"query": "typed calculator registry",
"limit": 5
}
POST
/v1/search/vedastro
Search Vedastro
Search the generated VedAstro reference and coverage inventory.
Use this when
Use this search route when the product needs the specific search vedastro contract rather than a broader bundle.
Returns
Ranked local search hits with source, snippet, and score metadata.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/search/vedastro" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Chapter10Predictions",
"limit": 5
}'JSON body
{
"query": "Chapter10Predictions",
"limit": 5
}Geo & Time
Coordinate, timezone, address, IP, and standard-time helpers.
POST
/v1/geo/ip
Geo Ip
Resolve approximate location context from an IP address.
Use this when
Use this geo & time route when the product needs the specific geo ip contract rather than a broader bundle.
Returns
Normalized place, coordinate, timezone, offset, and provider metadata.
Watch for
Provider routes can depend on network and cache settings. Disable providers explicitly in offline deployments.
Example request
cURL
curl -s "https://api.astro.ai/v1/geo/ip" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ip_address": "8.8.8.8"
}'JSON body
{
"ip_address": "8.8.8.8"
}
POST
/v1/geo/resolve
Geo Resolve
Resolve coordinates into provider-backed location context.
Use this when
Use after location selection to normalize coordinates, timezone, and provider metadata.
Returns
Normalized place, coordinate, timezone, offset, and provider metadata.
Watch for
Provider routes can depend on network and cache settings. Disable providers explicitly in offline deployments.
Example request
cURL
curl -s "https://api.astro.ai/v1/geo/resolve" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"latitude": 13.0827,
"longitude": 80.2707
}'JSON body
{
"latitude": 13.0827,
"longitude": 80.2707
}
POST
/v1/geo/search
Geo Search
Search provider-backed locations by address text.
Use this when
Use before asking a user to confirm a birth or event location.
Returns
Normalized place, coordinate, timezone, offset, and provider metadata.
Watch for
Provider routes can depend on network and cache settings. Disable providers explicitly in offline deployments.
Example request
cURL
curl -s "https://api.astro.ai/v1/geo/search" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": "Chennai, India",
"limit": 5
}'JSON body
{
"address": "Chennai, India",
"limit": 5
}
POST
/v1/geo/standard-time-now
Geo Standard Time Now
Return the current standard time at a resolved location.
Use this when
Use this geo & time route when the product needs the specific geo standard time now contract rather than a broader bundle.
Returns
Normalized place, coordinate, timezone, offset, and provider metadata.
Watch for
Provider routes can depend on network and cache settings. Disable providers explicitly in offline deployments.
Example request
cURL
curl -s "https://api.astro.ai/v1/geo/standard-time-now" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"location_name": "Chennai, India"
}'JSON body
{
"location_name": "Chennai, India"
}
POST
/v1/timezones/offset
Timezones Offset
Return timezone offset data for a coordinate and local date-time.
Use this when
Use when you already have coordinates and civil date-time and only need timezone offset context.
Returns
Normalized place, coordinate, timezone, offset, and provider metadata.
Watch for
Provider routes can depend on network and cache settings. Disable providers explicitly in offline deployments.
Example request
cURL
curl -s "https://api.astro.ai/v1/timezones/offset" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"year": 2026,
"month": 5,
"date": 22,
"hours": 12,
"minutes": 0,
"latitude": 13.0827,
"longitude": 80.2707
}'JSON body
{
"year": 2026,
"month": 5,
"date": 22,
"hours": 12,
"minutes": 0,
"latitude": 13.0827,
"longitude": 80.2707
}Autofill
Product-facing suggestions for birth, marriage, and location workflows.
POST
/v1/autofill/birth-location
Autofill Birth Location
Return birth-location candidates from a provider-backed address lookup.
Use this when
Use this autofill route when the product needs the specific autofill birth location contract rather than a broader bundle.
Returns
Candidate lists for product forms with explicit basis and warnings.
Watch for
Autofill routes suggest candidates for user confirmation; they are not hidden ML truth.
Example request
cURL
curl -s "https://api.astro.ai/v1/autofill/birth-location" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": "Chennai, India",
"limit": 5
}'JSON body
{
"address": "Chennai, India",
"limit": 5
}
POST
/v1/autofill/birth-time
Autofill Birth Time
Return candidate birth times from transparent chart evidence.
Use this when
Use for candidate ranking against explicit targets. It is evidence for review, not a final rectification claim.
Returns
Candidate lists for product forms with explicit basis and warnings.
Watch for
Autofill routes suggest candidates for user confirmation; they are not hidden ML truth.
Example request
cURL
curl -s "https://api.astro.ai/v1/autofill/birth-time" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"target_ascendant": "Virgo",
"precision_minutes": 60,
"top_k": 5
}'JSON body
{
"birth": {
"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"
}
},
"target_ascendant": "Virgo",
"precision_minutes": 60,
"top_k": 5
}
POST
/v1/autofill/birth-time-location
Autofill Birth Time Location
Return combined birth-time and birth-location candidates.
Use this when
Use this autofill route when the product needs the specific autofill birth time location contract rather than a broader bundle.
Returns
Candidate lists for product forms with explicit basis and warnings.
Watch for
Autofill routes suggest candidates for user confirmation; they are not hidden ML truth.
Example request
cURL
curl -s "https://api.astro.ai/v1/autofill/birth-time-location" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"address": "Chennai, India",
"target_ascendant": "Virgo",
"precision_minutes": 60,
"top_k": 5
}'JSON body
{
"birth": {
"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"
}
},
"address": "Chennai, India",
"target_ascendant": "Virgo",
"precision_minutes": 60,
"top_k": 5
}
POST
/v1/autofill/marriage-partner-name
Autofill Marriage Partner Name
Return deterministic partner-name suggestions.
Use this when
Use this autofill route when the product needs the specific autofill marriage partner name contract rather than a broader bundle.
Returns
Candidate lists for product forms with explicit basis and warnings.
Watch for
Autofill routes suggest candidates for user confirmation; they are not hidden ML truth.
Example request
cURL
curl -s "https://api.astro.ai/v1/autofill/marriage-partner-name" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "marriage partner name",
"number_of_names": 5
}'JSON body
{
"description": "marriage partner name",
"number_of_names": 5
}
POST
/v1/autofill/marriage-tags
Autofill Marriage Tags
Return marriage workflow tags from compatibility context.
Use this when
Use this autofill route when the product needs the specific autofill marriage tags contract rather than a broader bundle.
Returns
Candidate lists for product forms with explicit basis and warnings.
Watch for
Autofill routes suggest candidates for user confirmation; they are not hidden ML truth.
Example request
cURL
curl -s "https://api.astro.ai/v1/autofill/marriage-tags" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"male": {
"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"
}
},
"female": {
"year": 1998,
"month": 6,
"date": 18,
"hours": 9,
"minutes": 10,
"seconds": 0,
"latitude": 12.9716,
"longitude": 77.5946,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"limit": 12
}'JSON body
{
"male": {
"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"
}
},
"female": {
"year": 1998,
"month": 6,
"date": 18,
"hours": 9,
"minutes": 10,
"seconds": 0,
"latitude": 12.9716,
"longitude": 77.5946,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"limit": 12
}Rectification
Evidence scans for candidate birth times.
POST
/v1/rectification/house-strength
Rectification House Strength
Scan candidate birth times for target house-strength evidence.
Use this when
Use this rectification route when the product needs the specific rectification house strength contract rather than a broader bundle.
Returns
Ranked or grouped candidate time intervals with transparent evidence.
Watch for
Candidate scans are evidence tools. Do not present them as final birth-time predictions.
Example request
cURL
curl -s "https://api.astro.ai/v1/rectification/house-strength" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"target_house": 1,
"precision_minutes": 120
}'JSON body
{
"birth": {
"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"
}
},
"target_house": 1,
"precision_minutes": 120
}
POST
/v1/rectification/rising-sign
Rectification Rising Sign
Scan candidate birth times for a target rising sign.
Use this when
Use for a transparent same-day scan where the target rising sign is known.
Returns
Ranked or grouped candidate time intervals with transparent evidence.
Watch for
Candidate scans are evidence tools. Do not present them as final birth-time predictions.
Example request
cURL
curl -s "https://api.astro.ai/v1/rectification/rising-sign" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"target_ascendant": "Virgo",
"precision_minutes": 60
}'JSON body
{
"birth": {
"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"
}
},
"target_ascendant": "Virgo",
"precision_minutes": 60
}
POST
/v1/rectification/yoni-animal
Rectification Yoni Animal
Scan candidate birth times for a target Yoni animal.
Use this when
Use this rectification route when the product needs the specific rectification yoni animal contract rather than a broader bundle.
Returns
Ranked or grouped candidate time intervals with transparent evidence.
Watch for
Candidate scans are evidence tools. Do not present them as final birth-time predictions.
Example request
cURL
curl -s "https://api.astro.ai/v1/rectification/yoni-animal" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"possible_birth_time": {
"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"
}
},
"precision_hours": 6,
"target_animal": "Horse"
}'JSON body
{
"possible_birth_time": {
"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"
}
},
"precision_hours": 6,
"target_animal": "Horse"
}Names
Deterministic name suggestions and number-aware naming helpers.
POST
/v1/names/generate
Names Generate
Generate deterministic names from tone, constraints, and optional number targets.
Use this when
Use for deterministic name suggestions from a small local candidate pool and numerology evidence.
Returns
Deterministic candidate names with number evidence, matched terms, and warnings.
Watch for
The candidate pool is intentionally small until naming policy and language coverage are defined.
Example request
cURL
curl -s "https://api.astro.ai/v1/names/generate" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"description": "traditional Tamil name with a calm devotional tone",
"number_of_names": 5
}'JSON body
{
"description": "traditional Tamil name with a calm devotional tone",
"number_of_names": 5
}Time Ranges
VedAstro-style time range presets, counts, and CSV lists.
POST
/v1/time-ranges/csv
Time Ranges Csv
Generate a CSV-style list of times between two endpoints.
Use this when
Use this time ranges route when the product needs the specific time ranges csv contract rather than a broader bundle.
Returns
Resolved ranges, day counts, or CSV-style time rows.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/time-ranges/csv" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"start": {
"year": 1998,
"month": 5,
"date": 20,
"hours": 8,
"minutes": 25,
"seconds": 0,
"latitude": 13.0827,
"longitude": 80.2707,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"end": {
"year": 1998,
"month": 5,
"date": 20,
"hours": 18,
"minutes": 25,
"seconds": 0,
"latitude": 13.0827,
"longitude": 80.2707,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"hours_between": 2
}'JSON body
{
"start": {
"year": 1998,
"month": 5,
"date": 20,
"hours": 8,
"minutes": 25,
"seconds": 0,
"latitude": 13.0827,
"longitude": 80.2707,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"end": {
"year": 1998,
"month": 5,
"date": 20,
"hours": 18,
"minutes": 25,
"seconds": 0,
"latitude": 13.0827,
"longitude": 80.2707,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
},
"hours_between": 2
}
POST
/v1/time-ranges/days
Time Ranges Days
Count days in a named time-range preset.
Use this when
Use this time ranges route when the product needs the specific time ranges days contract rather than a broader bundle.
Returns
Resolved ranges, day counts, or CSV-style time rows.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/time-ranges/days" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"preset": "3weeks"
}'JSON body
{
"birth": {
"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"
}
},
"preset": "3weeks"
}
POST
/v1/time-ranges/resolve
Time Ranges Resolve
Resolve a named time-range preset into start and end timestamps.
Use this when
Use this time ranges route when the product needs the specific time ranges resolve contract rather than a broader bundle.
Returns
Resolved ranges, day counts, or CSV-style time rows.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/time-ranges/resolve" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"preset": "age1to3"
}'JSON body
{
"birth": {
"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"
}
},
"preset": "age1to3"
}Product State
Saved people, calculation history, product-library snapshots, client sessions, and journal events for reusable workflows.
GET
/v1/attachments
List Attachments
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific list attachments contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
mixed
Optional
query parameter.
kind
mixed
Optional
query parameter.
source_type
mixed
Optional
query parameter.
source_id
mixed
Optional
query parameter.
limit
integer
Optional
query parameter.
after
mixed
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/attachments" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/attachments
Create Attachment
Create a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific create attachment contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Example request
cURL
curl -s "https://api.astro.ai/v1/attachments" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Client intake notes",
"kind": "document",
"person_id": "person_...",
"source_type": "client_session",
"source_id": "session_...",
"file_name": "intake-notes.pdf",
"media_type": "application/pdf",
"summary": "Client supplied context for later journal and Teacher workflows.",
"tags": [
"intake",
"source"
]
}'JSON body
{
"title": "Client intake notes",
"kind": "document",
"person_id": "person_...",
"source_type": "client_session",
"source_id": "session_...",
"file_name": "intake-notes.pdf",
"media_type": "application/pdf",
"summary": "Client supplied context for later journal and Teacher workflows.",
"tags": [
"intake",
"source"
]
}
DELETE
/v1/attachments/{attachment_id}
Delete Attachment
Create a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific delete attachment contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
attachment_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/attachments/{attachment_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/attachments/{attachment_id}
Get Attachment
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific get attachment contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
attachment_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/attachments/{attachment_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
PATCH
/v1/attachments/{attachment_id}
Update Attachment
Create a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific update attachment contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
attachment_id
string
Required
path parameter.
Example request
cURL
curl -s "https://api.astro.ai/v1/attachments/{attachment_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Updated intake notes",
"summary": "Reviewed client supplied context.",
"tags": [
"intake",
"reviewed"
]
}'JSON body
{
"title": "Updated intake notes",
"summary": "Reviewed client supplied context.",
"tags": [
"intake",
"reviewed"
]
}
GET
/v1/calculation-runs
Calculation Runs
Create or list calculation history entries for saved people or direct birth payloads.
Use this when
Use to persist traceable calculation history for a saved person or direct birth payload.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
mixed
Optional
query parameter.
limit
integer
Optional
query parameter.
after
mixed
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/calculation-runs" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/calculation-runs
Calculation Runs
Create or list calculation history entries for saved people or direct birth payloads.
Use this when
Use to persist traceable calculation history for a saved person or direct birth payload.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Example request
cURL
curl -s "https://api.astro.ai/v1/calculation-runs" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"person_id": "person_example",
"calculation": "reading_summary",
"title": "Initial fact-traced reading"
}'JSON body
{
"person_id": "person_example",
"calculation": "reading_summary",
"title": "Initial fact-traced reading"
}
GET
/v1/calculation-runs/{run_id}
Calculation Runs Run Id
Fetch one saved calculation-run result and its trace metadata.
Use this when
Use to replay or inspect a previous chart, panchang, reading, or facts run.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
run_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/calculation-runs/{run_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/client-sessions
Client Sessions
Create or list guided client history around saved people, prompts, and linked artifacts.
Use this when
Use to persist a chat-like guided client workspace without generating astrology replies.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
mixed
Optional
query parameter.
status
mixed
Optional
query parameter.
limit
integer
Optional
query parameter.
after
mixed
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/client-sessions" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/client-sessions
Client Sessions
Create or list guided client history around saved people, prompts, and linked artifacts.
Use this when
Use to persist a chat-like guided client workspace without generating astrology replies.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Example request
cURL
curl -s "https://api.astro.ai/v1/client-sessions" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Moon nakshatra onboarding",
"person_id": "person_...",
"mode": "teacher",
"initial_message": "Help me understand my Moon nakshatra and current timing.",
"tags": [
"workbench",
"teacher"
]
}'JSON body
{
"title": "Moon nakshatra onboarding",
"person_id": "person_...",
"mode": "teacher",
"initial_message": "Help me understand my Moon nakshatra and current timing.",
"tags": [
"workbench",
"teacher"
]
}
DELETE
/v1/client-sessions/{session_id}
Client Sessions Session Id
Fetch, archive, update, or delete one guided client session.
Use this when
Use to inspect, archive, or remove one saved session while keeping linked artifacts intact.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
session_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/client-sessions/{session_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/client-sessions/{session_id}
Client Sessions Session Id
Fetch, archive, update, or delete one guided client session.
Use this when
Use to inspect, archive, or remove one saved session while keeping linked artifacts intact.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
session_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/client-sessions/{session_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
PATCH
/v1/client-sessions/{session_id}
Client Sessions Session Id
Fetch, archive, update, or delete one guided client session.
Use this when
Use to inspect, archive, or remove one saved session while keeping linked artifacts intact.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
session_id
string
Required
path parameter.
Example request
cURL
curl -s "https://api.astro.ai/v1/client-sessions/{session_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": {
"birth": {
"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"
}
}
}
}'JSON body
{
"input": {
"birth": {
"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"
}
}
}
}
POST
/v1/client-sessions/{session_id}/messages
Client Sessions Session Id Messages
Append a user/client/tool message to one guided client session without invoking a model.
Use this when
Use to append user, assistant, system, or tool messages supplied by the client.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
session_id
string
Required
path parameter.
Example request
cURL
curl -s "https://api.astro.ai/v1/client-sessions/{session_id}/messages" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"role": "assistant",
"content": "Saved the Teacher lesson plan and linked it to this session.",
"source_type": "library_item",
"source_id": "item_..."
}'JSON body
{
"role": "assistant",
"content": "Saved the Teacher lesson plan and linked it to this session.",
"source_type": "library_item",
"source_id": "item_..."
}
GET
/v1/journal-events
Journal Events
Create or list dated life events tied to saved people for later timeline, rectification, and report workflows.
Use this when
Use to capture user-confirmed life events that can later inform timelines, rectification, report context, and Teacher lessons.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
mixed
Optional
query parameter.
event_tag
mixed
Optional
query parameter.
limit
integer
Optional
query parameter.
after
mixed
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/journal-events" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/journal-events
Journal Events
Create or list dated life events tied to saved people for later timeline, rectification, and report workflows.
Use this when
Use to capture user-confirmed life events that can later inform timelines, rectification, report context, and Teacher lessons.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Example request
cURL
curl -s "https://api.astro.ai/v1/journal-events" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"person_id": "person_example",
"title": "Moved to a new city",
"happened_at": "2026-05-31T09:00:00+05:30",
"event_tags": [
"relocation",
"career"
],
"notes": "Useful context for timeline and rectification review."
}'JSON body
{
"person_id": "person_example",
"title": "Moved to a new city",
"happened_at": "2026-05-31T09:00:00+05:30",
"event_tags": [
"relocation",
"career"
],
"notes": "Useful context for timeline and rectification review."
}
DELETE
/v1/journal-events/{event_id}
Journal Events Event Id
Fetch or delete one saved journal event.
Use this when
Use to inspect or remove one dated life event without deleting the person profile.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
event_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/journal-events/{event_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/journal-events/{event_id}
Journal Events Event Id
Fetch or delete one saved journal event.
Use this when
Use to inspect or remove one dated life event without deleting the person profile.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
event_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/journal-events/{event_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
PATCH
/v1/journal-events/{event_id}
Journal Events Event Id
Fetch or delete one saved journal event.
Use this when
Use to inspect or remove one dated life event without deleting the person profile.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
event_id
string
Required
path parameter.
Example request
cURL
curl -s "https://api.astro.ai/v1/journal-events/{event_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"event_id": "event_example"
}'JSON body
{
"event_id": "event_example"
}
GET
/v1/library-items
Library Items
Create or list saved report snapshots, timeline snapshots, good-time windows, birth-time candidates, Teacher answers, Teacher lesson plans, and notes.
Use this when
Use to save report snapshots, chosen good-time windows, life timeline views, Teacher answers, Teacher lesson plans, or user-facing notes for later product views.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
kind
mixed
Optional
query parameter.
person_id
mixed
Optional
query parameter.
limit
integer
Optional
query parameter.
after
mixed
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/library-items" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/library-items
Library Items
Create or list saved report snapshots, timeline snapshots, good-time windows, birth-time candidates, Teacher answers, Teacher lesson plans, and notes.
Use this when
Use to save report snapshots, chosen good-time windows, life timeline views, Teacher answers, Teacher lesson plans, or user-facing notes for later product views.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Example request
cURL
curl -s "https://api.astro.ai/v1/library-items" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "note",
"title": "Saved onboarding note",
"payload": {
"summary": "Keep this with the client profile."
},
"tags": [
"onboarding"
]
}'JSON body
{
"kind": "note",
"title": "Saved onboarding note",
"payload": {
"summary": "Keep this with the client profile."
},
"tags": [
"onboarding"
]
}
DELETE
/v1/library-items/{item_id}
Library Items Item Id
Fetch or delete one saved product-library item.
Use this when
Use to retrieve or remove one saved snapshot without rerunning its source calculation.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
item_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/library-items/{item_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/library-items/{item_id}
Library Items Item Id
Fetch or delete one saved product-library item.
Use this when
Use to retrieve or remove one saved snapshot without rerunning its source calculation.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
item_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/library-items/{item_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/match-runs
Match Runs
Create or list saved facts-only Match Finder runs across two saved people.
Use this when
Use to persist compatibility review context between two saved people without generating advice or a pair verdict.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
mixed
Optional
query parameter.
limit
integer
Optional
query parameter.
after
mixed
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/match-runs" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/match-runs
Match Runs
Create or list saved facts-only Match Finder runs across two saved people.
Use this when
Use to persist compatibility review context between two saved people without generating advice or a pair verdict.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Example request
cURL
curl -s "https://api.astro.ai/v1/match-runs" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"male_person_id": "person_male_example",
"female_person_id": "person_female_example",
"title": "Compatibility review",
"user_question": "Which compatibility facts need attention?",
"include_facts": true
}'JSON body
{
"male_person_id": "person_male_example",
"female_person_id": "person_female_example",
"title": "Compatibility review",
"user_question": "Which compatibility facts need attention?",
"include_facts": true
}
DELETE
/v1/match-runs/{match_id}
Match Runs Match Id
Fetch or delete one saved facts-only compatibility run.
Use this when
Use to inspect or remove one saved Match Finder run while keeping both people intact.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
match_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/match-runs/{match_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/match-runs/{match_id}
Match Runs Match Id
Fetch or delete one saved facts-only compatibility run.
Use this when
Use to inspect or remove one saved Match Finder run while keeping both people intact.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
match_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/match-runs/{match_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/match-runs/{match_id}/report
Get Match Run Report
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific get match run report contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
match_id
string
Required
path parameter.
include_source_payloads
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/match-runs/{match_id}/report" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/people
People
Create or list saved birth profiles scoped to the authenticated key or local client identity.
Use this when
Use to save birth profiles once and reuse them across chart, reading, compatibility, and history workflows.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
limit
integer
Optional
query parameter.
after
mixed
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/people" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/people
People
Create or list saved birth profiles scoped to the authenticated key or local client identity.
Use this when
Use to save birth profiles once and reuse them across chart, reading, compatibility, and history workflows.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Example request
cURL
curl -s "https://api.astro.ai/v1/people" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example Native",
"birth": {
"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"
}
},
"tags": [
"example",
"client"
],
"notes": "Created from the API reference example."
}'JSON body
{
"name": "Example Native",
"birth": {
"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"
}
},
"tags": [
"example",
"client"
],
"notes": "Created from the API reference example."
}
DELETE
/v1/people/{person_id}
People Person Id
Fetch, update, or delete one saved birth profile.
Use this when
Use when a product needs to fetch, update, or remove one saved profile without exposing another client's records.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/people/{person_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/people/{person_id}
People Person Id
Fetch, update, or delete one saved birth profile.
Use this when
Use when a product needs to fetch, update, or remove one saved profile without exposing another client's records.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/people/{person_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
PATCH
/v1/people/{person_id}
People Person Id
Fetch, update, or delete one saved birth profile.
Use this when
Use when a product needs to fetch, update, or remove one saved profile without exposing another client's records.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
string
Required
path parameter.
Example request
cURL
curl -s "https://api.astro.ai/v1/people/{person_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Updated Example Native",
"tags": [
"example",
"updated"
]
}'JSON body
{
"name": "Updated Example Native",
"tags": [
"example",
"updated"
]
}
GET
/v1/people/{person_id}/client-brief
Get Person Client Brief
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific get person client brief contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
string
Required
path parameter.
limit
integer
Optional
query parameter.
include_payloads
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/people/{person_id}/client-brief" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/people/{person_id}/consultation-packet
Get Person Consultation Packet
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific get person consultation packet contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
string
Required
path parameter.
limit
integer
Optional
query parameter.
include_payloads
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/people/{person_id}/consultation-packet" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/people/{person_id}/context
People Person Id Context
Fetch a compact client-workspace summary for one saved person.
Use this when
Use for the first screen of a client workspace: recent runs, library items, journal events, match runs, counts, and next actions.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
string
Required
path parameter.
limit
integer
Optional
query parameter.
include_payloads
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/people/{person_id}/context" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/people/{person_id}/journal-questionnaire
Get Person Journal Questionnaire
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific get person journal questionnaire contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
string
Required
path parameter.
time_preset
string
Optional
query parameter.
limit
integer
Optional
query parameter.
event_tag
mixed
Optional
query parameter.
include_payloads
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/people/{person_id}/journal-questionnaire" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/people/{person_id}/journal-review
People Person Id Journal Review
Group one saved person's journal events with timeline evidence and safe next steps.
Use this when
Use when a client needs grouped journal events, timing evidence, and safe next actions for timeline, Teacher, report, or birth-time review workflows.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
string
Required
path parameter.
time_preset
string
Optional
query parameter.
limit
integer
Optional
query parameter.
event_tag
mixed
Optional
query parameter.
include_payloads
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/people/{person_id}/journal-review" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/people/{person_id}/timeline
People Person Id Timeline
Review one saved person's evidence timeline with journal overlays.
Use this when
Use when a client needs a Life Timeline review for a saved person plus user-confirmed journal overlays.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
string
Required
path parameter.
time_preset
string
Optional
query parameter.
limit
integer
Optional
query parameter.
include_payloads
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/people/{person_id}/timeline" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/questionnaire-responses
List Questionnaire Responses
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific list questionnaire responses contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
mixed
Optional
query parameter.
status
mixed
Optional
query parameter.
limit
integer
Optional
query parameter.
after
mixed
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/questionnaire-responses" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/questionnaire-responses
Create Questionnaire Response
Create a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific create questionnaire response contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Example request
cURL
curl -s "https://api.astro.ai/v1/questionnaire-responses" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"person_id": "person_example",
"title": "Answered birth-time review questionnaire",
"source_library_item_id": "item_questionnaire_example",
"time_preset": "age18to21",
"event_tag": "relocation",
"answers": [
{
"question_id": "target_signal",
"answer": "target_ascendant",
"confidence": "high"
},
{
"question_id": "target_ascendant_value",
"answer": "Virgo",
"confidence": "medium"
},
{
"question_id": "birth_time_uncertainty",
"answer": "within 30 minutes",
"confidence": "medium"
}
]
}'JSON body
{
"person_id": "person_example",
"title": "Answered birth-time review questionnaire",
"source_library_item_id": "item_questionnaire_example",
"time_preset": "age18to21",
"event_tag": "relocation",
"answers": [
{
"question_id": "target_signal",
"answer": "target_ascendant",
"confidence": "high"
},
{
"question_id": "target_ascendant_value",
"answer": "Virgo",
"confidence": "medium"
},
{
"question_id": "birth_time_uncertainty",
"answer": "within 30 minutes",
"confidence": "medium"
}
]
}
DELETE
/v1/questionnaire-responses/{response_id}
Delete Questionnaire Response
Create a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific delete questionnaire response contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
response_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/questionnaire-responses/{response_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/questionnaire-responses/{response_id}
Get Questionnaire Response
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific get questionnaire response contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
response_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/questionnaire-responses/{response_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/questionnaire-responses/{response_id}/birth-time-review
Get Questionnaire Birth Time Review
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific get questionnaire birth time review contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
response_id
string
Required
path parameter.
precision_minutes
integer
Optional
query parameter.
top_k
integer
Optional
query parameter.
include_evidence_scans
boolean
Optional
query parameter.
include_source_payloads
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/questionnaire-responses/{response_id}/birth-time-review" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/reminders
List Reminders
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific list reminders contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
person_id
mixed
Optional
query parameter.
status
mixed
Optional
query parameter.
kind
mixed
Optional
query parameter.
limit
integer
Optional
query parameter.
after
mixed
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/reminders" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
POST
/v1/reminders
Create Reminder
Create a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific create reminder contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Example request
cURL
curl -s "https://api.astro.ai/v1/reminders" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Review journal follow-up",
"due_at": "2026-06-07T09:00:00+05:30",
"person_id": "person_example",
"kind": "journal_review",
"source_type": "journal_event",
"source_id": "event_example",
"tags": [
"follow-up",
"journal"
]
}'JSON body
{
"title": "Review journal follow-up",
"due_at": "2026-06-07T09:00:00+05:30",
"person_id": "person_example",
"kind": "journal_review",
"source_type": "journal_event",
"source_id": "event_example",
"tags": [
"follow-up",
"journal"
]
}
DELETE
/v1/reminders/{reminder_id}
Delete Reminder
Create a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific delete reminder contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
reminder_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/reminders/{reminder_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
GET
/v1/reminders/{reminder_id}
Get Reminder
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific get reminder contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
reminder_id
string
Required
path parameter.
Example request
curl -s "https://api.astro.ai/v1/reminders/{reminder_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"
PATCH
/v1/reminders/{reminder_id}
Update Reminder
Create a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific update reminder contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
reminder_id
string
Required
path parameter.
Example request
cURL
curl -s "https://api.astro.ai/v1/reminders/{reminder_id}" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reminder_id": "reminder_example"
}'JSON body
{
"reminder_id": "reminder_example"
}
GET
/v1/workbench/dashboard
Get Workbench Dashboard
Retrieve a product state resource through the Astro AI /v1 envelope.
Use this when
Use this product state route when the product needs the specific get workbench dashboard contract rather than a broader bundle.
Returns
Saved person records, calculation-run records, product-library snapshots, journal events, client sessions, and pagination cursors.
Watch for
The development store is file-backed and scoped by API key or local client identity; use a durable database before hosted multi-user production.
Parameters
limit
integer
Optional
query parameter.
include_payloads
boolean
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/workbench/dashboard" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"External Providers
Explicitly configured external-provider gates.
POST
/v1/external/bazi/horoscope-predictions
External Bazi Horoscope Predictions
Validate or proxy an explicitly configured external Bazi horoscope provider.
Use this when
Use this external providers route when the product needs the specific external bazi horoscope predictions contract rather than a broader bundle.
Returns
Provider gate metadata or proxied provider output when explicitly configured.
Watch for
Provider-backed routes fail closed unless the matching environment variables are configured.
Example request
cURL
curl -s "https://api.astro.ai/v1/external/bazi/horoscope-predictions" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"birth": {
"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"
}
},
"sort_by_weight": false
}'JSON body
{
"birth": {
"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"
}
},
"sort_by_weight": false
}
POST
/v1/external/bazi/match-report
External Bazi Match Report
Validate or proxy an explicitly configured external Bazi match-report provider.
Use this when
Use this external providers route when the product needs the specific external bazi match report contract rather than a broader bundle.
Returns
Provider gate metadata or proxied provider output when explicitly configured.
Watch for
Provider-backed routes fail closed unless the matching environment variables are configured.
Example request
cURL
curl -s "https://api.astro.ai/v1/external/bazi/match-report" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"male": {
"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"
}
},
"female": {
"year": 1998,
"month": 6,
"date": 18,
"hours": 9,
"minutes": 10,
"seconds": 0,
"latitude": 12.9716,
"longitude": 77.5946,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
}
}'JSON body
{
"male": {
"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"
}
},
"female": {
"year": 1998,
"month": 6,
"date": 18,
"hours": 9,
"minutes": 10,
"seconds": 0,
"latitude": 12.9716,
"longitude": 77.5946,
"timezone": 5.5,
"config": {
"ayanamsa": "lahiri",
"observation_point": "topocentric"
}
}
}
POST
/v1/external/vedastro/chapter-predictions
External Vedastro Chapter Predictions
Capture explicitly configured VedAstro chapter-prediction fixtures for research.
Use this when
Use this external providers route when the product needs the specific external vedastro chapter predictions contract rather than a broader bundle.
Returns
Provider gate metadata or proxied provider output when explicitly configured.
Watch for
Provider-backed routes fail closed unless the matching environment variables are configured.
Example request
cURL
curl -s "https://api.astro.ai/v1/external/vedastro/chapter-predictions" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vedastro_name": "Chapter10Predictions",
"upstream_payload": {
"time": {
"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"
}
}
},
"include_provenance": true
}'JSON body
{
"vedastro_name": "Chapter10Predictions",
"upstream_payload": {
"time": {
"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"
}
}
},
"include_provenance": true
}Safety
Catalog of intentionally rejected sensitive or internal rows.
GET
/v1/safety/rejections
Safety Rejections
List rejected internal and sensitive VedAstro rows with audit metadata.
Use this when
Use this safety route when the product needs the specific safety rejections contract rather than a broader bundle.
Returns
A non-executing catalog of rejected rows and the reason each row stays out of the API.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Parameters
clone_decision
mixed
Optional
query parameter.
limit
integer
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/safety/rejections" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"Coverage
VedAstro implementation coverage and clone-decision ledger.
GET
/v1/coverage/vedastro
Coverage Vedastro
Return the generated VedAstro coverage ledger with filters.
Use this when
Use to understand what is implemented, gated, rejected, or still partial against VedAstro.
Returns
Coverage summary rows, parity state, and clone-decision metadata.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Parameters
implemented_only
boolean
Optional
query parameter.
clone_decision
mixed
Optional
query parameter.
parity_state
mixed
Optional
query parameter.
limit
integer
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/coverage/vedastro" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"Hermes Astro
Astro AI API operations.
POST
/v1/hermes/astro/chat
Create Hermes Astro Chat
Create a hermes astro resource through the Astro AI /v1 envelope.
Use this when
Use this hermes astro route when the product needs the specific create hermes astro chat contract rather than a broader bundle.
Returns
A typed AstroChatResponse payload inside the shared Astro AI success envelope.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Example request
cURL
curl -s "https://api.astro.ai/v1/hermes/astro/chat" \
-H "Authorization: Bearer ASTRO_AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Explain the chart using source-backed components.",
"person_id": "person_example",
"client_session_id": "session_example",
"mode": "reading",
"include_visual_context": true
}'JSON body
{
"message": "Explain the chart using source-backed components.",
"person_id": "person_example",
"client_session_id": "session_example",
"mode": "reading",
"include_visual_context": true
}
GET
/v1/hermes/astro/setup
Get Hermes Astro Setup
Retrieve a hermes astro resource through the Astro AI /v1 envelope.
Use this when
Use this hermes astro route when the product needs the specific get hermes astro setup contract rather than a broader bundle.
Returns
A typed HermesAstroProfileSetupResponse payload inside the shared Astro AI success envelope.
Watch for
Use meta.request_id for support, inspect meta.warnings before presenting results, and keep API keys on your backend.
Parameters
astro_base_url
mixed
Optional
query parameter.
Example request
curl -s "https://api.astro.ai/v1/hermes/astro/setup" \
-H "Authorization: Bearer ASTRO_AI_API_KEY"