Via the API

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 and the API reference.

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.

The basic flow

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

1. Start a conversation

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

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:

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

3. Continue the conversation

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

• 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

• 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

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

Related

• Using the API
• Communicate in Slack & Discord
• Communicate in the web app
• System events

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