Psychomantic API

Last updated: September 2026

Base and authentication

Base: https://api.psychomantic.com/v1

Authentication: X-API-Key: ish_... header (or Authorization: Bearer). The key is never passed in the URL: the server refuses that path, because a full URL ends up in logs.

To get a key, write to [email protected].

Response format

Success: {"success": true, "data": {...}}

Error: {"success": false, "error": {"code": "...", "message": "..."}}

Common codes: VALIDATION_ERROR, CALCULATION_ERROR, NOT_FOUND, DAILY_QUOTA_EXCEEDED, MONTHLY_QUOTA_EXCEEDED, UNAUTHORIZED.

Quotas: every authenticated response carries the X-Quota-Daily-* and X-Quota-Monthly-* headers.

Published endpoints

Five calculation endpoints, one call = one complete result:

POST /v1/astro/natal: natal chart (planets, houses, aspects, angles)
POST /v1/astro/transits: transits over a natal chart
POST /v1/astrocartography: worldwide planetary lines (GeoJSON)
POST /v1/asteroids: Chiron, Ceres, Pallas, Juno, Vesta
GET /v1/astro/moon-phase: moon phase

Without a key: GET /health (service status).

The rest of the surface (accounts, billing, application verticals) is not published: an exhaustive route map is attacker information, and it expires at the first change. The OpenAPI specification is a trade secret (rule R-022) and is only served in a local development environment.

MCP server (AI agents)

Remote server: POST https://api.psychomantic.com/mcp (streamable HTTP).

Header authentication only (X-API-Key or Authorization: Bearer), never through the URL. A GET on the same URL serves the public descriptor; the authoritative tool list comes from tools/list.

Example

curl -X POST https://api.psychomantic.com/v1/astro/natal \
  -H "X-API-Key: ish_..." \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-06-15","time":"14:30","latitude":48.8566,"longitude":2.3522,"timezone":"Europe/Paris"}'

Machine-readable summary: psychomantic.com/llms.txt.