API reference

All endpoints are served relative to your instance base URL — https://app.nara.de or https://your-instance.nara.de. Authenticate every request as described in API authentication; the examples below use an API principal token. Write requests require Content-Type: application/json.

Runs

Method	Path	Description
POST	/api/v1/runs	Start a run
GET	/api/v1/runs/{runId}	Read the run receipt
GET	/api/v1/runs/{runId}/events	Stream run events (SSE)
POST	/api/v1/runs/{runId}/approve	Decide a pending approval
POST	/api/v1/runs/{runId}/cancel	Request a cooperative cancel

Runs authenticate with an API principal token issued by your nara operator. Each principal is bound to one assistant profile; the run executes with that profile’s capabilities. The Idempotency-Key header is required — repeating a key returns the same run, and reusing it with a different body returns 409.

Start a run

Body: input, an array of typed content blocks — { "type": "text", "text": … }, { "type": "json", "value": … }, { "type": "file", "fileId": … }, or { "type": "reference", "source": …, "targetId": … } — plus an optional skillId naming a delegatable skill from the bound profile’s set. File and reference handles must belong to your organization. There are no model, prompt, tool, or policy overrides.

curl -X POST https://app.nara.de/api/v1/runs \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Idempotency-Key: 6f4f2c1e-4b7a-4a4e-9c1d-2f8e5a1b0c3d" \
  -H "Content-Type: application/json" \
  -d '{ "input": [{ "type": "text", "text": "Classify invoice INV-1042" }] }'

The response is 202 with { "runId": …, "status": "running" }. Add Prefer: wait=30 to receive the finished receipt directly when the run settles within the wait window.

The run receipt

GET /api/v1/runs/{runId} returns the fixed receipt envelope: status, message, structuredResult, artifacts, citations, sideEffectReceipts, unresolved (pending approvals), and usage. A run without enough credits ends with status failed and the reason in error; the request itself does not return 402.

Events

GET /api/v1/runs/{runId}/events streams the run’s redacted event ledger as SSE. Every frame carries an id; reconnect with the standard Last-Event-ID header to resume the cursor.

Approvals

Approval-gated actions never execute inside the run. They surface under unresolved in the receipt and wait for the principal’s bound approver: a named user, any organization admin (evaluated live), or a distinct approver principal. The run’s own token can never approve.

curl -X POST https://app.nara.de/api/v1/runs/{runId}/approve \
  -H "Authorization: Bearer <approver credential>" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "…", "approved": true }'

Cancel

POST /api/v1/runs/{runId}/cancel marks the run cancelling; it stops at the next safe boundary and started actions settle with receipts.

Data types

Method	Path	Description
GET	/api/knowledge/types	List Data types
POST	/api/knowledge/types	Create a Data type
PUT	/api/knowledge/types/{id}	Update a Data type
DELETE	/api/knowledge/types/{id}	Delete a Data type

curl https://app.nara.de/api/knowledge/types \
  -H "Authorization: Bearer nara_sa_..."

curl -X POST https://app.nara.de/api/knowledge/types \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer",
    "displayName": "Customer",
    "schema": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "tier": { "type": "string" }
      }
    }
  }'

curl -X DELETE https://app.nara.de/api/knowledge/types/{id} \
  -H "Authorization: Bearer nara_sa_..."

Knowledge records

Method	Path	Description
GET	/api/knowledge/objects	List Knowledge records
POST	/api/knowledge/objects	Create a Knowledge record
PATCH	/api/knowledge/objects/{id}	Update a Knowledge record
DELETE	/api/knowledge/objects/{id}	Delete a Knowledge record

Query parameters for listing

Parameter	Description
typeId	Filter by Data type ID
type	Filter by technical type name
key	Filter by object key
page	Page number
pageSize	Results per page

curl "https://app.nara.de/api/knowledge/objects?type=customer&page=1&pageSize=20" \
  -H "Authorization: Bearer nara_sa_..."

curl -X POST https://app.nara.de/api/knowledge/objects \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "customer", "contents": { "name": "Acme GmbH", "tier": "gold" } }'

curl -X PATCH https://app.nara.de/api/knowledge/objects/{id} \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "contents": { "tier": "platinum" } }'

Roles and groups

Roles, groups, memberships, and resource grants are not exposed through the public REST API. Manage them in Organization (/admin/organization) and Access Control (/admin/rbac).

Errors

All endpoints use the shared status codes documented in API authentication: 400 invalid body, 401 authentication failure, 402 insufficient credits, 403 permission denied, 404 not found, 500 server error.