Labels

Retrieve task labels for a task board. Labels help categorize and filter tasks.

Endpoint

Method	Endpoint	Description
GET	/tasks/v1/taskboards/{taskBoardId}/labels	Get task labels

Path Parameters

Parameter	Type	Required	Description
taskBoardId	string	Yes	Task board ID

Query Parameters

Parameter	Type	Required	Default	Description
title	string	No	-	Filter by label name
limit	integer	No	10	Results per page (1-100)
offset	integer	No	0	Pagination offset

Example Request

curl --request GET \
  --url 'https://api.connecteam.com/tasks/v1/taskboards/12345/labels?limit=100' \
  --header 'X-API-KEY: YOUR_API_KEY'

Response

{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "labels": [
      {
        "id": "label-abc123",
        "name": "Urgent",
        "color": "#FF0000"
      },
      {
        "id": "label-def456",
        "name": "Maintenance",
        "color": "#00FF00"
      },
      {
        "id": "label-ghi789",
        "name": "Training",
        "color": "#0000FF"
      }
    ]
  },
  "paging": {
    "offset": 3
  }
}

Response Fields

Field	Type	Description
id	string	Unique label identifier
name	string	Display name
color	string	Hex color code

Using Labels

Get All Labels for a Board

async function getAllLabels(taskBoardId) {
  const labels = [];
  let offset = 0;
  const limit = 100;

  while (true) {
    const response = await fetch(
      `https://api.connecteam.com/tasks/v1/taskboards/${taskBoardId}/labels?limit=${limit}&offset=${offset}`,
      { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
    );
    const data = await response.json();
    
    labels.push(...data.data.labels);
    
    if (data.data.labels.length < limit) break;
    offset = data.paging.offset;
  }

  return labels;
}

Build Label Mapping

const labels = await getAllLabels(12345);

// Map label names to IDs
const labelMap = {};
labels.forEach(label => {
  labelMap[label.name] = label.id;
});

// Use when creating tasks
await createTask({
  title: 'Urgent maintenance required',
  userIds: [9170357],
  status: 'published',
  labelIds: [labelMap['Urgent'], labelMap['Maintenance']]
});

Filter Tasks by Label

// Get tasks with specific labels
const urgentTasks = await fetch(
  `https://api.connecteam.com/tasks/v1/taskboards/12345/tasks?labelIds=${labelMap['Urgent']}`,
  { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
);

API Reference