API · Get started

Authentication & keys

Every request carries a secret key. A key acts for your account and can do what its permissions allow.

Create a key

Keys are made in the console, under Developers. Give the key a name (for example "Production server" or "Setup agent"), tick its permissions and click Create key. The full key starts with sk_live_ and is shown once; afterwards the console shows only its first characters, when it was created and when it was last used. An account can hold up to 10 active keys. Keys can only be created in the console, never with another key.

Send it with every request

Put the key in the Authorization header as a bearer token:

curl https://talk.selviaai.com/v1/agent/list \
  -H "Authorization: Bearer sk_live_…"

A key is a password for your account. Use it from your server or your agent's secret store, never in a web page or a mobile app, and never commit it to a repository.

Permissions

Each key has one or more permissions. A call the key isn't allowed to make answers 403.

Permission	Allows
`read`	Reading: agents, conversations and transcripts, usage, billing, voices (every GET outside /v1/sessions).
`setup`	Creating and changing things: agents, faces, voices, languages, studio, knowledge, data handoffs.
`sessions`	Starting, stopping, listing and directing live sessions (everything under /v1/sessions).
`delete`	Every DELETE. Each one must also add `?confirm=true` to the request.

New keys get read, setup and sessions. Give delete only to a key that needs it. A key that only starts sessions for a website can be sessions alone.

Deleting needs a confirmation

So that a script or an AI agent can't remove something by accident, every DELETE needs both the delete permission and confirm=true:

curl -X DELETE "https://talk.selviaai.com/v1/agent/42?confirm=true" \
  -H "Authorization: Bearer $SELVIA_API_KEY"

Revoke a key

Click Revoke next to the key in the console. It stops working at once, and every call made with it answers 401.

Audit log

Every call that changes something and is made with a key is recorded: which key, what was called, the result and when. Reads are not recorded. If you hand a key to an AI agent, this is how you see what it did.

When it fails

•401: no key, a malformed header, or a key that was revoked.
•403: the key lacks the permission for this call, or the account is not active.
•400: a DELETE without ?confirm=true.
•429: more than 120 requests a minute with one key. See Limits & pricing.