> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiaxoniq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Authenticate, understand the error shape, and find the endpoint you need — everything the aiAxonIQ product does is available programmatically.

Everything you can do in the dashboard, you can do through the API. It is the
same API the dashboard uses, so there is no second-class surface and nothing
that only the interface can reach.

<Info>
  **This reference is generated from the running route table**, so it cannot
  drift from what the API actually accepts. The endpoint pages beneath this one
  carry parameters, request shapes and status codes per operation.
</Info>

## Authenticate

Two credentials, and using the wrong one is the most common first error.

| Credential        | For                                          | Sent as                                |
| :---------------- | :------------------------------------------- | :------------------------------------- |
| **Session token** | Reading and changing anything in the product | `Authorization: Bearer <token>`        |
| **License key**   | Sending telemetry, and nothing else          | `X-License-Key` on the ingest endpoint |

<Warning>
  **A license key does not work on the API.** It authenticates ingest only. A
  request to `/api/logs` carrying `X-License-Key` is unauthenticated and
  returns `401`.

  The reverse is also true — a session token will not ingest telemetry. See
  [Authentication](/get-started/authentication).
</Warning>

Browser clients use an HttpOnly cookie set at sign-in; programmatic clients use
a bearer token. Both resolve to the same session.

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
     "https://app.aiaxoniq.com/api/services"
```

## Your organization is not a parameter

Many endpoints accept a `tenantId` query parameter. It is a historical artefact
and it is **always overwritten from your session**.

<Note>
  **Naming an organization other than your own returns `403`, not your own
  data.** The failure is visible rather than silently corrected — so a bug in
  your client surfaces immediately instead of producing plausible results from
  the wrong place.

  You never need to send it. A value that must equal your session's is a value
  with no reason to exist.
</Note>

## Errors

Every non-2xx response uses one shape:

```json theme={null}
{
  "error": "RETENTION_EXCEEDED",
  "message": "Your plan allows querying up to 30 days back."
}
```

<Warning>
  **Branch on `error`, never on `message`.** The `error` code is stable and is
  part of the contract. The `message` is written for a human and may be
  reworded at any time.
</Warning>

The ones you will meet:

| Status | `error`              | Means                                                                                            |
| :----- | :------------------- | :----------------------------------------------------------------------------------------------- |
| `400`  | `RETENTION_EXCEEDED` | The query reaches further back than your plan allows — see [Data retention](/concepts/retention) |
| `401`  | —                    | Missing or invalid session                                                                       |
| `403`  | `UPGRADE_REQUIRED`   | The feature is not enabled on your plan                                                          |
| `403`  | —                    | Authenticated, but your role is insufficient — see [Roles](/concepts/roles)                      |
| `404`  | —                    | No such resource **in your organization**                                                        |
| `429`  | —                    | Rate limited                                                                                     |

<Note>
  **A `403` for a role and a `403` for a plan are different problems with
  different fixes.** One is answered by an Admin in your organization; the
  other by your account contact. The `error` code distinguishes them.
</Note>

## Roles

Read endpoints need **Viewer**. Creating and editing product configuration
needs **Editor**. Users, license keys and billing need **Admin**. The audit log
needs **Auditor**, Admin or Owner.

The full model, including why Auditor is not a rung on the ladder, is on
[Roles and permissions](/concepts/roles).

## Working with the API

<AccordionGroup>
  <Accordion title="Querying telemetry" icon="magnifying-glass">
    Logs, metrics, traces and services are all queryable, with the same time
    ranges and filters the product uses. Results are cached briefly, so two
    identical requests in quick succession may return the same response — see
    [Platform architecture](/concepts/architecture).
  </Accordion>

  <Accordion title="Managing configuration as code" icon="file-code">
    Alert rules, dashboards, SLOs, synthetic checks and notification channels
    can all be created and updated programmatically — which is what makes it
    practical to keep them in version control and apply them per environment.

    Synthetic checks additionally import and export as YAML.
  </Accordion>

  <Accordion title="Prometheus-compatible queries" icon="chart-area">
    A subset of the Prometheus HTTP API, so Grafana can read aiAxonIQ as a
    datasource with no adapter. **Read the limits before relying on it** — rate
    functions parse and return an average. See
    [Grafana and Prometheus clients](/guides/integrations/grafana).
  </Accordion>

  <Accordion title="Usage reporting" icon="gauge">
    Ingest volume against plan allowances, for your own dashboards or a monthly
    report. Cached for five minutes.
  </Accordion>
</AccordionGroup>

## Sending telemetry

Ingest is a different surface with different rules — a license key rather than
a session, its own status codes and its own limits. It is documented under
[Ingest endpoints](/send-data/endpoints) rather than here.

## Next

<CardGroup cols={3}>
  <Card title="Authentication" icon="shield-halved" href="/get-started/authentication">
    The two credentials and which to use where.
  </Card>

  <Card title="Roles and permissions" icon="user-shield" href="/concepts/roles">
    What each role can reach.
  </Card>

  <Card title="Ingest endpoints" icon="list" href="/send-data/endpoints">
    The other half of the surface.
  </Card>
</CardGroup>