Stop

Stop the turn an agent is running on a conversation. The agent ends its current work and the conversation stays open for a follow-up.

Asks the agent to stop the turn it is running on a conversation. Use it when a task is going the wrong way or has run for too long.

POST /api/public/v1/conversations/{job_id}/stop

No request body. Requires an API key with the conversations:write scope.

What happens

Every user message still waiting on this conversation is ended, and the agent is told to stop.
The response is 202 Accepted right away. The stop itself is asynchronous.
When the agent confirms, a system message is added to the conversation: Stopped by API key <name>. Send a message to continue. The name is the API key's name from the dashboard.
If the agent has not confirmed within a minute, a system message says so. The agent may be offline or running an older nairid.

The conversation is not closed. Send a follow-up with Continue to carry on from where it stopped.

Example

curl -X POST https://api.nairi.ai/api/public/v1/conversations/JOB_ID/stop \
  -H "Authorization: Bearer $NAIRI_API_KEY"

const res = await fetch(
  `https://api.nairi.ai/api/public/v1/conversations/${jobId}/stop`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.NAIRI_API_KEY}` },
  },
);
const data = (await res.json()) as { job_id: string };

require "net/http"
require "json"
require "uri"

uri = URI("https://api.nairi.ai/api/public/v1/conversations/#{job_id}/stop")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV['NAIRI_API_KEY']}"

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
data = JSON.parse(res.body)

import os
import requests

res = requests.post(
    f"https://api.nairi.ai/api/public/v1/conversations/{job_id}/stop",
    headers={"Authorization": f"Bearer {os.environ['NAIRI_API_KEY']}"},
)
data = res.json()

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	jobID := os.Getenv("JOB_ID")
	req, _ := http.NewRequest(
		"POST",
		"https://api.nairi.ai/api/public/v1/conversations/"+jobID+"/stop",
		nil,
	)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("NAIRI_API_KEY"))
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	raw, _ := io.ReadAll(res.Body)
	var data map[string]any
	json.Unmarshal(raw, &data)
	fmt.Println(data)
}

Response: `202 Accepted`

{
  "job_id": "job_01KRK1V46BXS73CSNK2VR35NPJ"
}

Errors

Status	Body	When
`404`	`{"error":"job not found"}`	The `job_id` does not exist in your organization.
`400`	`{"error":"job is not an API job"}`	The conversation was started from Slack, Discord or the dashboard. Only conversations started with `POST /conversations/start` can be stopped here.
`409`	`{"error":"nothing is running for this conversation"}`	The agent is not working on anything right now, or no agent holds the conversation.
`409`	`{"error":"a stop for this conversation is already on its way"}`	A stop was requested less than a minute ago and the agent has not answered it yet.
`403`		The API key does not have the `conversations:write` scope.

What happens

Example

Response: 202 Accepted

Errors

On this page

Response: `202 Accepted`