# The satchitananda API

One public, read-only endpoint, `GET /api/v1/search/`, that searches the guided meditations on https://sat-chit-ananda.com/: by their words, and by meaning. The site's own search page uses it. The OpenAPI description is https://sat-chit-ananda.com/openapi.json.

No key, no sign-in, no cookies. Nothing about who searched is stored or logged. The day's total of searches is counted. The words of a search that found nothing are counted by day, as ideas for what to make next. To match by meaning, the words are sent once to Google's embedding model (gemini-embedding-001), with nothing about who sent them.

**Limits.** 100 searches per address per day (UTC). Over that, a 429 with Retry-After until midnight UTC.

## Search

```
GET https://sat-chit-ananda.com/api/v1/search/?q=help+me+fall+asleep&limit=3
```

| Parameter | What it does | Values |
|:---|:---|:---|
| `q` (or `query`, `search`) | What to look for, in your own words: what it is for, how you feel, or a line you remember. | 2 to 200 characters, required |
| `kind` (or `type`) | What to search. Meditations today; more kinds will come. | meditation, default meditation |
| `for` (or `playlist`) | Only those in this playlist (its slug), as the Meditations page's For filter. |  |
| `sound` | Only those with this natural sound (rain, ocean, forest), as the Meditations page's Sound filter. |  |
| `length` | Only those of this length, in whole minutes as the cards show. | under-20, 20-30, over-30 |
| `setting` | Only those for this setting: in bed, or sitting or lying down. | bed, sit-or-lie |
| `voice` | Only those read in this kind of voice (the first voice you hear). | male, female |
| `purpose` | Only those for this purpose, as their label says: for sleep, or to stay alert. | sleep, alert |
| `limit` (or `per_page`, `page_size`) | How many results to answer with. | 1 to 50, default 10 |
| `offset` | How many to skip: the previous answer's next_offset. | 0 to 1000, default 0 |
| `prefix` | While someone types: the last word also matches as the start of a word. | default false |

Every result has:

- its page (`url`)
- direct audio links (`audio.m4a`, `audio.mp3`, `audio.flac`)
- its length (`duration_seconds`, `length`), its voices and its playlists
- `match`: the passage that matched, the character ranges of its matched words, the part of the track it's from (`chapter.title`, and `chapter.at` in seconds), and whether words, meaning or both found it

`facets` says how many results each filter value would leave. `next_steps` says where to go next: the top result's audio and page, and the next page of results. When matching by meaning is unavailable, `"degraded": "words only"` says so.

## Errors

Every error is JSON with:

- `error`: what went wrong
- `suggestion`: what to do instead
- `next_steps`: where to go instead
- `did_you_mean`: when something sent was close to a known name or value

| Status | When |
|:---|:---|
| 400 | A parameter is missing, out of range, or not one the API knows |
| 405 | Anything but GET or HEAD |
| 429 | Over the day's 100 searches from this address; `Retry-After` is the seconds until midnight UTC |
| 503 | Search is busy; `Retry-After` says how long to wait |

Unknown paths under `/api/` answer JSON 404 with where to go instead. There's no key, no sign-in and no MCP server.
