API Reference

Ontyx exposes two API surfaces: the control plane (account management, keys, billing, usage) and the product API (geospatial data queries). This page documents the control plane, which is the only surface available today.

Control Plane

Control plane endpoints are authenticated with a session cookie (ontyx_session) issued at sign-in. They are used by the dashboard and are not intended for programmatic access from application code. All endpoints return JSON. Errors follow the shape { "error": { "code": "string", "message": "string" } }.

User

Method	Path	Response	Notes
`GET`	`/me`	`MeResponse`	Returns current user identity and entitlements

MeResponse shape:

{
  "userId": "usr_...",
  "email": "you@example.com",
  "entitlements": {
    "hasSubscription": true
  }
}

API Keys

Method	Path	Response	Notes
`GET`	`/api-keys`	`ListApiKeysResponse`	Returns metadata for all keys in the caller’s account; plaintext is never returned
`POST`	`/api-keys`	`CreateApiKeyResponse`	Creates a key; returns plaintext exactly once in `plaintext` field
`DELETE`	`/api-keys/:id`	`204 No Content`	Revokes the key; returns `404` if the key does not exist or belongs to another user

CreateApiKeyResponse shape:

{
  "plaintext": "ontyx_live_ak_<keyId>_<secret>",
  "key": {
    "keyId": "EGKCZE3PBGZ0FZHTH1DX4HCVEQ",
    "env": "live",
    "name": "claude-desktop",
    "scopes": ["read:data"],
    "createdAt": "2026-05-15T00:00:00.000Z"
  }
}

plaintext is the full bearer token to send in the Authorization header. It is returned once — re-fetching the key over GET /api-keys never includes it.

Subscription

Method	Path	Response	Notes
`GET`	`/subscription`	`SubscriptionResponse`	Returns current subscription status and period
`POST`	`/subscription`	`SubscriptionResponse`	Starts checkout; returns `409` if subscription is already active
`DELETE`	`/subscription`	`SubscriptionResponse`	Cancels the subscription; returns `404` if not active
`POST`	`/billing/portal`	`{ url: string }`	Opens a billing portal session; redirects via returned URL

Usage

Method	Path	Response	Notes
`GET`	`/usage`	`UsageResponse`	Returns current period, credits consumed, allotment, and quota state

UsageResponse shape:

{
  "period": "2026-07",
  "used": 450,
  "quota": 1000,
  "percent": 45,
  "state": "ok",
  "mode": "standard"
}

quota is the monthly credit allotment for the caller’s plan and mode is "free" or "standard". state is one of "ok" (under 80%), "warning" (80–100%), or "over" (above the allotment).

Overage behavior depends on the plan: on Standard, overage is soft — requests are not rejected when state is "over". On the free tier, the monthly credits are a hard cap; once they’re used up, data calls return a structured QUOTA_EXCEEDED result until credits reset at the start of the next month.

Credits

Usage is metered in credits. Every currently shipped call type costs 1 credit, metered only when the call succeeds:

Call type	Tools	Credits
Demographic lookup (ACS)	`get_population`, `get_average_income`	1
Location lookup	`geocode`, `reverse_geocode`, `search_nearby`	1
Static map render	`static_map`	1

Failed calls — validation errors, unknown zips, upstream service failures — are never metered.

Premium datasets (HUD rent benchmarks, CMBS, composite indices) will carry higher per-call credit costs when they ship; this table is the authoritative place to check. Monthly allotments per plan are listed on the pricing page.

Product API

[TODO: documented post-MCP-launch]

The product API is the data-serving surface that your agents and applications call directly. It uses bearer token authentication (see Authentication) and will expose geospatial query endpoints corresponding to the MCP tools described in Available Tools.

This section will be expanded once the MCP server and direct HTTP data API enter public availability.

Authentication