API Reference

This page documents the public REST endpoints currently exposed by the web application. At the moment, the public surface mainly covers:

Functional agent execution
Memory type administration
Memory object administration

All endpoints require a Bearer token.

Authentication

Include your server token in the Authorization header:

curl https://your-instance.nara.de/api/endpoint \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json"

Generate server tokens from Settings > API & Security. See Authentication & Tokens for details.

Agent API

The current public agent API is designed for functional agents. It does not accept arbitrary chat transcripts. Instead, you call a named functional agent with structured arguments.

List runnable functional agents

GET /api/agent/run

Returns the functional agents in your organization that can be executed through this API.

curl https://your-instance.nara.de/api/agent/run \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN"

Example response:

{
  "agents": [{ "name": "classifyUnspsc" }, { "name": "summarizeTicket" }]
}

Run a functional agent

POST /api/agent/run

curl -X POST https://your-instance.nara.de/api/agent/run \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "classifyUnspsc",
    "args": {
      "title": "Printer is offline",
      "description": "User cannot print from the office network printer."
    }
  }'

Field	Type	Required	Description
`agentName`	`string`	Yes	Name of the functional agent to execute
`args`	`unknown`	Yes	Structured payload validated by the agent’s configured argument schema

{
  "success": true,
  "sessionId": "api-7f6d9a32-f37a-4f69-b0bb-8bc6e4ea1f5c",
  "agentExecutionId": "cm123example",
  "agent": "classifyUnspsc",
  "output": {
    "unspsc": "43212105"
  },
  "messages": []
}

Notes:

The agent must exist by name in your organization.
The agent must be a functional agent.
Functional agents that depend on interactive app-only tools are not runnable through this API.
args must match the tool contract configured for that functional agent.

Typical error cases:

400 for invalid body data or invalid arguments
404 when the agent name does not exist
402 when there are not enough credits to execute the run

Memory API

The public memory REST API currently exposes types and objects endpoints.

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

List memory types

curl https://your-instance.nara.de/api/memory/types \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN"

Example response:

{
  "items": [
    {
      "id": "7d5d2f7f-7f4e-4609-9f2d-9e8ef5fd1111",
      "type": "TroubleshootingGuide",
      "displayName": "Troubleshooting Guide",
      "description": "Structured troubleshooting knowledge",
      "visibility": "PRIVATE",
      "version": 1,
      "jsonSchema": { "type": "object" },
      "idSchema": null,
      "groupNames": ["KNOWLEDGE"],
      "relations": []
    }
  ]
}

Create a memory type

curl -X POST https://your-instance.nara.de/api/memory/types \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TroubleshootingGuide",
    "displayName": "Troubleshooting Guide",
    "description": "Structured troubleshooting knowledge",
    "jsonSchema": {
      "type": "object",
      "required": ["title"],
      "properties": {
        "title": { "type": "string" },
        "resolution": { "type": "string" }
      }
    },
    "groupNames": ["KNOWLEDGE"]
  }'

Supported fields in the create body:

type
displayName
description
visibility
jsonSchema
idSchema
embeddingSchema
groupNames
relations

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

List memory objects

curl "https://your-instance.nara.de/api/memory/objects?type=TroubleshootingGuide&page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN"

Supported query parameters:

typeId
type
key
page
pageSize

Example response:

{
  "total": 1,
  "items": [
    {
      "id": "7ec6a9ba-32cf-4f51-b859-5e5c228f2222",
      "typeId": "7d5d2f7f-7f4e-4609-9f2d-9e8ef5fd1111",
      "key": "printer-offline-fix",
      "content": {
        "title": "Printer Offline Fix",
        "resolution": "Restart the spooler and verify connectivity."
      }
    }
  ]
}

Create a memory object

curl -X POST https://your-instance.nara.de/api/memory/objects \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": "7d5d2f7f-7f4e-4609-9f2d-9e8ef5fd1111",
    "key": "printer-offline-fix",
    "content": {
      "title": "Printer Offline Fix",
      "resolution": "Restart the spooler and verify connectivity."
    }
  }'

Update a memory object

curl -X PATCH https://your-instance.nara.de/api/memory/objects/7ec6a9ba-32cf-4f51-b859-5e5c228f2222 \
  -H "Authorization: Bearer YOUR_SERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "title": "Printer Offline Fix",
      "resolution": "Restart the spooler service, then reconnect the printer."
    }
  }'

Error handling

Endpoints return JSON errors with an error field and, where relevant, additional details.

Example:

{
  "error": "Invalid request data"
}

Common statuses:

Status	Meaning
`400`	Invalid request body, parameters, or schema validation
`401`	Missing or invalid token
`403`	Admin access required
`404`	Resource not found
`402`	Insufficient credits for agent execution
`500`	Unexpected server error

Next steps

Authentication & Tokens Generate and manage server tokens for API access.

Managing Agents Configure functional agents before calling them programmatically.

Memory & Knowledge Understand the schemas and objects used by the memory endpoints.