Create Share Link | SpeechifyAI API

Mint a share link for the agent.

The response carries the link’s bearer token. It is also stored encrypted, 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.

Mint a share link for the agent. The response carries the link's bearer `token`. It is also stored encrypted, 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.

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

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.

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. 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.

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).

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.

token_recoverableboolean

Whether revealShareLinkToken can return this link’s URL. False for links created before the token was stored recoverably: theirs was hashed and discarded, so the only way to share again is a new link. Read it before offering a copy action.

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. 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

$	curl -X POST https://api.speechify.ai/v1/agents/agent_01jqr8x9zg5k2m3n4p5q6r7s8t/share-links \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{}'

1	{
2	"id": "share_01jqr8x9zg5k2m3n4p5q6r7s8t",
3	"agent_id": "agent_01jqr8x9zg5k2m3n4p5q6r7s8t",
4	"label": "sent to Acme Inc, 4 Aug",
5	"token_prefix": "Ax7Kq2Rd",
6	"token_recoverable": true,
7	"status": "active",
8	"expires_at": "2024-08-11T15:00:00Z",
9	"revoked_at": "null",
10	"budget_seconds": 3600,
11	"seconds_used": 120,
12	"seconds_reserved": 60,
13	"seconds_remaining": 3420,
14	"max_call_duration_seconds": 300,
15	"max_concurrent": 3,
16	"allowed_tool_ids": [
17	"tool_webhook_01a2b3c4d5e6f7g8h9i0jklm"
18	],
19	"last_used_at": "2024-08-10T14:45:00Z",
20	"created_at": "2024-08-04T09:30:00Z",
21	"token": "Ax7Kq2Rd9fGhJkLmNpQrStUvWxYz1234"
22	}