Web widget

GET /v1/agents/{name}/share-links#

List test links. Public "try this agent" links for one agent: pages we host at /try/{token} that embed the agent's web widget, so you can hand a reviewer a URL instead of an embed snippet. Each carries its url, how many sessions it has spent, and a status of active, expired, exhausted or revoked.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/agents/{name}/share-links" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "items": [
    {
      "agent": "front-desk",
      "created_at": "2026-09-14T12:00:00Z",
      "expires_at": "2026-09-17T12:00:00Z",
      "label": "for the reviewer",
      "last_used_at": "2026-09-14T15:20:00Z",
      "max_sessions": 20,
      "revoked": false,
      "sessions_used": 3,
      "status": "active",
      "token": "k3JqTz9wY1n8Qb2vXm5LpR0e",
      "url": "https://api.voiceland.ai/try/k3JqTz9wY1n8Qb2vXm5LpR0e"
    }
  ]
}

POST /v1/agents/{name}/share-links#

Create a test link. Mints an unguessable link that hosts this agent's web widget on our domain. Anyone with the URL can talk to the agent, so the link expires (expires_in_hours, default 168, at most 720; or no_expiry: true for a link that only revocation or the cap ends), is capped (max_sessions, default 50, at most 1000) and can be revoked. Every session it mints spends your minutes under your own rate limit and concurrency cap, exactly like a session from your site; the token only widens who can reach the agent. The agent's web widget must be enabled.

Request body

application/json Schema: WidgetShareRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/agents/{name}/share-links" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "expires_in_hours": 72,
  "label": "for the reviewer",
  "max_sessions": 20
}'

A successful response returns a WidgetShareView.

Example response

{
  "agent": "front-desk",
  "created_at": "2026-09-14T12:00:00Z",
  "expires_at": "2026-09-17T12:00:00Z",
  "label": "for the reviewer",
  "last_used_at": "2026-09-14T15:20:00Z",
  "max_sessions": 20,
  "revoked": false,
  "sessions_used": 3,
  "status": "active",
  "token": "k3JqTz9wY1n8Qb2vXm5LpR0e",
  "url": "https://api.voiceland.ai/try/k3JqTz9wY1n8Qb2vXm5LpR0e"
}

DELETE /v1/agents/{name}/share-links/{token}#

Revoke a test link. Withdraws the link at once: the hosted page answers 404 and no further session can be minted with it. Sessions already running are unaffected.

Parameters

Responses

Example request

curl -X DELETE "https://api.voiceland.ai/v1/agents/{name}/share-links/{token}" \
  -H "Authorization: Bearer VL_API_KEY"

Schemas#

Error#

Error envelope returned for non-2xx responses.

WidgetShareRequest#

WidgetShareView#