# AstroLogics API: notes for coding agents

Vedic astrology API over HTTPS. Base URL `https://api.astrologics.in`. The contract is OpenAPI 3.1: https://developers.astrologics.in/reference/openapi.yaml. Every docs page is also markdown: https://developers.astrologics.in/llms.txt lists them.

## Keys

Send `Authorization: Bearer <key>` on every request.

- `al_test_`: the real engine, never charged; `meta.mode` is `test`. Start here.
- `al_live_`: spends the plan's credits. Only successful (2xx) calls are charged.
- `al_pub_`: for widgets in the browser only: read-only operations without birth data, from the origins listed on the key.
- Test and live keys are secret. Use them only from a server, never in a web page or a mobile app; see https://developers.astrologics.in/docs/mobile-apps.md.

## Request

Birth details: https://developers.astrologics.in/docs/birth-input.md. A place is coordinates, a `place_id` from `GET /v1/places/search`, or a free-text query. Do not invent a birth time: set `time_accuracy`. Use made-up birth details in tests and examples.

`POST /v1/kundli`:

```json
{
  "birth": {
    "date": "1990-08-13",
    "time": "06:30",
    "place": {
      "latitude": 28.6139,
      "longitude": 77.209
    }
  }
}
```

## Errors

Read `error.code`, not the message: https://developers.astrologics.in/docs/errors.md. Errors are never charged.

- `error.issues` lists every problem in the request at once; fix them together.
- `place_ambiguous` comes with `error.candidates`: send one of their `place_id` values.
- A `404` for an unknown path can carry `error.suggestions`: the operations you may have meant.
- A `429` carries `Retry-After`: `rate_limited` means wait and retry; `quota_exhausted` means retrying soon will not help.
- Quote `request_id` when reporting a problem.

## SDKs

Official clients for TypeScript and JavaScript, Python and PHP, downloaded from us for now: https://developers.astrologics.in/products/sdks.md. Quickstarts: https://developers.astrologics.in/docs/quickstart-typescript.md, https://developers.astrologics.in/docs/quickstart-python.md, https://developers.astrologics.in/docs/quickstart-php.md.

## MCP

Every public operation is a tool at `https://api.astrologics.in/mcp` (your API key), and the docs are searchable at `https://developers.astrologics.in/mcp` (no key). Setup: https://developers.astrologics.in/docs/mcp.md.

## Credits and storing results

Each operation's credits are in the reference; each response reports the balance in `X-Credits-Remaining`. Rate limits: https://developers.astrologics.in/docs/rate-limits.md. What to cache: https://developers.astrologics.in/docs/caching-and-data-retention.md. Calculation changes are versioned by `meta.engine_version`: https://developers.astrologics.in/docs/versioning-and-calculation-changes.md.

## Operations

- [Places & time](https://developers.astrologics.in/reference/places-and-time.md): 4 operations
- [Kundli](https://developers.astrologics.in/reference/kundli.md): 24 operations
- [Dasha](https://developers.astrologics.in/reference/dasha.md): 4 operations
- [Doshas](https://developers.astrologics.in/reference/doshas.md): 4 operations
- [Matchmaking](https://developers.astrologics.in/reference/matchmaking.md): 4 operations
- [Panchang & muhurat](https://developers.astrologics.in/reference/panchang-and-muhurat.md): 10 operations
- [Calendar](https://developers.astrologics.in/reference/calendar.md): 3 operations
- [Horoscopes](https://developers.astrologics.in/reference/horoscopes.md): 4 operations
- [Transits](https://developers.astrologics.in/reference/transits.md): 6 operations
- [Timing](https://developers.astrologics.in/reference/timing.md): 5 operations
- [Numerology](https://developers.astrologics.in/reference/numerology.md): 8 operations
- [Chart images](https://developers.astrologics.in/reference/chart-images.md): 2 operations
- [Reports](https://developers.astrologics.in/reference/reports.md): 3 operations
- [KP](https://developers.astrologics.in/reference/kp.md): 6 operations
- [Lal Kitab](https://developers.astrologics.in/reference/lal-kitab.md): 4 operations
- [Annual](https://developers.astrologics.in/reference/annual.md): 1 operation
- [Biorhythm](https://developers.astrologics.in/reference/biorhythm.md): 6 operations
- [Forecast](https://developers.astrologics.in/reference/forecast.md): 5 operations
- [Western](https://developers.astrologics.in/reference/western.md): 9 operations
- [Chinese](https://developers.astrologics.in/reference/chinese.md): 7 operations
- [Feng Shui](https://developers.astrologics.in/reference/feng-shui.md): 5 operations
- [Vastu](https://developers.astrologics.in/reference/vastu.md): 7 operations
- [Platform](https://developers.astrologics.in/reference/platform.md): 2 operations