Overview
What conversations are and how to drive agent work programmatically — start, continue, list, and inspect message threads via the Nairi REST API.
A conversation is a job assigned to a single agent — an ordered list of messages (user, assistant, and system) plus a status that tracks the agent's progress. Conversations are how you trigger work programmatically instead of typing into Slack, Discord, or the dashboard.
How it works
- Start a conversation with
POST /conversations/start, passing anagent_idand an initialprompt. The API returns ajob_idand themessage_idof your prompt. - The agent picks up the job and appends
assistantmessages as it works. You can poll a single message or list all messages on the job. - To send a follow-up, call
POST /conversations/{job_id}/continue. Only API-started jobs can be continued via the API — jobs created from Slack, Discord, or the web UI are off-limits.
When to use it
- Embed Nairi as the AI layer in your own product. Run an agent on behalf of an end user and render the conversation in your UI.
- Kick off agent work from your own systems. Trigger conversations from CI pipelines, webhooks, cron, or backend services — no human in the loop.
Modes
execute(default) — agent has full tool access.ask— agent answers without invoking tools.
See Message reference for the full list of message roles and statuses returned by the message endpoints.
3. Full example
End-to-end runnable script covering agent setup, deployment, and a full conversation. Available in every language Nairi's REST API supports.
Start
Create a new Nairi conversation and dispatch the first user message to a deployed agent. Returns the conversation ID and the message ID to poll on.