Agent API

Public API Server-to-server Functional agents

What this page covers

Use this page when you want to trigger an agent from outside the webapp – for example from a backend service, a cron job, or another platform.

• Supported entrypoint: POST /api/agent/run
• Scope: functional agents with a JSON argument schema
• Auth: JWT bearer token with admin privileges for the target organization

Good fit

Use the Agent API when you want a single structured response (function-style call) rather than a long-running chat session.

Prerequisites

1. Create a functional agent in the nara webapp and publish it to your organization.
2. Configure the agent’s Arguments type (JSON schema) so inputs can be validated.
3. Note the agent’s name – this is what you pass as agentName on the API.
4. Obtain an admin API token (JWT) for the organization you want to run the agent in.

Endpoint overview

HTTP (recommended)

The HTTP endpoint is available from your nara webapp:

POST https://app.nara.de/api/agent/run
Authorization: Bearer <ADMIN_JWT>
Content-Type: application/json

Request body:

{
  "agentName": "support_triage",
  "args": {
    "ticketId": "TCK-12345",
    "priority": "high",
    "language": "en"
  }
}

On success the response contains the agent’s structured result and the internal execution trace:

{
  "success": true,
  "sessionId": "api-...",
  "agent": "support_triage",
  "output": {
    "category": "billing",
    "nextStep": "escalate_to_human",
    "summary": "Customer cannot update credit card."
  },
  "messages": [
    {
      "role": "assistant",
      "parts": [{ "type": "text", "text": "…" }]
    }
  ]
}

If validation or authorization fails you receive an error JSON payload with an appropriate HTTP status (4xx or 5xx).

Node.js via fetch

const baseUrl = 'https://app.nara.de'
const token = process.env.NARA_ADMIN_TOKEN ?? ''

type SupportTriageResult = {
  category: string
  nextStep: string
  summary: string
}

async function runSupportTriage(args: unknown): Promise<SupportTriageResult> {
  const response = await fetch(`${baseUrl}/api/agent/run`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      agentName: 'support_triage',
      args,
    }),
  })

  if (!response.ok) {
    throw new Error(`Agent call failed with status ${response.status}`)
  }

  const payload = (await response.json()) as {
    success?: boolean
    output?: unknown
    error?: string
  }

  if (!payload.success || !payload.output) {
    throw new Error(payload.error ?? 'Agent call failed')
  }

  return payload.output as SupportTriageResult
}

This pattern works from any Node.js service that can reach the webapp URL and attach an appropriate admin token.

@nara/rpc (internal)

For services that already run alongside the webapp, you can also use the typed RPC client exposed by @nara/rpc to call the same functionality, while letting the webapp handle authentication:

import { createRpcClient } from '@nara/rpc/client'

const rpc = createRpcClient()

const functionalAgents = await rpc.agent.list({ type: 'FUNCTIONAL' })

// Use the HTTP endpoint or internal hooks to execute functional agents.

Use this from trusted internal services. For third-party integrations and server-to-server calls, prefer the HTTPS endpoint shown in the HTTP tab.

Authentication model

Admin-only

Agent execution requires an admin context for the target organization. The token must carry an admin role for that org.

JWT tokens

Tokens are verified by the nara platform; you can either call the endpoint from an authenticated admin session or send an admin-scoped JWT as a bearer token.

Organization scoping

The agent must belong to the same organization as the token. Cross-org execution is rejected.

Choosing the right token

For long‑lived integrations prefer a dedicated service token with an admin role in the target organization instead of reusing interactive user tokens.

Inspecting available functional agents

You can discover functional agents that are executable via this API:

GET https://app.nara.de/api/agent/run
Authorization: Bearer <ADMIN_JWT>

The response lists agents by name:

{
  "agents": [{ "name": "support_triage" }, { "name": "contract_summary" }]
}

Use these names as agentName when calling POST /api/agent/run.

Next steps

Bring agents into your workflows

The typical next step is to call your functional agent from a scheduler, event handler, or ticketing integration and persist the output payload into your own system.

Explore the Edge Connector for on‑prem tools