Why we renamed 200 operation IDs

API operation IDs are the names your SDK methods, your docs, and your AI agents see. For most of this project, ours read like postVedicBirthChart — technically accurate, but the HTTP method is not what the endpoint does.

The old names

\\\`

postWesternHouses → POST /v1/western/houses

postVedicYogasDetect → POST /v1/vedic/yogas/detect

postDivinationTarotYesNo → POST /v1/divination/tarot/yes-no

postVedicDashaSubMahadashaAntardashaPratyantardashaSookshma

\\\`

The last one is path parameters mashed into a name. Unreadable by humans, and not much better for machines.

The new names

Operation IDs now use semantic verbs — the verb describes what the engine does, not how HTTP transports it:

|---|---|---|

What this buys you

SDK ergonomics. Our generated TypeScript client produces client.generateBirthChart() instead of client.postVedicBirthChart(). Autocomplete reads like a sentence.

Agent comprehension. AI agents pick endpoints from their names. calculateHouses is self-evident; postWesternHouses requires cross-referencing the docs.

Consistency across domains. list for catalogs (listCards, listHexagrams, listNakshatras), search for lookups (searchCities, searchCrystals), get for singletons (getHexagram, getAngelNumber) — the same conventions the ecosystem's mature APIs use, so engineers switching between platforms see familiar shapes.

The same went for URLs

Alongside the renames we normalized 57 URLs: /v1/divination/tarot/spreads/* became /v1/tarot/spreads/* (flat domains, like the ecosystem standard), humandesign became human-design, moon phases moved to Western, and KP folded into the Vedic tag. Every old path still works — they return a 308 redirect to the canonical location, flagged deprecated in the OpenAPI spec.

Names are the cheapest API surface to get right, and the most expensive to change later. We changed ours now, before version 1.0.