How-to guide

Public access

Set how many sessions website visitors may start, how long they last, and what they agree to first.

What you'll build

Limits for the visitors who talk to your agent from your website, set from the dashboard or from code, and a way to see why a visit was turned away.

A visitor reaches an agent through a website key: the publishable key behind the voice button. Public access decides whether that key is open, and how much it may do.

How the limits stack

Limits are set at four levels: the platform and your plan, your workspace, one agent, and one website key. Levels only tighten. A cap is the lowest of them, and any "off" wins. A website key is open only when its own row says enabled: true, for the agent it was enabled for. Pointing the key at a different agent turns it off again.

SettingRangeMeaning
enabledtrue or falseWhether sessions are allowed
sessionsPerDay0 to 500Sessions a key admits per day
concurrentSessions0 to 10Sessions at the same time
perIpPerHour1 to 20Sessions from one address per hour
maxCallMinutes1 to 5Longest session
perSenderPerDay1 to 10Replies one sender gets per day (messaging)
botCheckon or offWhether visitors pass a bot check first
consentprivacyUrl, statementsWhat the visitor agrees to before the call starts

The consent step needs a privacy policy address (consent.privacyUrl) before public access can be on. statements is 1 to 8 sentences of up to 200 characters. Left out, the defaults are used.

Prerequisites

  • A secret API key with public_access:read to read and public_access:write to change. See Authentication and API keys.
  • A website key. Create it in the dashboard under Settings → Workspace → Public access, where you also set the daily budget, the bot check and the limits.
Who may loosen a limit. A key may tighten: turn public access off or lower a cap. Turning it on, raising a cap, turning the bot check off and changing the bot check's keys need a workspace admin. A key that asks gets 403 forbidden. Enabling a website key also needs a hard daily budget on the key that covers every session it may run at once.

Step 1: See what is set

GET /v1/public-access/settings returns one row for the workspace, one per agent and one per website key. Each row has a version. Send it back as the If-Match header on the next write so you never overwrite a newer change.

curl https://api.vlayers.ai/v1/public-access/settings \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"

Step 2: See what a visitor gets right now

GET /v1/public-access/effective?keyId=… resolves the result for one website key: whether it is open, why not when it is not (offReason), each cap, and which level decided each value (sources).

curl "https://api.vlayers.ai/v1/public-access/effective?keyId=$WEBSITE_KEY_ID" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"

Step 3: Change a limit

Each level has a PUT that sets only the fields you send and a DELETE that removes the row, so that level inherits again. Add a note to say why; it goes in the change log.

Pause all public sessions in the workspace:

curl -X PUT https://api.vlayers.ai/v1/public-access/settings/workspace \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "enabled": false
    },
    "note": "Pausing public sessions during the launch review"
  }'

Allow one agent at most one session at a time:

curl -X PUT "https://api.vlayers.ai/v1/public-access/settings/agents/$AGENT_ID" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "concurrentSessions": 1
    }
  }'

Set a website key's daily sessions:

curl -X PUT "https://api.vlayers.ai/v1/public-access/settings/bindings/$BINDING_ID" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "sessionsPerDay": 20
    }
  }'

Remove a row:

curl -X DELETE "https://api.vlayers.ai/v1/public-access/settings/agents/$AGENT_ID" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"

deleteWorkspacePublicAccess and deleteBindingPublicAccess do the same for the workspace and a key. Removing a row that said "off" loosens, so it needs an admin. Removing a key's row turns public access off for that key.

Step 4: See why visits were turned away

GET /v1/public-access/usage?keyId=… counts today (UTC): sessions admitted and ended, and attempts turned away with the reason. A visitor sees one generic message; you see why.

curl "https://api.vlayers.ai/v1/public-access/usage?keyId=$WEBSITE_KEY_ID" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
{
  "keyId": "key_9b3d42",
  "since": "2026-10-20T00:00:00.000Z",
  "admitted": 12,
  "ended": 11,
  "refusals": [{ "reason": "challenge_failed", "count": 3 }, { "reason": "ip_rate", "count": 1 }]
}

Pair it with the key's daily budget to watch spend.

From a chat assistant

Over MCP, public_access_get reads the settings and public_access_tighten lowers them. Loosening stays with a workspace admin in the dashboard.

Test it

Read the effective settings for your key, lower sessionsPerDay to 1 with putBindingPublicAccess, read them again, and check that sources.sessionsPerDay names the key's level.

Next steps

On this page