Teams

Teams are the organizational backbone of ticket routing in the ITSM platform. Each team groups agents by function or expertise area — Network Operations, Desktop Support, Security, and so on. When AI triage classifies an incoming ticket, it routes it to the appropriate team based on category and specialization. Teams support configurable queue strategies that determine how tickets are distributed among members.

The team model

The team model contains all the information about a support team, including its members, queue distribution strategy, and areas of specialization.

Properties

Name
id
Type
string
Description
Unique identifier for the team (UUID).
Name
name
Type
string
Description
The display name of the team.
Name
description
Type
string
Description
A description of the team's purpose and responsibilities.
Name
lead_id
Type
string
Description
The UUID of the user designated as the team lead.
Name
members
Type
array
Description
An array of user objects that are members of the team.
Name
queue_strategy
Type
string
Description
The strategy used for distributing tickets among team members. One of round_robin, least_busy, or skill_based.
Name
specializations
Type
array
Description
An array of strings representing the team's areas of expertise (e.g., ["VPN", "Firewall", "DNS"]). Used by AI triage for routing decisions.
Name
created_at
Type
timestamp
Description
Timestamp of when the team was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the team was last updated.
Name
organization_id
Type
string
Description
The tenant ID that the team belongs to.

Queue strategies

Strategy	Description
`round_robin`	Tickets are assigned to team members in a rotating sequence, ensuring even distribution regardless of current workload.
`least_busy`	Tickets are assigned to the team member with the fewest open tickets, balancing active workload in real time.
`skill_based`	Tickets are matched to team members based on their individual skill tags and the ticket's category/subcategory.

GET/v1/teams

List all teams

This endpoint allows you to retrieve a paginated list of all teams in your organization. By default, a maximum of twenty teams are shown per page.

Optional attributes

Name
search
Type
string
Description
Search teams by name (case-insensitive partial match).
Name
page
Type
integer
Description
The page number for pagination. Defaults to 1.
Name
limit
Type
integer
Description
Limit the number of teams returned per page. Defaults to 20.

Request

GET

/v1/teams

curl -G http://localhost:3000/v1/teams \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

{
  "success": true,
  "data": [
    {
      "id": "team_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Network Operations",
      "description": "Handles all network infrastructure incidents including VPN, DNS, firewall, and WAN/LAN issues.",
      "lead_id": "usr_f6e5d4c3-b2a1-0987-fedc-ba9876543210",
      "queue_strategy": "least_busy",
      "specializations": ["VPN", "Firewall", "DNS", "WAN", "LAN"],
      "member_count": 8,
      "open_tickets": 23,
      "created_at": 1708783200,
      "updated_at": 1708784100,
      "organization_id": "org_9f8e7d6c5b4a"
    },
    {
      "id": "team_b2c3d4e5-f6a7-8901-bcde-f12345678901"
      // ...
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 6,
      "totalPages": 1,
      "hasMore": false
    }
  }
}

POST/v1/teams

Create a team

This endpoint allows you to create a new team. You must provide a team name at minimum. The queue strategy defaults to round_robin if not specified. Specializations can be added at creation time or later via an update.

Required attributes

Name
name
Type
string
Description
The display name for the team. Must be unique within the organization.

Optional attributes

Name
description
Type
string
Description
A description of the team's purpose and responsibilities.
Name
lead_id
Type
string
Description
The UUID of the user to designate as team lead.
Name
queue_strategy
Type
string
Description
The ticket distribution strategy. One of round_robin, least_busy, or skill_based. Defaults to round_robin.
Name
specializations
Type
array
Description
An array of strings representing the team's areas of expertise.

Request

POST

/v1/teams

curl http://localhost:3000/v1/teams \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Security Operations",
    "description": "Handles security incidents, vulnerability management, and access control issues.",
    "lead_id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "queue_strategy": "skill_based",
    "specializations": ["IAM", "Vulnerability", "Malware", "DLP", "SIEM"]
  }'

Response

{
  "success": true,
  "data": {
    "id": "team_c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "Security Operations",
    "description": "Handles security incidents, vulnerability management, and access control issues.",
    "lead_id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "members": [],
    "queue_strategy": "skill_based",
    "specializations": ["IAM", "Vulnerability", "Malware", "DLP", "SIEM"],
    "created_at": 1708790400,
    "updated_at": 1708790400,
    "organization_id": "org_9f8e7d6c5b4a"
  }
}

GET/v1/teams/:id

Retrieve a team

This endpoint allows you to retrieve a team by providing its UUID. The response includes the full list of team members with their profile summaries. Refer to the list at the top of this page to see which properties are included with team objects.

Request

GET

/v1/teams/team_a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl http://localhost:3000/v1/teams/team_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "id": "team_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Network Operations",
    "description": "Handles all network infrastructure incidents including VPN, DNS, firewall, and WAN/LAN issues.",
    "lead_id": "usr_f6e5d4c3-b2a1-0987-fedc-ba9876543210",
    "members": [
      {
        "id": "usr_f6e5d4c3-b2a1-0987-fedc-ba9876543210",
        "name": "Alex Rivera",
        "email": "arivera@acme.com",
        "role": "agent",
        "avatar_url": "https://cdn.example.com/avatars/arivera.jpg",
        "status": "active"
      },
      {
        "id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Jessica Chen",
        "email": "jchen@acme.com",
        "role": "agent",
        "avatar_url": "https://cdn.example.com/avatars/jchen.jpg",
        "status": "active"
      }
    ],
    "queue_strategy": "least_busy",
    "specializations": ["VPN", "Firewall", "DNS", "WAN", "LAN"],
    "created_at": 1708783200,
    "updated_at": 1708784100,
    "organization_id": "org_9f8e7d6c5b4a"
  }
}

