Stop waiting on a handle

curl --request POST \
  --url https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "handle": "wt_9d06ad7bc3674fe1aa789ec2eda55c3c",
  "kind": "job",
  "cancelled_at": "2026-08-17T12:31:07Z"
}

{
  "type": "https://docs.narrative.io/reference/architecture/agent-conversations/errors/invalid-tool-alias",
  "title": "Invalid Tool Alias",
  "status": 400,
  "detail": "invalid tool aliases (must match ^[a-zA-Z][a-zA-Z0-9]{0,7}$): with_underscore",
  "instance": "/agents",
  "log_id": "1f6e5d4c-3b2a-1098-7654-3210fedcba98",
  "debug": null
}

Agent Conversations

Stop waiting on a handle

Drops the conversation’s claim on a handle. A run parked on that handle wakes, is told the handle is no longer being waited on, and carries on — it reports back, asks a question, or does something else. The run finishes normally, so the conversation is free to take its next turn immediately.

What this does not do

It does not cancel the work. The job behind the handle keeps running exactly as before, the same way a wait timing out leaves its job alone. Stop the job through its own API if that is what you want.

It does not cancel the run. The turn completes on its own terms, with the abandoned wait recorded in the conversation — nothing is discarded.

The model is told the handle reads stopped_waiting, which says what happened to the wait and claims nothing about the task.

When there is nothing to wake

The claim is dropped whether or not a run is currently parked on it, and the response says when. If the run had already moved on, or the wait had already finished, there is simply nothing to interrupt — and a later wait_for on that handle reads the dropped claim rather than waiting again.

Idempotent: cancelling the same handle twice returns the same cancelled_at.

Permission

agent_conversations resource with write verb.

POST

agents

conversations

{id}

waitables

{handle}

cancel

Stop waiting on a handle

curl --request POST \
  --url https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/agents/conversations/{id}/waitables/{handle}/cancel")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "handle": "wt_9d06ad7bc3674fe1aa789ec2eda55c3c",
  "kind": "job",
  "cancelled_at": "2026-08-17T12:31:07Z"
}

{
  "type": "https://docs.narrative.io/reference/architecture/agent-conversations/errors/invalid-tool-alias",
  "title": "Invalid Tool Alias",
  "status": 400,
  "detail": "invalid tool aliases (must match ^[a-zA-Z][a-zA-Z0-9]{0,7}$): with_underscore",
  "instance": "/agents",
  "log_id": "1f6e5d4c-3b2a-1098-7654-3210fedcba98",
  "debug": null
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string<uuid>

required

The conversation's UUID. UUID identifying a conversation. Returned from POST /agents/conversations and used in every other agent endpoint that operates on this conversation.

Example:

"bc2505b7-068d-44ed-8055-a6f6ffe54ab1"

handle

string

required

The handle to stop waiting on, exactly as job_monitor returned it. Opaque — do not parse or construct one. The pattern is the alphabet handles are drawn from, not their format: a segment outside it does not match this route and returns 404, the same answer an unusable handle gets.

Maximum string length: 128

Pattern: ^[A-Za-z0-9_-]+$

Example:

"wt_9d06ad7bc3674fe1aa789ec2eda55c3c"

Response

The handle, with the moment its claim was dropped.

A handle after its claim has been dropped. Nothing here reports how the task behind the handle is doing: dropping a claim does not touch the task, so its own API is where to look.

handle

string

required

The handle, as job_monitor returned it.

Example:

"wt_9d06ad7bc3674fe1aa789ec2eda55c3c"

kind

enum<string>

required

What sort of task the handle points at.

Available options:

job

cancelled_at

string<date-time> | null

When the claim was dropped. Set on the first cancel and never moved, so cancelling the same handle again reports the original moment.

Example:

"2026-08-17T12:31:07Z"

⌘I