> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # The Niadra API > Base address, authentication, and the route groups of the data API and the control API. Niadra has two HTTP APIs. The **data API** belongs to each space: your agents and systems write events, read context and navigate the history there, and your governance team erases, exports, audits and measures. The **control API** manages tenants, projects, sources, keys, people and versioned configuration, and never holds customer content. The SDKs cover the agent side of the data API; every route of both APIs has its own page in this reference. ## Base address Each space has a stable address that carries its region and never names the infrastructure behind it: ```text theme={null} https://..api.niadra.com ``` The SDK derives it from the key (`nia_sk_____`). While a space moves between cells, the old one answers `421 wrong_cell` and the SDK retries on a fresh connection. The control API lives at `https://control.api.niadra.com`. ## Authentication Every route takes `Authorization: Bearer `. What the credential must be depends on the route: | Kind of route | Credential | Example | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | Agent and system routes | A source key with the scope of the route: `track`, `act`, `context`, `search`, `identify` | [`POST /v1/context`](/en/api/context) needs `context` | | Governance routes | A Console person token with one of the roles of the route, or a source key with the `admin` scope | [`POST /v1/forget`](/en/api/forget) needs `security` | | Base-wide analysis | A source key with the `analytics` scope (analyst sources only), or a person with `analysis`; a reveal also needs `admin` on the key, or `security` on the person | [`POST /v1/insights/aggregate`](/en/api/insights-aggregate) | | Webhook entry | The method declared in the mapping of the source: bearer, HMAC signature, URL token or mTLS | [`POST /v1/ingest/webhook/{source_id}`](/en/api/ingest-webhook) | | Control API | The token of a person, from [`POST /v1/auth/login`](/en/api/control/login), valid 15 minutes | [`GET /v1/users/me`](/en/api/control/me) | The Console roles are `admin`, `security`, `integration`, `review`, `analysis` and `vendor`. `admin` passes every role check. A `vendor` person only sees the sources named in their role binding. A key without the scope a route needs gets `403 scope_missing`; a person without the role gets `403 forbidden`. Each reference page says what its route accepts. ## Route groups | Group | What it covers | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Write | [batch](/en/api/batch), [media uploads](/en/api/media-uploads), [file imports](/en/api/ingest-files) and [their status](/en/api/ingest-file), [system webhooks](/en/api/ingest-webhook) and [their challenge](/en/api/ingest-webhook-challenge), [OTLP traces](/en/api/otel-traces), [feedback](/en/api/feedback) | | Context | [by handle](/en/api/context), [by profile id](/en/api/context-by-profile), [subject tokens](/en/api/subject-tokens), [MCP server](/en/api/mcp) | | History | [search](/en/api/history-search), [timeline by handle](/en/api/history-timeline), [timeline by profile](/en/api/history-timeline-by-profile), [open an item](/en/api/history-item), [tool definitions](/en/api/history-tools) | | Objects | [state](/en/api/object) and [timeline](/en/api/object-timeline) of an order, ticket or invoice | | Identity and profiles | [assertions](/en/api/identity-assertions), [create](/en/api/identity-assertions-create), [retract](/en/api/identity-assertion-retract), [merge](/en/api/identity-merge), [unmerge](/en/api/identity-unmerge), [block a handle](/en/api/identity-handles-block), [links](/en/api/identity-links), [suggestions](/en/api/identity-suggestions), [profile search](/en/api/profiles-search), [profile](/en/api/profile), [memory](/en/api/profile-memory), [objects](/en/api/profile-objects) | | Privacy and audit | [forget](/en/api/forget), [erasure list](/en/api/forget-list), [export](/en/api/export), [export runs](/en/api/export-runs), [receipts](/en/api/receipts), [chain verification](/en/api/receipts-verify), [lineage](/en/api/lineage-receipt), [policy simulation](/en/api/policy-simulate), [secrets](/en/api/secrets) | | Sources | [coverage](/en/api/sources-coverage), [cut a source in the cell](/en/api/source-revoke) | | Patterns, measurement and usage | [retract a pattern](/en/api/trait-retract), [dry-run a rule](/en/api/traits-dry-run), [opt out](/en/api/traits-opt-out), [context use](/en/api/context-use), [usage](/en/api/usage) | | Review and assistant | [review queue](/en/api/review-queue), [verdicts](/en/api/review-verdicts), [agreement](/en/api/review-agreement), [configuration assistant](/en/api/assist) | | Triggers and webhooks | [dry-run a trigger](/en/api/triggers-dry-run), [firings](/en/api/trigger-firings), [deliveries](/en/api/webhook-deliveries), [redeliver](/en/api/webhook-redeliver) | | Base-wide analysis | [schema](/en/api/insights-schema), [overview](/en/api/insights-overview), [aggregate](/en/api/insights-aggregate), [find profiles](/en/api/insights-profiles), [search](/en/api/insights-search), [reveal](/en/api/insights-reveal), [analysis MCP](/en/api/mcp-insights) | | Control API | [access](/en/api/control/login), [people and roles](/en/api/control/me), [projects](/en/api/control/projects), [sources and keys](/en/api/control/sources), [configuration](/en/api/control/config-types), [usage](/en/api/control/usage), [platform operations](/en/api/control/cells) | ## Conventions in one table | Topic | Rule | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Version | In the path (`/v1`). New fields and routes never change it; removing or changing the meaning of a field is `/v2`, with 12 months of coexistence and a `Deprecation` header | | Personal data | Phones, e-mails, documents and free text go in the body, never in the URL. That is why context, search and timeline by handle are `POST`; their `GET` forms take a profile id | | Idempotency | Events carry `idempotency_key`; identity writes, `POST /v1/forget` and source revocation require the `Idempotency-Key` header | | Errors | `application/problem+json` with a stable `code`; the batch answers `200`, or `207` when some items were rejected | | Pagination | Opaque `cursor` and `limit` (up to 200 on lists, 100 on timelines) | | Cache | ETag on deterministic reads; for context by handle, send `known_etag` in the body; by profile, `If-None-Match` returns `304` | | Tracing | `traceparent` is accepted and returned; every answer carries `request_id` | The details are in [Limits and conventions](/en/conventions) and [Errors](/en/errors). ## Contract The reference is generated from the OpenAPI 3.1 contract that the server exports from its own code, the same file the SDKs and the Console are tested against. Enum values and field names are English ASCII and never change meaning within `/v1`. ## Next steps The call every agent makes before it acts. Messages, system events and actions. The code catalog and what to do with each code. Sizes, rates, idempotency and caching.