Make a share link

POST
/v1/agents/{id}/share-links

Makes a public link to one agent and answers with the address to share, once. Anyone who has it can talk to the agent without signing in, up to the caps: $10, 20 conversations and 60 minutes of talking in all unless you set others, until the link ends (seven days unless you set another, up to 30). What they use is charged to your balance; a call counts in full while it is running, so the last few dollars may go unused. The link runs the version you choose (live or draft) as it is when you make it, with every tool that may change something switched off until you name it in toolsOn; tools that send a message, place a call or transfer to a destination taken from the conversation are always off, and the agent's memory is never read. Only an admin of the workspace can make a link: an API key cannot, whatever its scopes. An agent whose code runs on your own server cannot be shared this way (share_unsupported_for_remote_agent).

Requires an API key with the share_links:write scope.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

id*string

The agent id.

Request Body

application/json
  1. body
title*string

The name of the page visitors open.

Length1 <= length <= 80
displayName?string

Who is shown as sharing it. The workspace name when left out.

Length1 <= length <= 80
target*string

live for the published version, draft for the draft as it is now. The link keeps that version until you update it.

Value in"live""draft"
privacyUrl*string

The address of your privacy policy, which visitors see before they talk. https only; you answer for what they say.

Lengthlength <= 500
expiresInSeconds?integer

How long the link works from now, in seconds: one hour (3600) to 30 days. Seven days when left out.

Range3600 <= value <= 2592000
limits?

Any of the nine caps; the ones you leave out take their default.

toolsOn?array<>

The tools to switch on, by name. Every tool that may change something is off until you name it here.

Itemsitems <= 256

Response Body

The link, and the address to share, shown this once

application/json
  1. response
link*
url*string

The link to share. It is returned this once: a list never carries it, and an admin copies it again in the dashboard.

Formaturi
Example Request
curl -X POST "https://api.vlayers.ai/v1/agents/$AGENT_ID/share-links" \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "title": "Books team test",    "target": "live",    "privacyUrl": "https://example.com/privacy",    "limits": {      "dollarsMicros": 5000000,      "conversations": 12    }  }'
Example Response
{  "link": {    "id": "grt_0192f5e1a2b37c4d8e5f6a7b8c9d0e1f",    "agentId": "0192f5c2-6f7a-7b9c-8d1e-2f3a4b5c6d78",    "state": "active",    "title": "Books team test",    "displayName": "Acme Books",    "target": "live",    "sealedVersionLabel": "Published version of Nov 8",    "sealedAt": "2026-11-08T15:12:00.000Z",    "privacyUrl": "https://acmebooks.example/privacy",    "limits": {      "conversations": 12,      "voiceMinutes": 60,      "dollarsMicros": 5000000,      "atOnce": 2,      "callMinutes": 5,      "typedMessages": 40,      "typedDollarsMicros": 1000000,      "perAddressPerDay": 5,      "perAddressPerHour": 3    },    "expiresAt": "2026-11-15T15:12:00.000Z",    "tools": {      "off": [        "refund_order",        "vl_send_text"      ]    },    "usage": {      "conversations": 0,      "minutes": 0,      "spentMicros": 0    },    "lastUsedAt": null,    "revokedBy": null,    "revokedAt": null,    "createdBy": "user_2abc",    "createdAt": "2026-11-08T15:12:00.000Z",    "updatedAt": "2026-11-08T15:12:00.000Z",    "version": 1  },  "url": "https://try.vlayers.ai/t#vlsl_Zk3m9QvXwA1nB7cD2eF4gH6iJ8kL0mN5oP7qR9sT1uV"}