Teams and users

These endpoints manage teams, the roles inside them, and which teammates hold each role. A team groups agents. A role says which of the team's agents its members reach and what they may do with them. Teams & roles explains the idea for people who use the dashboard.

For example, an agency with one team per client can create the team, its agents and an "Editor" role from its own tools, then put the client's staff on that role.

Read the overview first for the base URL, keys, errors and paging.

Who can call these endpoints: the workspace owner only. A teammate's key gets 403, whatever its role.

Teammates themselves are invited in the dashboard. The API can put an existing teammate on a role or take them off a team, but it can't invite new ones.

List users

Returns the staff accounts of your workspace, the owner and the teammates, newest first. Chatters are not in this list. See Chatters.

text

GET /api/v1/users

bash

curl https://chat.example.com/api/v1/users \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

json

{
  "data": [
    {
      "id": "0199f410-2a3b-7c4d-8e5f-6a7b8c9d0e1f",
      "name": "Sam Lee",
      "email": "[email protected]",
      "created_at": "2026-08-02T09:00:00+00:00"
    }
  ],
  "next_cursor": null
}

Use a user's id as user_id when you assign a role or make a sign-in link.

The team object

json

{
  "id": "0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01",
  "name": "Support",
  "agents": [
    { "id": "a3f9c2e17b4d08", "name": "Help Desk" }
  ],
  "roles": [
    {
      "id": "0199f412-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "Editor",
      "description": null,
      "all_agents": false,
      "agent_ids": ["a3f9c2e17b4d08"],
      "permissions": ["agent.setup", "agent.sources.train.files", "agent.chat.view"],
      "created_at": "2026-10-25T12:00:00+00:00"
    }
  ],
  "created_at": "2026-08-01T08:00:00+00:00"
}

Field	Type	Meaning
`id`	string	The team's id. Use it as `team_id` when you create an agent.
`name`	string	The team's name.
`agents`	array	The team's agents, each with `id` and `name`.
`roles`	array	The team's roles. See The role object.
`created_at`	string	When the team was created.

List teams

Returns your teams with their agents and roles, newest first.

text

GET /api/v1/teams

bash

curl https://chat.example.com/api/v1/teams \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [team, …], "next_cursor": … }. See Pagination.

Create a team

text

POST /api/v1/teams

Body field	Type	Required	Notes
`name`	string	yes	Up to 255 characters.

bash

curl https://chat.example.com/api/v1/teams \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Client: Acme" }'

The answer is 201 Created with { "data": team }.

Get a team

text

GET /api/v1/teams/{team}

bash

curl https://chat.example.com/api/v1/teams/0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01 \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": team }.

Rename a team

text

PATCH /api/v1/teams/{team}

Body field	Type	Required	Notes
`name`	string	yes	Up to 255 characters.

bash

curl -X PATCH https://chat.example.com/api/v1/teams/0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01 \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Customer support" }'

The answer is { "data": team }.

Delete a team

text

DELETE /api/v1/teams/{team}

bash

curl -X DELETE https://chat.example.com/api/v1/teams/0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01 \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content. These teams can't be deleted, and the answer is a 422 that says why:

your primary team.
your only team. Create another one first.
a team that still has agents. Delete or move them first.
a team that still has members. Remove them first.

Remove a team member

Takes a teammate off a team. Their account stays in the workspace.

text

DELETE /api/v1/teams/{team}/members/{member}

bash

curl -X DELETE https://chat.example.com/api/v1/teams/0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01/members/0199f410-2a3b-7c4d-8e5f-6a7b8c9d0e1f \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content. A user who is not on the team is a 404. The owner can't be removed.

The role object

Field	Type	Meaning
`id`	string	The role's id.
`name`	string	The role's name.
`description`	string or null	A description, if one is set.
`all_agents`	boolean	`true` when the role reaches every agent of the team, also ones added later.
`agent_ids`	array of strings	The agents the role reaches when `all_agents` is `false`.
`permissions`	array of strings	What the role's members may do. See the codes below.
`created_at`	string	When the role was created.

The permission codes are the ones behind the switches you see when you edit a role in the dashboard:

