Clomni

Scopes and endpoints: workspace, agents, teams

Last updated: 11 November 2026 · 10 min read

Scopes for workspace details, AI credit, the audit log, agents and teams. Below is what each scope allows, its risk and review, and the endpoints it opens.

Steps

  1. 1

    How to read this article

    • Paths follow https://api.clomni.ai/v1: GET /v1/agents means https://api.clomni.ai/v1/agents. Paths have no workspace ID, because a token belongs to one workspace.
    • Every request carries the Authorization: Bearer clomni_pat_xxx header. How to get a token: Tokens and authentication in the Developer API.
    • Risk: low (no personal data), medium (reads customer data or changes internal data), high (sends to customers, deletes, bulk exports, changes live settings).
    • Every scope goes through review, in public apps too. More: Review: checking scopes and rejection reasons.
    • "Also grants": write and manage grant the read of the same resource. send, delete, publish, assign and run grant nothing.
    • When an endpoint lists several scopes, any one of them is enough. Without the scope the API answers 403 insufficient_scope with required_scopes in the body.
    • Every POST takes an Idempotency-Key header, so a repeated request is not run twice.
  2. 2

    Read workspace details (workspace:read)

    Reads the workspace's name, locale, settings (such as auto-resolve) and package details. Integrations usually start here to check which workspace they are connected to.

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/workspace: Get the workspace

    Example:

    curl "https://api.clomni.ai/v1/workspace" \
  -H "Authorization: Bearer clomni_pat_xxx"
  3. 3

    Change workspace settings (workspace:write)

    Changes the workspace's name, locale and auto-resolve setting. Billing, the package and deleting the workspace are not available through the API. An inbox's working hours are changed with inboxes:write, not with this scope.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: workspace:read.

    Endpoints:

    • PATCH /v1/workspace: Update workspace settings

    Example:

    curl -X PATCH "https://api.clomni.ai/v1/workspace" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"auto_resolve_after": 1440}'
  4. 4

    Read plan and usage (billing:read)

    Reads the workspace's AI credit balance: the monthly credit, what is used and left, and the cost per feature. The catalogue also names the plan, usage and invoices, but today the only endpoint of this scope shows the AI credit.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/ai_credits: Get the AI credit balance

    Example:

    curl "https://api.clomni.ai/v1/ai_credits" \
  -H "Authorization: Bearer clomni_pat_xxx"
  5. 5

    Read the audit log (audit_logs:read)

    Reads the audit log: who changed what and when. Newest first, 15 entries per page. Used to copy the log into a security or compliance system.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/audit_logs: List audit log entries

    Example:

    curl "https://api.clomni.ai/v1/audit_logs?page=1" \
  -H "Authorization: Bearer clomni_pat_xxx"
  6. 6

    Read agents (agents:read)

    Reads the list of agents, their roles (administrator, agent) and availability. Needed to pick who to assign a conversation to and to show names in reports.

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/agents: List agents
    • GET /v1/assignable_agents: List agents who can be assigned

    Example:

    curl "https://api.clomni.ai/v1/agents" \
  -H "Authorization: Bearer clomni_pat_xxx"
  7. 7

    Manage agents (agents:manage)

    Invites an agent (an invitation email is sent), changes their role and availability, removes them from the workspace. Meant for keeping the agent list in step with an HR system. A wrong request can lock an agent out, so it is high risk.

    • Risk: high.
    • Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days.
    • Also grants: agents:read.

    Endpoints:

    • POST /v1/agents: Invite an agent
    • PATCH /v1/agents/{agent_id}: Change an agent's role or availability
    • DELETE /v1/agents/{agent_id}: Remove an agent from the workspace

    Example:

    curl -X POST "https://api.clomni.ai/v1/agents" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kamran Aliyev", "email": "[email protected]", "role": "agent"}'
  8. 8

    Read teams (teams:read)

    Reads teams and their members.

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/teams: List teams
    • GET /v1/teams/{team_id}: Get a team
    • GET /v1/teams/{team_id}/team_members: List team members

    Example:

    curl "https://api.clomni.ai/v1/teams" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/teams/3/team_members" \
  -H "Authorization: Bearer clomni_pat_xxx"
  9. 9

    Edit teams (teams:write)

    Creates, changes and deletes teams, adds and removes agents. PATCH /v1/teams/{team_id}/team_members replaces the members: only the users you send stay in the team.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: teams:read.

    Endpoints:

    • POST /v1/teams: Create a team
    • PATCH /v1/teams/{team_id}: Update a team
    • DELETE /v1/teams/{team_id}: Delete a team
    • POST /v1/teams/{team_id}/team_members: Add agents to a team
    • PATCH /v1/teams/{team_id}/team_members: Replace a team's members
    • DELETE /v1/teams/{team_id}/team_members: Remove agents from a team

    Example:

    curl -X POST "https://api.clomni.ai/v1/teams/3/team_members" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"user_ids": [12]}'
  10. 10

    Related articles

Document

Developer platform: guide v1.0 · 41 pages Open Download