Web widget

Οι περιγραφές των endpoints και των πεδίων εμφανίζονται στα αγγλικά, όπως ακριβώς τις δημοσιεύει το API. Είναι επιλογή μας, ώστε να διαβάζετε εδώ ό,τι θα δείτε και στις αποκρίσεις.

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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

{
  "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; or unlimited_sessions: true for no cap, max_sessions 0 on the link) 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.

Σώμα αιτήματος

application/json Σχήμα: WidgetShareRequest

Αποκρίσεις

Παράδειγμα αιτήματος

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
}'

Η επιτυχής απόκριση επιστρέφει ένα WidgetShareView.

Παράδειγμα απόκρισης

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

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Σχήματα#

Error#

Error envelope returned for non-2xx responses.

WidgetShareRequest#

Options for a public test link. All optional.

WidgetShareView#

A test link as reads return it: the row plus the URL to hand out and its status.