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, units consumed, quota, and quota state

UsageResponse shape:

{
  "period": "2026-05",
  "used": 450,
  "quota": 10000,
  "percent": 5,
  "state": "ok"
}

state is one of "ok" (under 80%), "warning" (80–100%), or "over" (above quota). Soft overages are allowed — requests are not rejected when state is "over".

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