# Via the API

Start and continue conversations with your agents from scripts, CI, or your own code.



Nairi exposes a public REST API for talking to agents programmatically. This page gives you a quick overview. For the full reference (every endpoint, schemas, language examples), see [Using the API](/help/using-the-api) and the [API reference](/api).

## Authentication [#authentication]

* Header: `Authorization: Bearer <NAIRI_API_KEY>`.
* Keys are issued per org under **Settings → API Key**.
* Keys are not interchangeable with the agent API key used by self-hosted `nairid` daemons.

See [Using the API → Creating a public API key](/help/using-the-api#creating-a-public-api-key).

## The basic flow [#the-basic-flow]

Three steps: start a conversation, poll until the reply lands, then continue.

### 1. Start a conversation [#1-start-a-conversation]

```bash
curl -X POST https://api.nairi.ai/api/public/v1/conversations/start \
  -H "Authorization: Bearer $NAIRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"AGENT_ID", "prompt":"hello"}'
```

Response includes a `job_id` (for follow-ups and the message list) and a `message_id` (for polling).

### 2. Poll for the reply [#2-poll-for-the-reply]

```bash
curl https://api.nairi.ai/api/public/v1/messages/<message_id> \
  -H "Authorization: Bearer $NAIRI_API_KEY"
```

The user message moves through `queued` → `pending` → `completed` (or `failed`). Poll until you see a terminal status, then fetch the full thread:

```bash
curl https://api.nairi.ai/api/public/v1/conversations/<job_id>/messages \
  -H "Authorization: Bearer $NAIRI_API_KEY"
```

### 3. Continue the conversation [#3-continue-the-conversation]

```bash
curl -X POST https://api.nairi.ai/api/public/v1/conversations/<job_id>/continue \
  -H "Authorization: Bearer $NAIRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"and the second question..."}'
```

## When to use the API [#when-to-use-the-api]

* CI jobs that need an agent to review a PR or run a check.
* Internal tools that wrap Nairi behind your own UI.
* One-off scripts: backfills, batch jobs, periodic reports.

For interactive, human-driven use, Slack/Discord or the Tasks UI in the web app are usually a better fit.

## Best practices [#best-practices]

* **One API key per integration.** Revocation is targeted; you can rotate a script's key without breaking CI.
* **Store keys in a secret manager**, not in code or `.env` files committed to git.
* **Idempotency**: each conversation has a `job_id`; reuse it to continue, mint a new one for a fresh thread.

## Full reference [#full-reference]

See the [Nairi API reference](/api) for every endpoint, request/response schemas, and code samples in five languages.

## Related [#related]

* [Using the API](/help/using-the-api)
* [Communicate in Slack & Discord](/help/communicating-with-agents/slack-and-discord)
* [Communicate in the web app](/help/communicating-with-agents/web-app)
* [System events](/help/communicating-with-agents/system-events)

***

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