Overview

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

1. Start a conversation with POST /conversations/start, passing an agent_id and an initial prompt. The API returns a job_id and the message_id of your prompt.
2. The agent picks up the job and appends assistant messages as it works. You can poll a single message or list all messages on the job.
3. 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.