# Overview

Programmatic access to your Nairi organization. Manage agents, conversations, artifacts, vaults, and more.





The Nairi REST API lets you manage your organization's agents, run conversations, and configure artifacts (rules, MCP configs, skills, vaults, env vars, scheduled jobs) programmatically.

## Base URL [#base-url]

All endpoints are served from:

```text
https://api.nairi.ai
```

## Authentication [#authentication]

Every request must include a Bearer token in the `Authorization` header:

```http
Authorization: Bearer YOUR_API_KEY
```

You can generate API keys from your organization's settings in the [Nairi dashboard](https://app.nairi.ai).

<Callout type="warn">
  Treat API keys like passwords. Never commit them to source control or share them publicly. If a key is compromised, revoke it from the dashboard.
</Callout>

## Quick start [#quick-start]

New to the API? The &#x2A;*[Quickstart](/api/quickstart)** walks through the full end-to-end flow — configure an agent, deploy it, and drive a conversation — with copy-paste code in bash, TypeScript, Ruby, Python, and Go.

<Cards>
  <Card title="1. Configure and deploy an agent" href="/api/quickstart/configure-and-deploy" description="Create the agent, attach a rule and a vault, then deploy it." />

  <Card title="2. Drive a conversation" href="/api/quickstart/drive-a-conversation" description="Start a conversation, poll for the reply, and send a follow-up." />

  <Card title="3. Full example" href="/api/quickstart/full-example" description="The whole flow as one runnable script, in every supported language." />
</Cards>

## What you can do [#what-you-can-do]

<Cards>
  <Card title="Conversations" href="/api/conversations/start" description="Start, continue, and poll agent conversations." />

  <Card title="Agents" href="/api/agents/list" description="Create, deploy, and manage agents." />

  <Card title="Agent resources" href="/api/agent-resources/list" description="Attach rules, MCP configs, skills, and vaults to agents." />

  <Card title="Env vars" href="/api/env-vars/list" description="Plaintext environment variables for agent containers." />

  <Card title="Rules" href="/api/rules/list" description="Text-based instructions that guide agent behavior." />

  <Card title="MCP configs" href="/api/mcp-configs/list" description="Model Context Protocol tool integrations." />

  <Card title="Skills" href="/api/skills/list" description="Packaged capabilities (.skill / .zip)." />

  <Card title="Vaults" href="/api/vaults/list" description="Logical containers for secrets." />

  <Card title="Vault secrets" href="/api/vault-secrets/list" description="Individual secrets injected into agent environments." />

  <Card title="Channels" href="/api/channels/list" description="Slack and Discord channels connected to your organization." />

  <Card title="Scheduled jobs" href="/api/scheduled-jobs/list" description="Cron-driven jobs that post to Slack or Discord." />
</Cards>

## ID format [#id-format]

All resource IDs are 26-character ULIDs (lexicographically sortable, encoding both time and randomness). Most resources prefix the ULID with a short type tag so the kind of resource is obvious at a glance.

```text
cci_01KEQ6963XS96YDP3NF9NKB7QJ
```

| Prefix         | Resource                                                                               |
| -------------- | -------------------------------------------------------------------------------------- |
| `cci_`         | Agents (container integrations)                                                        |
| `ccr_`         | Agent resource assignments                                                             |
| `cev_`         | Agent environment variables                                                            |
| `aar_`         | Rules                                                                                  |
| `amc_`         | MCP configs                                                                            |
| `ask_`         | Skills                                                                                 |
| `vlt_`         | Vaults                                                                                 |
| `sec_`         | Vault secrets                                                                          |
| `ai_`          | Anthropic integrations                                                                 |
| `cc_`          | Connected channels                                                                     |
| `sj_`          | Scheduled jobs                                                                         |
| `job_` or `j_` | Jobs (conversations). Newer jobs use `job_`. Older ones use `j_`. Treat both as valid. |
| `cmsg_`        | Conversation messages                                                                  |

Treat all IDs as opaque strings. Invalid IDs return `400 Bad Request`.

## Error handling [#error-handling]

All errors share a consistent JSON shape:

```json
{
  "error": "error message here"
}
```

### Common status codes [#common-status-codes]

| Status | Meaning                                          |
| ------ | ------------------------------------------------ |
| `200`  | Success                                          |
| `201`  | Created                                          |
| `202`  | Accepted (async operation queued)                |
| `204`  | No Content (successful delete)                   |
| `400`  | Bad Request. Invalid input or validation failure |
| `401`  | Unauthorized. Missing or invalid API key         |
| `404`  | Not Found                                        |
| `500`  | Internal Server Error                            |

### Conversation errors [#conversation-errors]

When an agent fails to process a message:

1. The user message's `status` is set to `failed`.
2. A new `system` role message is appended with details. The content follows the format:

   ```text
   nairid encountered error: <details>
   ```

Common scenarios:

* The agent is disconnected or unreachable.
* Task execution failure.

To detect errors, either poll the user message and check `status: "failed"`, or list all messages and look for `role: "system"`.

## Versioning [#versioning]

The current API version is **v1**, served under the `/api/public/v1/` prefix. Breaking changes will be released under a new version path. Non-breaking additions may roll out without notice.