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.
| Setting | Range | Meaning |
|---|---|---|
enabled | true or false | Whether sessions are allowed |
sessionsPerDay | 0 to 500 | Sessions a key admits per day |
concurrentSessions | 0 to 10 | Sessions at the same time |
perIpPerHour | 1 to 20 | Sessions from one address per hour |
maxCallMinutes | 1 to 5 | Longest session |
perSenderPerDay | 1 to 10 | Replies one sender gets per day (messaging) |
botCheck | on or off | Whether visitors pass a bot check first |
consent | privacyUrl, statements | What 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:readto read andpublic_access:writeto 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.
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.