PATCH/v1/teams/:id

Update a team

This endpoint allows you to perform a partial update on a team. You can update the name, description, lead, queue strategy, and specializations. To modify team membership, use the dedicated add member and remove member endpoints.

Optional attributes

Name
name
Type
string
Description
Update the team name.
Name
description
Type
string
Description
Update the team description.
Name
lead_id
Type
string
Description
Change the team lead.
Name
queue_strategy
Type
string
Description
Change the ticket distribution strategy.
Name
specializations
Type
array
Description
Replace the team's specialization tags.

Request

PATCH

/v1/teams/team_a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl -X PATCH http://localhost:3000/v1/teams/team_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "queue_strategy": "skill_based",
    "specializations": ["VPN", "Firewall", "DNS", "WAN", "LAN", "SD-WAN"]
  }'

Response

{
  "success": true,
  "data": {
    "id": "team_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Network Operations",
    "description": "Handles all network infrastructure incidents including VPN, DNS, firewall, and WAN/LAN issues.",
    "lead_id": "usr_f6e5d4c3-b2a1-0987-fedc-ba9876543210",
    "members": [
      {
        "id": "usr_f6e5d4c3-b2a1-0987-fedc-ba9876543210",
        "name": "Alex Rivera",
        "email": "arivera@acme.com",
        "role": "agent",
        "status": "active"
      }
    ],
    "queue_strategy": "skill_based",
    "specializations": ["VPN", "Firewall", "DNS", "WAN", "LAN", "SD-WAN"],
    "created_at": 1708783200,
    "updated_at": 1708790500,
    "organization_id": "org_9f8e7d6c5b4a"
  }
}

DELETE/v1/teams/:id

Delete a team

This endpoint allows you to delete a team. Before deletion, all tickets currently assigned to this team must be reassigned to another team. Deleting a team removes all member associations but does not delete the member user accounts. This action is permanent and cannot be undone.

Request

DELETE

/v1/teams/team_c3d4e5f6-a7b8-9012-cdef-123456789012

curl -X DELETE http://localhost:3000/v1/teams/team_c3d4e5f6-a7b8-9012-cdef-123456789012 \
  -H "Authorization: Bearer {token}"

POST/v1/teams/:id/members

Add team member

This endpoint allows you to add a user to a team. The user must exist in the same organization and have an active status. A user can belong to multiple teams simultaneously.

Required attributes

Name
user_id
Type
string
Description
The UUID of the user to add to the team.

Optional attributes

Name
role
Type
string
Description
The member's role within the team. One of member or lead. Defaults to member.
Name
skills
Type
array
Description
An array of skill tags for skill-based routing (e.g., ["VPN", "Cisco"]).

Request

POST

/v1/teams/team_a1b2c3d4-e5f6-7890-abcd-ef1234567890/members

curl http://localhost:3000/v1/teams/team_a1b2c3d4-e5f6-7890-abcd-ef1234567890/members \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_d4e5f6a7-b890-1234-abcd-ef5678901234",
    "skills": ["VPN", "Cisco", "Palo Alto"]
  }'

Response

{
  "success": true,
  "data": {
    "team_id": "team_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user_id": "usr_d4e5f6a7-b890-1234-abcd-ef5678901234",
    "name": "Sam Patel",
    "email": "spatel@acme.com",
    "role": "member",
    "skills": ["VPN", "Cisco", "Palo Alto"],
    "added_at": 1708790400
  }
}

DELETE/v1/teams/:id/members/:userId

Remove team member

This endpoint allows you to remove a user from a team. If the user has tickets assigned to them through this team, those tickets will remain assigned but the user will no longer receive new tickets via the team's queue strategy. The team lead cannot be removed without first designating a new lead.

Request

DELETE

/v1/teams/team_a1b2c3d4-e5f6-7890-abcd-ef1234567890/members/usr_d4e5f6a7-b890-1234-abcd-ef5678901234

curl -X DELETE http://localhost:3000/v1/teams/team_a1b2c3d4-e5f6-7890-abcd-ef1234567890/members/usr_d4e5f6a7-b890-1234-abcd-ef5678901234 \
  -H "Authorization: Bearer {token}"

GET/v1/teams/:id/workload

Get team workload

This endpoint returns the current workload distribution for a team. It shows each member's open ticket count, average resolution time, and availability status. This data is used by the least_busy and skill_based queue strategies to make routing decisions and is useful for managers monitoring team capacity.

Request

GET

/v1/teams/team_a1b2c3d4-e5f6-7890-abcd-ef1234567890/workload

curl http://localhost:3000/v1/teams/team_a1b2c3d4-e5f6-7890-abcd-ef1234567890/workload \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "data": {
    "team_id": "team_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "team_name": "Network Operations",
    "queue_strategy": "least_busy",
    "total_open_tickets": 23,
    "total_members": 8,
    "avg_tickets_per_member": 2.9,
    "members": [
      {
        "user_id": "usr_f6e5d4c3-b2a1-0987-fedc-ba9876543210",
        "name": "Alex Rivera",
        "open_tickets": 5,
        "in_progress_tickets": 3,
        "avg_resolution_hours": 4.2,
        "status": "active",
        "skills": ["VPN", "Firewall", "Cisco"]
      },
      {
        "user_id": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Jessica Chen",
        "open_tickets": 2,
        "in_progress_tickets": 1,
        "avg_resolution_hours": 3.8,
        "status": "active",
        "skills": ["DNS", "WAN", "LAN"]
      }
    ],
    "sla_compliance_rate": 0.91,
    "queried_at": 1708790400
  }
}