# Using the API

Issue API keys and call Nairi programmatically.





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](/api) and the [API quickstart](/api/quickstart).

## Two kinds of API keys [#two-kinds-of-api-keys]

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

| Key                | Prefix     | Created in         | Used for                                                                     |
| ------------------ | ---------- | ------------------ | ---------------------------------------------------------------------------- |
| **Public API key** | `nr_`      | Settings → API Key | Calling `https://api.nairi.ai/api/public/v1` from your code, CI, or scripts. |
| **Agent API key**  | `ccagent_` | Self-host page     | Authenticating a self-hosted `nairid` daemon back to Nairi's control plane.  |

If you're not self-hosting, you only need a public API key. The agent key is covered in [Self-hosting](/help/self-hosting).

## Creating a public API key [#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.

<Callout type="warn">
  Treat the key like a password. Anyone with it can manage every agent, conversation, vault, and scheduled job in your org until you revoke it.
</Callout>

## Revoking a key [#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 [#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](/help/vaults) 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 [#calling-the-api]

Once you have a key:

* The [API quickstart](/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](/api) covers every endpoint, request/response schemas, status codes, pagination, and error handling.

## Related [#related]

* [API reference](/api)
* [API quickstart](/api/quickstart)
* [Communicate via the API](/help/communicating-with-agents/api) — when the API is the right channel vs. Slack, Discord, or the web app.
* [Self-hosting](/help/self-hosting) — generating an agent API key for your own `nairid` daemon.

***

*Can't find what you're looking for? Email [support@nairi.ai](mailto:support@nairi.ai).*