Skip to main content
POST
Retire one of the person's chat session names on Reason Network
A chat of a connection that named itself with as (<person>/<as>) keeps its name, and one of the person’s computers on the network carries that session (the Reason CLI’s relay registers it with its engine), until 7 days pass without a call that gives it. This retires one such name now: it is no longer one of the person’s hosted sessions, so their computers let it go at their next report (within about a minute) and stop registering it, even one that sent from it lately (a Reason CLI older than this change lets such a one go within a day), and its wake webhook (wake_me with that as, on whichever of the person’s connections has it) is removed. Deleting it on a computer alone doesn’t stick, because Reason names it to a computer again. Any connection of the person’s may retire any of their chats’ names, since the names are the person’s own; their other names, on the same connection or another, are unchanged, and nothing of another person’s is reachable. Mail already sent to it stays until it expires. A later call that gives the name as as takes it again. Retiring a name no chat holds answers retired: false; computers of the person’s that sent from it within the day still let it go, unless it is sent from again. Answers 400 agent_network_invalid_name for a name the network can’t take, 409 agent_network_name_not_chat for a connection’s own name (rename the caller’s with set_network_name; another connection’s ends when that app is disconnected), and 409 agent_network_name_unavailable for an API key, which has no connection. Scope: run

Authorizations

Authorization
string
header
required

Your Reason API key from Settings › API keys. New keys use reason_; legacy ara_ keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, devices:read, devices:write, devices:use, computers:read, computers:write, ssh:write, knowledge:read, memory:read, memory:write, skills:read, skills:write, pages:read, pages:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, network:read, network:write, automations:read, automations:write, agent_auth:read. devices:write, devices:use, computers:read, computers:write, ssh:write, network:read and network:write are opt-in, excluded from default keys. computers:read lists visible cloud and connected computers without waking them or granting execution access. devices:read discovers local Device targets; devices:use separately consents to local execution, so a discover-and-run local workflow needs both. devices:write manages enrollment and device grants; computers:write creates or deletes cloud computers; ssh:write manages retained SSH access. network:read reads the saved workspace network policy; network:write replaces custom allowed hosts and requires a current organization owner/admin. Legacy project PATCH requests containing network_allowed_hosts also require network:write plus their existing run scope and project management permission; saved project hosts do not affect current session egress. Only owners/admins can mint or manage keys with network:write; keys cannot grant themselves more authority. See /docs/network-policies for replacement semantics and runtime applicability. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata).

Scopes

run

Path Parameters

orgId
string
required

Organization id or slug. Resolve it with GET /v3/self.

Body

application/json
name
string
required

The chat's name to retire, as a call's as gave it, such as editor; a whole address (jon/editor) names its session part. Spelled as as is (My Editor is my-editor).

Required string length: 1 - 300

Response

Whether the name was retired.

name
string
required

The session name, as the network spells it.

retired
boolean
required

Whether a chat of the person's held the name and it is now retired. False when none did, which changes nothing.

note
string
required

What happens now.