API reference

Sub-accounts

Create separate workspaces under your organization, each with its own API key and concurrency limits.

A sub-account is a separate workspace inside your organization. It has its own agents, calls, numbers and API key, so one customer or team cannot see another's data. Sub-accounts share the organization's concurrency and spend the parent account's wallet. See the Sub-accounts guide.

All routes need Authorization: Bearer <key> from the organization's main account. A sub-account's own key cannot manage sub-accounts: every route here then answers 403 with Only organization admins can manage sub-accounts. Creating, updating and deleting need the admin role; reading needs viewer.

Operation	Method and path
Create a sub-account	`POST /sub-accounts/create`
List sub-accounts	`GET /sub-accounts/all`
Update a sub-account	`PATCH /sub-accounts/{sub_account_id}`
Delete a sub-account	`DELETE /sub-accounts/{sub_account_id}`
Usage across every sub-account	`GET /sub-accounts/all/usage`
Get usage of one sub-account	`GET /sub-accounts/{sub_account_id}/usage`

Concurrency limits

Each sub-account has two numbers:

min_concurrency: calls the sub-account can always run at the same time, even when the rest of the organization is busy.
max_concurrency: the most calls it may run at the same time. Without it, the organization's maximum applies.

The minimums of all sub-accounts together may not exceed the organization's minimum, and no maximum may exceed the organization's maximum.

Operations

Create a sub-account

POST /sub-accounts/create

Creates a sub-account and its API key. The key starts with sa-.

Auth: API key or session token of the organization's main account. Role: admin and up.

Parameter	In	Type	Required	Description
`name`	body	string	yes	Display name.
`min_concurrency`	body	integer	one of the two	Guaranteed concurrent calls. Default `0`.
`max_concurrency`	body	integer	one of the two	Cap on concurrent calls.
`multi_tenant`	body	boolean	no	Stored flag. Default `false`.
`db_host`, `db_name`, `db_port`, `db_user`, `db_password`	body	string	no	Stored with the sub-account and returned by this call.

Limitation: multi_tenant and the db_* fields are stored and returned as sent. The platform does not use them to place a sub-account's data in a separate database.

Request

bash

curl -X POST https://api.sevennadi.si/sub-accounts/create \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"name": "Example Bank - Collections", "min_concurrency": 2, "max_concurrency": 5}'

Response 200 OK

json

{
  "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "name": "Example Bank - Collections",
  "organization_id": "3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a",
  "api_key": "sa-0123456789abcdef0123456789abcdef",
  "multi_tenant": false,
  "min_concurrency": 2,
  "max_concurrency": 5,
  "user_id": "4a257495-4e4b-484e-92e5-c616a720ec03",
  "created_at": "2026-10-13T08:20:00Z",
  "updated_at": "2026-10-13T08:20:00Z"
}

user_id is the id of the account that created the sub-account.

Errors

Status	Message
400	`Bad request. Please provide name.`
400	`Bad request. Please provide min_concurrency and/or max_concurrency.`
400	`Sum of account minimums (<n>) exceeds the org minimum (<n>) by <n>; lower an account minimum first.`
400	`max_concurrency (<n>) exceeds the organization maximum (<n>).`
400	`min_concurrency cannot be greater than max_concurrency.`
403	`Only organization admins can manage sub-accounts.`

List sub-accounts

GET /sub-accounts/all

Returns the organization's sub-accounts, oldest first.

Auth: API key or session token of the organization's main account. Role: viewer and up.

No parameters.

Request

bash

curl https://api.sevennadi.si/sub-accounts/all \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

[
  {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "name": "Example Bank - Collections",
    "organization_id": "3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a",
    "api_key": "sa-0123456789abcdef0123456789abcdef",
    "api_key_masked": false,
    "multi_tenant": false,
    "min_concurrency": 2,
    "max_concurrency": 5
  }
]

Who gets the key:

Caller	`api_key`	`api_key_masked`
An API key of the main account, or a login with the role admin or owner	The real key. Each such request is written to the security log as `sub_account_keys_read`.	`false`
A login with the role member or viewer	`sa-` followed by 28 zeros and the key's last four characters. It has the shape of a key and does not work as one.	`true`
Anyone, when the operator has set `SUB_ACCOUNT_KEYS_VISIBLE=false`	Masked as above. The real key is then shown once only, in the response that creates the sub-account.	`true`