Code	Label in the dashboard
`agent.setup`	Setup agent
`agent.channels`	Manage channels
`agent.sources.train.files`	Train Files
`agent.sources.train.text`	Train Text
`agent.sources.train.qa`	Train Q&A
`agent.sources.train.web`	Train Web
`agent.sources.train.audio`	Train Audio
`agent.sources.train.video`	Train Video
`agent.sources.train.functions`	Manage Functions
`agent.sources.train.connectors`	Manage Connectors
`agent.sources.delete`	Delete sources
`agent.chat.view`	View conversations
`agent.chat.pulse`	Conversation Pulse
`agent.chat.takeover`	Take over
`agent.chat.delete`	Delete conversations
`agent.chat.export`	Export conversations
`agent.audit.view`	View audit log
`agent.evals.view`	View evals
`agent.evals.manage`	Manage evals
`agent.guardrails.view`	View guardrails
`agent.guardrails.manage`	Manage guardrails
`agent.analytics.chats`	Chat analytics
`agent.analytics.sentiment`	Sentiment
`agent.analytics.tone`	Tones
`agent.analytics.topics`	Topics
`agent.analytics.sources`	Sources
`agent.topics.manage`	Manage topics
`agent.leads.view`	View leads
`agent.leads.settings`	Lead settings
`agent.leads.export`	Export leads
`agent.chatters.manage`	Agent Chatters
`agent.identity.manage`	Agent Identity Verification
`agent.delete`	Delete agent
`account.api_keys`	API keys
`account.connectors`	Connectors
`account.functions`	Functions
`account.prompts`	Prompts
`account.chatters.manage`	Chatters
`account.governance`	Governance
`account.security`	Security

An unknown code is a 422. To reach every agent, use all_agents instead of a code.

Create a role

text

POST /api/v1/teams/{team}/roles

Body field	Type	Required	Default	Notes
`name`	string	yes		Up to 255 characters. Must be unique in the team.
`all_agents`	boolean	no	`false`	`true` reaches every agent of the team.
`agent_ids`	array of strings	no	none	The agents the role reaches. Ignored when `all_agents` is `true`. Every id must be an agent of this team, or the request is a `422`.
`permissions`	array of strings	no	none	Permission codes from the table above.

bash

curl https://chat.example.com/api/v1/teams/0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01/roles \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Editor",
    "agent_ids": ["a3f9c2e17b4d08"],
    "permissions": ["agent.setup", "agent.sources.train.files", "agent.chat.view"]
  }'

The answer is 201 Created with { "data": role }.

Update a role

Changes the fields you send. A field you leave out keeps its value. agent_ids and permissions replace the whole list when you send them.

text

PATCH /api/v1/teams/{team}/roles/{role}

bash

curl -X PATCH https://chat.example.com/api/v1/teams/0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01/roles/0199f412-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "all_agents": true }'

The answer is { "data": role }.

Delete a role

text

DELETE /api/v1/teams/{team}/roles/{role}

bash

curl -X DELETE https://chat.example.com/api/v1/teams/0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01/roles/0199f412-5e6f-7a8b-9c0d-1e2f3a4b5c6d \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is 204 No Content. A role that members still hold is a 422. Move them to another role first.

Assign a teammate to a role

Puts a teammate on a role. They join the team, if they weren't on it, and get the role's access. A person holds one role per team, so assigning again moves them to the new role.

text

POST /api/v1/teams/{team}/roles/{role}/users

Body field	Type	Required	Notes
`user_id`	string	yes	A teammate's id from List users. Any other id is a `422`.

bash

curl https://chat.example.com/api/v1/teams/0199f3a2-1c4e-7b1a-9d2e-5f6a7b8c9d01/roles/0199f412-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users \
  -H "Authorization: Bearer $CHATVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "0199f410-2a3b-7c4d-8e5f-6a7b8c9d0e1f" }'

json

{
  "data": {
    "id": "0199f410-2a3b-7c4d-8e5f-6a7b8c9d0e1f",
    "name": "Sam Lee",
    "email": "[email protected]",
    "created_at": "2026-08-02T09:00:00+00:00"
  }
}

Teams and users#

List users#

The team object#

List teams#

Create a team#

Get a team#

Rename a team#

Delete a team#

Remove a team member#

The role object#

Create a role#

Update a role#

Delete a role#

Assign a teammate to a role#

Teams and users

List users

The team object

List teams

Create a team

Get a team

Rename a team

Delete a team

Remove a team member

The role object

Create a role

Update a role

Delete a role

Assign a teammate to a role