Teams¶

Teams group agents together for organized ticket routing and collaboration. Tickets can be assigned to teams, and team members can work on assigned tickets.

Endpoints¶

Method	Endpoint	Description	Scope Required
GET	`/v1/teams`	List teams	`teams:read`
GET	`/v1/teams/{id}`	Get team	`teams:read`
POST	`/v1/teams`	Create team	`teams:write`
PATCH	`/v1/teams/{id}`	Update team	`teams:write`
DELETE	`/v1/teams/{id}`	Delete team	`teams:delete`
POST	`/v1/teams/{id}/members`	Add member	`teams:write`
DELETE	`/v1/teams/{id}/members/{user_id}`	Remove member	`teams:write`

The Team Object¶

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Technical Support",
  "description": "Handles technical issues and bug reports",
  "members": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "agent1@company.com",
      "full_name": "Alice Johnson"
    },
    {
      "id": "234f5678-e90c-12d3-b456-526714174111",
      "email": "agent2@company.com",
      "full_name": "Bob Smith"
    }
  ],
  "created_at": "2025-01-05T08:00:00Z",
  "updated_at": "2025-01-10T14:30:00Z"
}

Attributes¶

Field	Type	Description
`id`	UUID	Unique team identifier
`name`	string	Team name
`description`	string	Team description
`members`	array	List of team members
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last modification timestamp

List Teams¶

Retrieve a paginated list of teams.

GET /v1/teams

Query Parameters¶

Parameter	Type	Default	Description
`skip`	integer	0	Number of records to skip
`limit`	integer	50	Maximum records to return (max: 100)

Examples¶

cURLPython

curl -X GET "https://api.toptickets.app/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.toptickets.app/v1/teams",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

Response¶

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Technical Support",
    "description": "Handles technical issues",
    "created_at": "2025-01-05T08:00:00Z"
  },
  {
    "id": "661f9511-f30c-52e5-b827-557766551111",
    "name": "Billing Support",
    "description": "Handles billing inquiries",
    "created_at": "2025-01-05T09:00:00Z"
  }
]

Get Team¶

Retrieve a team with its members.

GET /v1/teams/{team_id}

Path Parameters¶

Parameter	Type	Description
`team_id`	UUID	The team ID

Examples¶

cURLPython

curl -X GET "https://api.toptickets.app/v1/teams/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

TEAM_ID = "550e8400-e29b-41d4-a716-446655440000"

response = requests.get(
    f"https://api.toptickets.app/v1/teams/{TEAM_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

Response¶

Returns the full team object including members.

Create Team¶

Create a new team.

POST /v1/teams

Request Body¶

Field	Type	Required	Description
`name`	string	Yes	Team name (max 255 chars)
`description`	string	No	Team description

Examples¶

cURLPython

curl -X POST "https://api.toptickets.app/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Technical Support",
    "description": "Handles technical issues and bug reports"
  }'

import requests

response = requests.post(
    "https://api.toptickets.app/v1/teams",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "name": "Technical Support",
        "description": "Handles technical issues and bug reports"
    }
)

Response (201 Created)¶

Returns the created team object.

Update Team¶

Update an existing team.

PATCH /v1/teams/{team_id}

Path Parameters¶

Parameter	Type	Description
`team_id`	UUID	The team ID

Request Body¶

Field	Type	Description
`name`	string	Updated team name
`description`	string	Updated description

Examples¶

cURLPython

curl -X PATCH "https://api.toptickets.app/v1/teams/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for the team"
  }'

import requests

TEAM_ID = "550e8400-e29b-41d4-a716-446655440000"

response = requests.patch(
    f"https://api.toptickets.app/v1/teams/{TEAM_ID}",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "description": "Updated description for the team"
    }
)

Response¶

Returns the updated team object.

Delete Team¶

Delete a team.

DELETE /v1/teams/{team_id}

Path Parameters¶

Parameter	Type	Description
`team_id`	UUID	The team ID

Examples¶

cURLPython

curl -X DELETE "https://api.toptickets.app/v1/teams/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

TEAM_ID = "550e8400-e29b-41d4-a716-446655440000"

response = requests.delete(
    f"https://api.toptickets.app/v1/teams/{TEAM_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if response.status_code == 204:
    print("Team deleted")

Response¶

Returns 204 No Content on success.

Team Assignments

Deleting a team will unassign all tickets currently assigned to that team.

Add Team Member¶

Add a user to a team.

POST /v1/teams/{team_id}/members

Path Parameters¶

Parameter	Type	Description
`team_id`	UUID	The team ID

Request Body¶

Field	Type	Required	Description
`user_id`	UUID	Yes	ID of the user to add

Examples¶

cURLPython

curl -X POST "https://api.toptickets.app/v1/teams/550e8400-e29b-41d4-a716-446655440000/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123e4567-e89b-12d3-a456-426614174000"
  }'

import requests

TEAM_ID = "550e8400-e29b-41d4-a716-446655440000"
USER_ID = "123e4567-e89b-12d3-a456-426614174000"

response = requests.post(
    f"https://api.toptickets.app/v1/teams/{TEAM_ID}/members",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={"user_id": USER_ID}
)

Response¶

{
  "message": "User added to team successfully"
}

Remove Team Member¶

Remove a user from a team.

DELETE /v1/teams/{team_id}/members/{user_id}

Path Parameters¶

Parameter	Type	Description
`team_id`	UUID	The team ID
`user_id`	UUID	The user ID to remove

Examples¶

cURLPython

curl -X DELETE "https://api.toptickets.app/v1/teams/550e8400-e29b-41d4-a716-446655440000/members/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

TEAM_ID = "550e8400-e29b-41d4-a716-446655440000"
USER_ID = "123e4567-e89b-12d3-a456-426614174000"

response = requests.delete(
    f"https://api.toptickets.app/v1/teams/{TEAM_ID}/members/{USER_ID}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

if response.status_code == 204:
    print("Member removed from team")

Response¶

Returns 204 No Content on success.