Warning: For admins, owners and API keys this list returns each sub-account's API key in full. Treat the response as a secret.

Errors

Status	Message
403	`Only organization admins can manage sub-accounts.`

Update a sub-account

PATCH /sub-accounts/{sub_account_id}

Changes the name or the concurrency limits. Fields you leave out keep their values.

Auth: API key or session token of the organization's main account. Role: admin and up.

Parameter	In	Type	Required	Description
`sub_account_id`	path	string (UUID)	yes	The sub-account.
`name`	body	string	no	New name.
`min_concurrency`	body	integer	no	New guaranteed concurrency.
`max_concurrency`	body	integer	no	New cap.

Request

bash

curl -X PATCH https://api.sevennadi.si/sub-accounts/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"max_concurrency": 8}'

Response 200 OK

json

{"message": "success", "state": "updated"}

Errors

The concurrency messages of Create a sub-account, 403 Only organization admins can manage sub-accounts. and 404 Sub-account not found.

Delete a sub-account

DELETE /sub-accounts/{sub_account_id}

Deletes a sub-account and revokes its API keys at once. Requests with those keys then answer 401.

Auth: API key or session token of the organization's main account. Role: admin and up.

Parameter	In	Type	Required	Description
`sub_account_id`	path	string (UUID)	yes	The sub-account.

Request

bash

curl -X DELETE https://api.sevennadi.si/sub-accounts/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

{"message": "success", "state": "deleted"}

Errors

Status	Message
403	`Only organization admins can manage sub-accounts.`
404	`Sub-account not found`

Usage across every sub-account

GET /sub-accounts/all/usage

Returns one usage report per sub-account for a time window. The default window is the last 30 days.

Auth: API key or session token of the organization's main account. Role: viewer and up.

Parameter	In	Type	Required	Description
`from`	query	string	no	Start, as an ISO 8601 date or timestamp in UTC. Default: 30 days before `to`.
`to`	query	string	no	End. A bare date includes that whole day. Default: now.

Request

bash

curl "https://api.sevennadi.si/sub-accounts/all/usage?from=2026-10-01&to=2026-10-13" \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

json

[
  {
    "sub_account_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "from": "2026-10-01",
    "to": "2026-10-13T23:59:59.999999+00:00",
    "total_records": 42,
    "total_duration": 1830.5,
    "total_cost": 134.4,
    "total_platform_cost": 58.8,
    "total_telephony_cost": 29.4,
    "status_map": {"completed": 36, "no-answer": 4, "busy": 2},
    "synthesizer_cost_map": {"elevenlabs": {"eleven_turbo_v2_5": {"characters": 51200, "cost": 25.2}}},
    "transcriber_cost_map": {"deepgram": {"nova-2": {"duration": 1830.5, "cost": 12.6}}},
    "llm_cost_map": {"openai": {"gpt-4o-mini": {"tokens": 96000, "cost": 8.4}}}
  }
]

The report counts executions created inside the window. Each cost map is keyed by provider, then model, and holds the units used and their cost. The numbers above only show the shape.

Errors

Status	Message
400	`from/to must be ISO 8601 dates or timestamps`
403	`Only organization admins can manage sub-accounts.`

Get usage of one sub-account

GET /sub-accounts/{sub_account_id}/usage

Returns the usage report of one sub-account.

Auth: API key or session token of the organization's main account. Role: viewer and up.

Parameter	In	Type	Required	Description
`sub_account_id`	path	string (UUID)	yes	The sub-account.
`from`	query	string	no	As above.
`to`	query	string	no	As above.

Request

bash

curl "https://api.sevennadi.si/sub-accounts/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/usage?from=2026-10-01" \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

The same report object as above, without sub_account_id.

Errors

Status	Message
400	`from/to must be ISO 8601 dates or timestamps`
403	`Only organization admins can manage sub-accounts.`
404	`Sub-account not found`