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

All endpoints are served from:

https://api.nairi.ai

Authentication

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

Authorization: Bearer YOUR_API_KEY

You can generate API keys from your organization's settings in the Nairi dashboard.

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.

Quick start

New to the API? The 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.

1. Configure and deploy an agent

Create the agent, attach a rule and a vault, then deploy it.

2. Drive a conversation

Start a conversation, poll for the reply, and send a follow-up.

3. Full example

The whole flow as one runnable script, in every supported language.

What you can do

Conversations

Start, continue, and poll agent conversations.

Agent resources

Attach rules, MCP configs, skills, and vaults to agents.

Env vars

Plaintext environment variables for agent containers.

Rules

Text-based instructions that guide agent behavior.

MCP configs

Model Context Protocol tool integrations.

Vault secrets

Individual secrets injected into agent environments.

Channels

Slack and Discord channels connected to your organization.

Scheduled jobs

Cron-driven jobs that post to Slack or Discord.

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.

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

All errors share a consistent JSON shape:

{
  "error": "error message here"
}

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

When an agent fails to process a message:

The user message's status is set to failed.
A new system role message is appended with details. The content follows the format:
```
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

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.

Overview