Account API reference
The dashboard runs on two small APIs of its own. They’re listed here so you know what exists; they’re meant for the dashboard, not for scripts. To send data from a script, use the Push API. To ask questions, connect an assistant (Connect your assistant).
Both take the signed-in person’s dashboard session, sent as Authorization: Bearer <session token>. Personal API keys and push keys aren’t accepted. Every request acts on the caller’s own organization, worked out from their membership, never from the request. Errors are { "error": { "code": "…", "message": "…" } }, with the message in plain words.
The account API
At https://app-api.ontyx.io.
You
| Method | Path | What it does |
|---|---|---|
GET | /health | { "ok": true, … } when the service is up. Needs no session. |
GET | /me | The signed-in person (user: id, email, displayName), entitlements, and their organization (org: name, role, canManage, connectorUrl, connectDocsUrl), or null when they aren’t in one. |
GET | /legal/acceptance | Whether the person’s acceptance of the Terms of Service is current, with currentVersion, termsUrl and privacyUrl. |
POST | /legal/accept | Records acceptance of the current version. An optional body { "version": "…" } must match the current version. |
The organization
| Method | Path | Who | What it does |
|---|---|---|---|
GET | /org | any member | The organization: name, the caller’s role, canManage, connectorUrl, connectDocsUrl. |
PATCH | /org | owner, admin | Renames it: { "name": "…" }, 1 to 128 characters. |
GET | /org/members | any member | Everyone in the organization, with their role and when they joined. |
PATCH | /org/members/{userId} | owner, admin | Changes a role: { "role": "admin" } or "reader". Never the owner’s. |
DELETE | /org/members/{userId} | owner, admin | Removes a member (204). Never the owner. |
GET | /org/invites | owner, admin | Invitations still waiting. |
POST | /org/invites | owner, admin | Invites { "email": "…", "role": "admin" } (or "reader"). Answers 201 with the invite and emailSent (false when the email already has an account: they join at their next sign-in). |
DELETE | /org/invites/{inviteId} | owner, admin | Revokes a waiting invitation (204). |
GET | /org/api-keys | owner, admin | The organization’s push keys, newest first. Never the keys themselves. |
POST | /org/api-keys | owner, admin | Creates a push key: { "name": "…" }, 1 to 64 characters. Answers 201 with plaintext (the key, in this answer only) and key. |
DELETE | /org/api-keys/{keyId} | owner, admin | Revokes a push key (204). It stops working straight away. |
Personal API keys
| Method | Path | What it does |
|---|---|---|
GET | /api-keys | The caller’s personal keys: keyId, env, name, scopes, createdAt. Never the keys themselves. |
POST | /api-keys | Creates one: { "name": "…", "scopes": ["read:data"] } (scopes optional). Answers 201 with plaintext (in this answer only) and key. |
DELETE | /api-keys/{id} | Revokes one (204). 404 if it doesn’t exist or isn’t the caller’s. |
The dashboard’s data endpoints
The pages that show your organization’s data (datasets, approvals, metrics, views) read it from the Ontyx server at https://mcp.ontyx.io/app/v1, with the same session. Each decision there is the same one the matching tool makes in a conversation.
| Method | Path | Who | What it does |
|---|---|---|---|
GET | /me | any member | The organization’s name, the caller’s role, and whether they can approve. |
GET | /datasets | any member | Every dataset with its rows, as-of date, freshness in words, how new data is added, badges, and its last load in a sentence. |
GET | /datasets/{name} | any member | One dataset: columns, checks with their last state, relationships with their match, a waiting change in words, what it’s built from, and its last load in full. |
GET | /datasets/{name}/versions | any member | Its loads, newest first, and its structure versions with who decided them and what changed. |
GET | /datasets/{name}/preview | any member | The first rows of the data version in use (?rows=, 25 by default, up to 100), the same rows the assistant’s preview gives, with each column’s kind and what it holds, and notes on a refused last load, a waiting change, a dataset built from others or one marked for deletion. |
GET | /lineage | any member | One dataset, metric or saved view (?dataset=, ?metric= or ?view=) with everything it depends on and everything that depends on it, and how each link stands. |
GET | /approvals | any member | Every structure change and metric version waiting for approval, oldest first. |
POST | /approvals/structure-changes/{dataset}/{schema_version}/approve | owner, admin | Approves a structure version, optionally with retire_metrics. A refusal that would stop metrics or datasets built from it carries would_stop. |
POST | /approvals/structure-changes/{dataset}/{schema_version}/reject | owner, admin | Rejects it, with { "reason": "…" } (required). |
POST | /approvals/metrics/{metric}/{metric_version}/approve | owner, admin | Approves a metric version. |
POST | /approvals/metrics/{metric}/{metric_version}/reject | owner, admin | Rejects it, with { "reason": "…" } (required). |
GET | /metrics | any member | The metrics in use; ?show=retired or ?show=all for the others. |
GET | /metrics/{metric} | any member | One metric: its sentence, status, versions, what it reads and how to ask it. |
POST | /metrics/{metric}/retire | owner, admin | Retires it, with an optional { "reason": "…" }. |
GET | /views | any member | Every saved view, with its metrics and parameters. |
POST | /views/{view}/rename | owner, admin | Renames it: { "name": "…" }. |
DELETE | /views/{view} | owner, admin | Deletes it. Its metrics and data stay. |