Skip to main content
POST
Share a link with the agent
Registers an https URL with the session. The agent sees only the returned reference and can open it once in the session’s cloud browser by passing the reference to browser_use open_tab; the URL itself is stored encrypted and never returned. Mention the reference in a message to ask the agent to open it. 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.

sessionId
string
required

The session id, returned as session_id by createSession and listSessions.

Body

application/json
url
string
required

Absolute https URL to open in the session's cloud browser. Stored encrypted; never returned or shown to the agent.

label
string

Short display name for the link in lists, for example Local app. Omitted or blank, the URL's host is used.

Maximum string length: 80
expires_in_seconds
integer
default:3600

How long after creation the agent may open the link; once it passes, the link can no longer be opened and its status reads expired.

Required range: 60 <= x <= 86400

Response

The shared link.

id
string
required

The shared link's id; pass it as linkId to revokeSessionSharedLink.

reference
string
required

The only form the agent sees: pass it to browser_use open_tab as the url.

label
string
required

Display name of the link.

origin
string
required

Scheme and host of the stored URL.

status
enum<string>
required

active until the agent opens it (opened), it is revoked (revoked) or its lifetime ends (expired).

Available options:
active,
opened,
revoked,
expired
created_by_user_id
string | null
required

The member who registered the link.

created_at
string
required

When the link was registered.

expires_at
string
required

When the reference stops working if it was not opened first.

opened_at
string | null
required

When the agent opened the link; null until then.

revoked_at
string | null
required

When the link was revoked; null unless revoked.