Read a share link

GET
/v1/share-links/{linkId}

Reads one share link with its recent refusals and stops: why a visit was turned away or a conversation ended (expired, revoked, conversations_used, minutes_used, budget_used, busy and the others), each with when and how many times in a row. Use it to see why a link stopped working, and send its version as If-Match when you change it.

Requires an API key with the share_links:read 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

linkId*string

The share link id, from the list or from the answer that made it.

Response Body

The link with its recent refusals and stops

application/json
  1. response
id*string

The link id.

agentId*string

The agent the link opens.

Formatuuid
state*string

active, expired or revoked (turned off).

Value in"active""expired""revoked"
title*string
displayName*string
target*string

live: the published version of the agent. draft: its draft as it is now. The link keeps the version it was made from until you update it.

Value in"live""draft"
sealedVersionLabel*string

What version the link runs, in words: "Published version of Nov 8" or "Draft of Nov 8, 3:12 pm".

sealedAt*string
Formatdate-time
privacyUrl*string
limits*

The nine caps of the link.

expiresAt*string
Formatdate-time
tools*

Which tools the link has off. Tools that send, call or transfer to a destination from the conversation are always off.

usage*
lastUsedAt*|
Formatdate-time
revokedBy*|

Who turned it off, when it was.

revokedAt*|
Formatdate-time
createdBy*string
createdAt*string
Formatdate-time
updatedAt*string
Formatdate-time
version*integer

Send this back as If-Match when you change the link. A stale one is refused with 409.

behindPublishedReason?|

Set when the link runs an older version than the agent publishes now, and says why it was not moved. Change the link to update it.

recent*array<>

Recent refusals and stops, newest first.

Itemsitems <= 50
Example Request
curl "https://api.vlayers.ai/v1/share-links/$SHARE_LINK_ID" \  -H "Authorization: Bearer $VOICELAYER_API_KEY"
Example Response
{  "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": 20,    "voiceMinutes": 60,    "dollarsMicros": 10000000,    "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": 3,    "minutes": 12.5,    "spentMicros": 1500000  },  "lastUsedAt": "2026-11-09T09:30:00.000Z",  "revokedBy": null,  "revokedAt": null,  "createdBy": "user_2abc",  "createdAt": "2026-11-08T15:12:00.000Z",  "updatedAt": "2026-11-08T15:12:00.000Z",  "version": 3,  "recent": [    {      "reason": "busy",      "at": "2026-11-09T09:31:00.000Z",      "count": 2    }  ]}