Using the API

Nairi exposes a public REST API for managing your org's agents, conversations, artifacts, vaults, env vars, and scheduled jobs from your own code, scripts, or CI. This page covers the dashboard side: how to issue and manage keys, and what to keep in mind operationally. For the API surface itself — endpoints, schemas, status codes, pagination, language samples — see the API reference and the API quickstart.

Two kinds of API keys

Nairi issues two distinct key types. They are not interchangeable, and they live in different places in the dashboard.

If you're not self-hosting, you only need a public API key. The agent key is covered in Self-hosting.

Creating a public API key

1. Open the dashboard and go to Settings → API Key.
2. Click Create API Key and give it a descriptive name (we recommend one key per integration so you can revoke each independently).
3. Copy the key value immediately. It's shown once. After you close the dialog the dashboard only displays the last four characters as a hint (e.g. nr_...maA=).
4. Store it in a secret manager (or .env for local dev). Never commit it to git.

Revoking a key

From the same Settings → API Key page, click the delete icon on the row for the key you want to revoke. Revocation is immediate: in-flight requests using that key start returning 401 Unauthorized right away. There's no grace period and no undo, so make sure the key isn't still in use before you remove it.

Best practices

• One key per integration. Separate keys for your CI, your local scripts, and each third-party app means you can rotate or revoke one without breaking the others.
• Rotate periodically. Create the replacement first, swap it in, then delete the old key.
• Don't embed keys in agent prompts or repos. If you need an agent to call back into Nairi, put the key in a vault and reference it as an env var.
• Identify your traffic. Set a meaningful User-Agent header on your client so spikes are easy to attribute when something goes wrong.

Calling the API

Once you have a key:

• The API quickstart walks through creating an agent, starting a conversation, polling for the reply, and continuing the thread — with copy-paste code in bash, TypeScript, Ruby, Python, and Go.
• The API reference covers every endpoint, request/response schemas, status codes, pagination, and error handling.

Related

• API reference
• API quickstart
• Communicate via the API — when the API is the right channel vs. Slack, Discord, or the web app.
• Self-hosting — generating an agent API key for your own nairid daemon.

---

Can't find what you're looking for? Email support@nairi.ai.