API ReferenceShare LinksManage

Create Share Link

Beta
Mint a share link for the agent. The response carries the link's bearer `token`. It is also stored, so a caller who loses it reads it back with `revealShareLinkToken` instead of revoking and re-creating — which would kill the copy the recipient already has. Every cap is optional and falls back to a bounded default. There is no way to express "unlimited": an anonymous link that spends the workspace's balance should not be creatable by omitting a field. An agent may hold at most 10 live links at once; an eleventh is refused with `409 share_link_limit_reached`. Revoking a link, or letting one expire, frees its slot immediately.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

agent_idstringRequired

Agent id (prefixed external id, agent_...).

Headers

Speechify-VersionstringOptional
Idempotency-KeystringOptional<=255 characters
A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Request

This endpoint expects an object.
labelstringOptional<=120 characters
An optional note so several links can be told apart.
expires_in_secondsintegerOptional
How long the link stays usable. A duration rather than a timestamp, so a client with a skewed clock cannot mint a link that is already expired. Defaults to 7 days, maximum 30.
budget_secondsintegerOptional
Total conversation time the link may authorise, across all its calls. This is the control that bounds what a leaked link can cost. Defaults to 1 hour, maximum 4.
max_call_duration_secondsintegerOptional
Ceiling on a single call. Defaults to 5 minutes, maximum 30, and is clamped again to the agent's own limit.
max_concurrentintegerOptional
Simultaneous calls allowed on this link. Defaults to 3, maximum 10.
allowed_tool_idslist of stringsOptional

Tools to opt this link into, by id — the same tool_… ids listAgentTools returns. Omit for the default posture (call controls and knowledge search only). Opting a webhook or MCP tool in lets a stranger drive it, so it is an explicit act rather than something inherited from the agent. Every id must name a tool attached to this agent; anything else is a 400.

Response headers

Speechify-Request-IdstringOptional
Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

The created link, including its one-time token.

idstringformat: "^share_[0-9a-hjkmnp-tv-z]{26}$"
agent_idstringformat: "^agent_[0-9a-hjkmnp-tv-z]{26}$"
labelstring
The owner's own note on the link, for telling several apart.
token_prefixstring
The token's leading characters, kept so a list can show a recognisable masked label. Useless as a guess on its own.
statusenum

The link’s resolved lifecycle state, computed server-side so every client agrees on what “expired” means.

expires_atdatetime
revoked_atdatetime or null
budget_secondsinteger
Total conversation time this link may ever authorise.
seconds_usedinteger
Conversation time settled against the link.
seconds_reservedinteger
Conversation time held by calls currently in flight.
seconds_remaininginteger

What a new call can still draw on: the budget minus settled and in-flight time. Reservations count against it, so two simultaneous starts cannot both spend the tail.

max_call_duration_secondsinteger
Ceiling on any single call opened through this link. Clamped at dispatch against the agent's own limit and the workspace plan, so a link can shorten a call but never lengthen one.
max_concurrentinteger

How many calls this link may run at once. Bounded separately from the workspace’s own concurrency cap, so a widely-shared link cannot consume the capacity the owner’s real callers need.

allowed_tool_idslist of strings

Tools the owner opted this link into, by id — the same tool_… ids listAgentTools returns. Empty means the default posture: the agent’s built-in call controls and knowledge search only, with no webhook, MCP or transfer tool — a link recipient is a stranger, not the owner’s customer.

last_used_atdatetime or null
created_atdatetime
tokenstring
The link's opaque bearer token.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error