The Niadra 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:

https://<space>.<region>.api.niadra.com

The SDK derives it from the key (nia_sk_<live|test>_<region>_<space>_<key_id>_<secret>). 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 <credential>. 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` 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` 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`
Webhook entry	The method declared in the mapping of the source: bearer, HMAC signature, URL token or mTLS	`POST /v1/ingest/webhook/{source_id}`
Control API	The token of a person, from `POST /v1/auth/login`, valid 15 minutes	`GET /v1/users/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, media uploads, file imports and their status, system webhooks and their challenge, OTLP traces, feedback
Context	by handle, by profile id, subject tokens, MCP server
History	search, timeline by handle, timeline by profile, open an item, tool definitions
Objects	state and timeline of an order, ticket or invoice
Identity and profiles	assertions, create, retract, merge, unmerge, block a handle, links, suggestions, profile search, profile, memory, objects
Privacy and audit	forget, erasure list, export, export runs, receipts, chain verification, lineage, policy simulation, secrets
Sources	coverage, cut a source in the cell
Patterns, measurement and usage	retract a pattern, dry-run a rule, opt out, context use, usage
Review and assistant	review queue, verdicts, agreement, configuration assistant
Triggers and webhooks	dry-run a trigger, firings, deliveries, redeliver
Base-wide analysis	schema, overview, aggregate, find profiles, search, reveal, analysis MCP
Control API	access, people and roles, projects, sources and keys, configuration, usage, platform operations

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 and 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

Read context

The call every agent makes before it acts.

Send a batch

Messages, system events and actions.

Errors

The code catalog and what to do with each code.

Limits and conventions

Sizes, rates, idempotency and caching.

Overview

Write

Context

History

Objects

Identity and profiles

Privacy and audit

Sources

Patterns, measurement and usage

Review and assistant

Triggers and webhooks

Base-wide analysis

Control: access

Control: tenant and projects

Control: sources and keys

Control: configuration

Control: usage

Control: platform operations

The Niadra API

Base address

Authentication

Route groups

Conventions in one table

Contract

Next steps

Read context

Send a batch

Errors

Limits and conventions

​Base address

​Authentication

​Route groups

​Conventions in one table

​Contract

​Next steps

Read context

Send a batch

Errors

Limits and conventions

Base address

Authentication

Route groups

Conventions in one table

Contract

Next steps