Skip to content
Radioso Docs home
Open app

Accounts and users

These routes manage who can access an account, which account the current session is operating on, and account-level usage visibility for signed-in members. They use the same session cookie as Auth and sessions — call them against whichever host you signed in on.

How it works

Use these routes after a session has already been established.

  1. List accessible accounts if the user belongs to more than one account.
  2. Switch the active account if needed.
  3. List current users, invitations, and workspace grants for that account.
  4. Create invitations, update roles, assign workspace grants, or remove access.
  5. Read aggregate trends or detailed AI usage when a member needs account-level activity reporting.

Organization roles are scoped to one account:

  • owner is the top authority for that organization.
  • admin can manage users, workspaces, settings, documents, ingestion, and tokens, but cannot remove or demote owners.
  • member can use workspaces broadly and reveal workspace tokens, but cannot manage users, rename the organization, create or delete workspaces, or rotate workspace tokens.

Open-source deployments have one self-created organization per server. The first signup creates it, later users join it by invitation, and signed-in users cannot create another organization. This restriction does not apply to workspaces: owners and admins can continue to create workspaces inside the organization with POST /api/v1/workspace.

Enterprise Edition allows signed-in users to create an additional organization with POST /api/v1/account/accounts. The creator becomes its owner, a default workspace is created, and the session switches to the new organization. The Enterprise monthly anti-abuse cap applies to this additional-organization path.

Any active account member can read usage trends for the current account.

text
GET /api/v1/account/usage-trends?from=2026-06-01&to=2026-06-30&granularity=day

The response is a continuous UTC bucket series. Each bucket includes:

  • conversations created in the period
  • user and assistant message counts
  • succeeded input, output, and total token usage

Use granularity=day, granularity=week, or granularity=month. from and to are inclusive YYYY-MM-DD UTC dates. Very large requests are rejected when they would produce more than 366 buckets.

You can narrow the report with workspaceId and agentId. Both filters must belong to the current account. Token usage is directly scoped by account and workspace. When agentId is supplied, token events are attributed through their conversation. Token events without a conversation are not included in agent-filtered token totals because they cannot be tied to an agent.

The report returns aggregate counts only. It does not return message content, prompts, completions, retrieved chunks, or document content.

Detailed AI usage

Use detailed usage when you need to understand the model and embedding work behind a date range, rather than just its aggregate trend. Any active account member can read the two views:

text
GET /api/v1/account/usage/messages?from=2026-06-01&to=2026-06-30
GET /api/v1/account/usage/internal-operations?from=2026-06-01&to=2026-06-30

/usage/messages returns one summary for each visitor-facing user message. Its modelTokens and embeddingTokens fields stay separate: model totals include input, completion, reasoning coverage, and—when reasoning coverage is complete—visible output. Each summary also includes its messageId and conversationId, which lets the dashboard open that turn without returning the message body. Embedding input and vector counts remain a separate subtotal, so a retrieval embedding cannot change the message’s reasoning or visible-output figure.

/usage/internal-operations returns one event at a time. It covers work such as agent setup, dashboard test chat, evals, directive drafting and coherence checks, metadata generation, document processing, and provider attempts that have no visitor message. Each row includes a stable operation label, provider and model, event kind, status, usage quality, token dimensions when available, and embedding vector count when applicable.

Both endpoints accept inclusive UTC from and to dates in YYYY-MM-DD form, an optional account-owned workspaceId, limit from 1 through 100 (50 by default), and an opaque cursor for the next page. The date range can span at most 90 days. A workspace filter that belongs to another account returns 400.

The responses are deliberately operational rather than conversational. They return attribution and token accounting, never prompt text, model completion text, message bodies, document content, provider request IDs, idempotency keys, or error details.

Invite a user

Create an invitation from the active account context.

text
POST /api/v1/account/invitations

The request body is defined by the OpenAPI schema. Use the API Reference for the exact payload.

The invite request includes a role field. Use member by default. Use admin only for trusted teammates who should manage the organization.

Revoke an invitation

Cancel a pending invitation that has not been accepted yet. Use the invitation id from the invitations array in GET /api/v1/account/users.

text
DELETE /api/v1/account/invitations/{invitationId}

Owners and admins can revoke. A revoked invitation can no longer be accepted, and its acceptance link stops working. Revoking an invitation that has already been accepted returns 409; remove that user with DELETE /api/v1/account/users/{membershipId} instead.

Workspace grants

Workspace grants are optional. If no grant exists, the user inherits their organization role for the workspace.

Use workspace grants to give a user admin or member access for a workspace. Grants do not remove inherited access.

text
PUT /api/v1/account/workspaces/{workspaceId}/grants/{userId}
DELETE /api/v1/account/workspaces/{workspaceId}/grants/{userId}

Switch account context

Switching accounts changes which account subsequent session-scoped routes operate on.

json
{
  "accountId": "account-uuid",
  "preferredWorkspaceId": "workspace-uuid"
}

accountId is required. preferredWorkspaceId is optional.

Remove account access

Use the membership id from GET /api/v1/account/users when removing access.

The route is:

text
DELETE /api/v1/account/users/{membershipId}

Endpoint reference

text
GET    /api/v1/account/users
GET    /api/v1/account/accounts
GET    /api/v1/account/usage-trends
GET    /api/v1/account/usage/messages
GET    /api/v1/account/usage/internal-operations
POST   /api/v1/account/accounts
POST   /api/v1/account/invitations
POST   /api/v1/account/switch
PATCH  /api/v1/account/users/{membershipId}
PUT    /api/v1/account/workspaces/{workspaceId}/grants/{userId}
DELETE /api/v1/account/invitations/{invitationId}
DELETE /api/v1/account/workspaces/{workspaceId}/grants/{userId}
DELETE /api/v1/account/users/{membershipId}

Common failure modes

  • 401 means the session is missing or no longer valid.
  • 400 means a usage range, cursor, page limit, or workspace filter is invalid for the current account.
  • 403 means the caller lacks the required permission. It is also returned when an open-source user attempts to create an additional organization.
  • 404 means the membership does not exist in the current account.
  • 409 usually means the requested removal would violate an account rule.