# Natalka preview API

The public API at https://natalka.ai provides anonymous city search and natal chart previews.
It requires no account, API key, OAuth token or agent registration. This does not grant access
to saved charts, Telegram conversations, compatibility reports or payments.

- [OpenAPI 3.1 description](https://natalka.ai/openapi.json)
- [API catalog](https://natalka.ai/.well-known/api-catalog)
- [Access instructions](https://natalka.ai/auth.md)
- [Agent skill](https://natalka.ai/.well-known/agent-skills/natal-chart-preview/SKILL.md)
- [Liveness](https://natalka.ai/health): process liveness only, not database readiness.

## Requests

Use HTTPS POST with `Content-Type: application/json`. Bodies are limited to 2048 bytes.
Use `locale: "ru"` or `"en"`; omitted locale defaults to Russian. Unknown properties are rejected.
Browser calls must originate on this site; the API does not enable cross-origin CORS.
Server clients can call directly without an Origin header. No cookies or credentials are required.

### Search birthplaces

`POST /api/preview/cities`

```json
{"query":"Moscow","locale":"en"}
```

The trimmed query must contain 2–80 characters. A successful response is
`{"cities":[{"id":524901,"label":"…"}]}` with at most eight candidates. Let the user choose
the correct city. Use the returned id; do not guess coordinates, timezones or identifiers.
City data comes from [GeoNames](https://www.geonames.org/), licensed under
[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

### Calculate a preview

`POST /api/preview/chart`

```json
{"date":"1995-06-15","time":"12:00","cityId":524901,"locale":"en"}
```

This is an illustrative input, not the visitor's inferred birth data. Supply a real calendar date
between 1800-01-01 and today. Prefer YYYY-MM-DD. Birth time is local to the birthplace, in HH:MM;
use JSON `null` when it is unknown. The server also accepts day-first dates separated by `.`, `/`
or `-`; it does not accept month-first dates. City ids must be positive integers at most 20000000.

Success returns `{"kind":"chart","html":"…"}`. The HTML contains placements, a chart and
applicable caveats. This is a rendered preview, not a JSON feed of planetary coordinates.
Without a known time there are no houses or angles; preserve both possible Moon signs when shown.
Keep any house-system substitution and historical-clock caveats with the result.

A daylight-saving overlap returns `{"kind":"fold","offsets":[…]}` instead of a chart.
Offsets are minutes east of UTC in the order of the two choices. Ask the user which applies,
then retry with `"fold":0` or `"fold":1`. Never choose silently. The user can instead mark
time unknown. A daylight-saving gap requires corrected input; do not shift the time automatically.

## Errors and limits

Errors have an `error` string, with no submitted birth data or internal exception details.

| Status | Meaning |
|---|---|
| 400 | Invalid input: `invalid`, `date`, `time` or `city`. |
| 403 | Browser origin rejected: `invalid`. |
| 413 | Body too large: `tooLarge`. |
| 415 | JSON content type required: `invalid`. |
| 422 | Nonexistent local time (`gap`), skipped date (`skipped`), calculation unavailable (`unavailable`). |
| 429 | Shared capacity exhausted: `busy`. Honor `Retry-After: 60`. |
| 503 | Temporarily unavailable: `unavailable`. |

Budgets are shared across all visitors in the running process: 120 city searches and 30 chart
attempts per minute, with at most four concurrent city reads. Do not batch or crawl birth inputs.
Responses use `Cache-Control: no-store` and `X-Robots-Tag: noindex`.

## Privacy and interpretation

Submit only birth data the user supplied for this calculation. Keep it in POST bodies, never
URLs, telemetry or persistent client storage. The application neither saves these inputs nor
sends them to AI services. Infrastructure logging is a separate concern.

Astrology is for reflection, not scientific prediction, diagnosis or medical, legal or financial
advice. Charts, readings and compatibility are free in [Natalka on Telegram](https://t.me/natalkachart_bot);
answered chat questions use credits. To save a chart or receive a reading, the user opens Telegram
and enters the details again. The website does not transfer birth data to the bot.

## Browser tools and page content

Compatible WebMCP browsers discover `search_birth_cities` and `calculate_chart_preview` on page
load. They use the same endpoints and limits. Unsupported browsers retain the normal calculator.

Request `/` or `/en` with `Accept: text/markdown` for localized Markdown. HTML remains the default;
`Vary: Accept` distinguishes the representations. Public catalogs and documentation permit CORS;
this does not extend to preview requests.