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 a server token. Write requests require Content-Type: application/json.

Agent execution

Method	Path	Description
GET	/api/agent/run	List runnable workflow agents
POST	/api/agent/run	Execute a workflow agent by name

Only workflow agents can be executed via the API; chat agents are not runnable this way. Agents whose tools require WEBAPP execution cannot run over the API either.

Each agent’s editor also has a Call this agent via API dialog that shows the exact endpoint, headers, and ready-made code samples for that agent.

List runnable agents

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

Run a workflow agent

Body: agentName (the agent’s internal name) and args (an object matching the agent’s input data type).

curl -X POST https://app.nara.de/api/agent/run \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "agentName": "invoice-classifier", "args": { "invoiceId": "INV-1042" } }'

Memory types

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

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

curl -X POST https://app.nara.de/api/memory/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/memory/types/{id} \
  -H "Authorization: Bearer nara_sa_..."

Memory objects

Method	Path	Description
GET	/api/memory/objects	List memory objects
POST	/api/memory/objects	Create a memory object
PATCH	/api/memory/objects/{id}	Update a memory object
DELETE	/api/memory/objects/{id}	Delete a memory object

Query parameters for listing

Parameter	Description
typeId	Filter by memory 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/memory/objects?type=customer&page=1&pageSize=20" \
  -H "Authorization: Bearer nara_sa_..."

curl -X POST https://app.nara.de/api/memory/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/memory/objects/{id} \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "contents": { "tier": "platinum" } }'

Roles

Method	Path	Description
GET	/api/roles	List roles
POST	/api/roles	Create a custom role
GET	/api/roles/{id}	Get a role
PUT	/api/roles/{id}	Update a role
DELETE	/api/roles/{id}	Delete a custom role
POST	/api/roles/{id}/assign	Assign the role to a principal
POST	/api/roles/{id}/unassign	Remove the role from a principal
GET	/api/roles/{id}/principals	List principals assigned to the role

The built-in Admin and Member roles cannot be deleted or renamed.

curl -X POST https://app.nara.de/api/roles \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Lead",
    "description": "Manages tickets and support access",
    "permissions": ["ticket.view", "ticket.update", "supportAccess.manage"]
  }'

curl -X POST https://app.nara.de/api/roles/{id}/assign \
  -H "Authorization: Bearer nara_sa_..." \
  -H "Content-Type: application/json" \
  -d '{ "principalType": "USER", "principalId": "<user-id>" }'

curl https://app.nara.de/api/roles/{id}/principals \
  -H "Authorization: Bearer nara_sa_..."

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.