CallaboDevelopersBeta
Docs menu

REST API

Roles

Read workspace and team roles with their permissions.

GET/v2/workspaces/{slug}/workspace-roles

Search Workspace role list

List workspace roles and the member count for each role with pagination.

Parameters

  • slugRequiredstringpath
    Workspace slug
  • offsetintegerqueryDefault 0
    Zero-based offset of the first returned item.
  • limitintegerqueryDefault 100
    Maximum number of items returned.

Request example

curl --request GET \
  --url "https://api.callabo.ai/v2/workspaces/your-workspace/workspace-roles" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $CALLABO_PAT"

Success responses

Response body

  • itemsRequiredV2WorkspaceRole[]
    Custom workspace roles.
  • idRequiredinteger
    Custom workspace role identifier.
  • nameRequiredstring
    Custom workspace role name.
  • descriptionstring | null
    Custom workspace role description.
  • is_system_roleRequiredboolean
    Whether the role is managed by the system.
  • member_countRequiredinteger
    Number of members assigned to the role.
  • created_atRequiredstring (date-time)
    Date and time when the role was created.
  • updated_atRequiredstring (date-time)
    Date and time when the role was last updated.
  • permissionsRequiredV2Permission[]
    Permissions assigned to the custom workspace role.
  • pageRequiredV2Pagination
    Custom workspace role pagination information.
  • offsetRequiredinteger
    Zero-based offset of the first returned item.
  • limitRequiredinteger
    Requested maximum number of items.
  • totalRequiredinteger
    Total number of matching items.

Response example

{
  "items": [
    {
      "id": 1,
      "name": "Example",
      "is_system_role": true,
      "member_count": 1,
      "created_at": "2026-08-27T03:00:00Z",
      "updated_at": "2026-08-27T03:00:00Z",
      "permissions": [
        {
          "resource": "member_management",
          "effect": "allow"
        }
      ]
    }
  ],
  "page": {
    "offset": 1,
    "limit": 1,
    "total": 1
  }
}

Errors

StatusError codeDescription
401UNAUTHORIZEDUnauthenticated request
403FORBIDDENInsufficient requester permissions
404WORKSPACE_NOT_FOUNDNot found
422VALIDATION_ERRORUnprocessable content
429RATE_LIMIT_EXCEEDEDRequest limit exceededLearn more
GET/v2/workspaces/{slug}/workspace-roles/{role_id}

Workspace role details inquiry

Retrieve workspace role permissions and the number of assigned members.

Parameters

  • role_idRequiredintegerpath
    Role ID.
  • slugRequiredstringpath
    Workspace slug

Request example

curl --request GET \
  --url "https://api.callabo.ai/v2/workspaces/your-workspace/workspace-roles/1" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $CALLABO_PAT"

Success responses

Response body

  • idRequiredinteger
    Custom workspace role identifier.
  • nameRequiredstring
    Custom workspace role name.
  • descriptionstring | null
    Custom workspace role description.
  • is_system_roleRequiredboolean
    Whether the role is managed by the system.
  • member_countRequiredinteger
    Number of members assigned to the role.
  • created_atRequiredstring (date-time)
    Date and time when the role was created.
  • updated_atRequiredstring (date-time)
    Date and time when the role was last updated.
  • permissionsRequiredV2Permission[]
    Permissions assigned to the custom workspace role.
  • resourceRequiredPermissionResource
    Resource to which the permission applies.
  • effectRequiredPermissionStatus
    Allow or deny status to apply to the resource.

Response example

{
  "id": 1,
  "name": "Example",
  "is_system_role": true,
  "member_count": 1,
  "created_at": "2026-08-27T03:00:00Z",
  "updated_at": "2026-08-27T03:00:00Z",
  "permissions": [
    {
      "resource": "member_management",
      "effect": "allow"
    }
  ]
}

Errors

StatusError codeDescription
401UNAUTHORIZEDUnauthenticated request
403FORBIDDENInsufficient requester permissions
404WORKSPACE_NOT_FOUND, WORKSPACE_ROLE_NOT_FOUNDNot found
422VALIDATION_ERRORUnprocessable content
429RATE_LIMIT_EXCEEDEDRequest limit exceededLearn more
GET/v2/workspaces/{slug}/team-roles

Team role list search

List team roles and permissions with pagination.

Parameters

  • slugRequiredstringpath
    Workspace slug
  • offsetintegerqueryDefault 0
    Zero-based offset of the first returned item.
  • limitintegerqueryDefault 100
    Maximum number of items returned.

Request example

curl --request GET \
  --url "https://api.callabo.ai/v2/workspaces/your-workspace/team-roles" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $CALLABO_PAT"

Success responses

Response body

  • itemsRequiredV2TeamRole[]
    Custom team roles.
  • idRequiredinteger
    Custom team role identifier.
  • nameRequiredstring
    Custom team role name.
  • descriptionstring | null
    Custom team role description.
  • is_system_roleRequiredboolean
    Whether the role is managed by the system.
  • permissionsRequiredV2Permission[]
    Permissions assigned to the custom team role.
  • pageRequiredV2Pagination
    Custom team role pagination information.
  • offsetRequiredinteger
    Zero-based offset of the first returned item.
  • limitRequiredinteger
    Requested maximum number of items.
  • totalRequiredinteger
    Total number of matching items.

Response example

{
  "items": [
    {
      "id": 1,
      "name": "Example",
      "is_system_role": true,
      "permissions": [
        {
          "resource": "member_management",
          "effect": "allow"
        }
      ]
    }
  ],
  "page": {
    "offset": 1,
    "limit": 1,
    "total": 1
  }
}

Errors

StatusError codeDescription
401UNAUTHORIZEDUnauthenticated request
403FORBIDDENInsufficient requester permissions
404WORKSPACE_NOT_FOUNDNot found
422VALIDATION_ERRORUnprocessable content
429RATE_LIMIT_EXCEEDEDRequest limit exceededLearn more
GET/v2/workspaces/{slug}/team-roles/{role_id}

Team role details inquiry

Retrieve team role details and permissions.

Parameters

  • role_idRequiredintegerpath
    Role ID.
  • slugRequiredstringpath
    Workspace slug

Request example

curl --request GET \
  --url "https://api.callabo.ai/v2/workspaces/your-workspace/team-roles/1" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer $CALLABO_PAT"

Success responses

Response body

  • idRequiredinteger
    Custom team role identifier.
  • nameRequiredstring
    Custom team role name.
  • descriptionstring | null
    Custom team role description.
  • is_system_roleRequiredboolean
    Whether the role is managed by the system.
  • permissionsRequiredV2Permission[]
    Permissions assigned to the custom team role.
  • resourceRequiredPermissionResource
    Resource to which the permission applies.
  • effectRequiredPermissionStatus
    Allow or deny status to apply to the resource.

Response example

{
  "id": 1,
  "name": "Example",
  "is_system_role": true,
  "permissions": [
    {
      "resource": "member_management",
      "effect": "allow"
    }
  ]
}

Errors

StatusError codeDescription
401UNAUTHORIZEDUnauthenticated request
403FORBIDDENInsufficient requester permissions
404WORKSPACE_NOT_FOUND, TEAM_ROLE_NOT_FOUNDNot found
422VALIDATION_ERRORUnprocessable content
429RATE_LIMIT_EXCEEDEDRequest limit exceededLearn more
© 2026 Return Zero, Inc.