Skip to main content

Labels & Organization

Endpoints for managing labels and organizing work items and flows.

Label Management​

GET /api/labels​

Gets labels with filtering and pagination.

Query Parameters:

  • projectId: Filter by project
  • search: Search by name
  • limit: Maximum labels to return (default: 50)
  • offset: Number of labels to skip (default: 0)

Response:

{
  "labels": [
    {
      "id": "label-123",
      "name": "login",
      "color": "#FF6B6B",
      "description": "Login-related test cases",
      "projectId": "project-456",
      "usageCount": 15,
      "createdAt": "2024-01-01T00:00:00.000Z"
    },
    {
      "id": "label-456",
      "name": "regression",
      "color": "#4ECDC4",
      "description": "Regression test suite",
      "projectId": "project-456",
      "usageCount": 8
    }
  ],
  "total": 2
}

GET /api/labels/names​

Gets label names for autocomplete/suggestions.

Query Parameters:

  • projectId: Filter by project
  • prefix: Filter names starting with prefix

Response:

{
  "labels": [
    "login",
    "regression",
    "smoke-test",
    "performance",
    "integration"
  ]
}

GET /api/labels/stats​

Gets label usage statistics.

Query Parameters:

  • projectId: Filter by project

Response:

{
  "totalLabels": 25,
  "mostUsed": [
    {
      "labelId": "label-123",
      "name": "login",
      "usageCount": 45,
      "usagePercentage": 18.5
    }
  ],
  "usageByProject": {
    "project-456": {
      "totalLabels": 15,
      "totalUsage": 120
    }
  },
  "recentlyCreated": [
    {
      "labelId": "label-789",
      "name": "new-feature",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}

GET /api/labels/usage/:labelId?​

Gets detailed usage statistics for a label.

Parameters:

  • labelId: Label identifier (optional - if not provided, returns usage for all labels)

Response:

{
  "labelId": "label-123",
  "name": "login",
  "usage": {
    "flows": 12,
    "workItems": 33,
    "total": 45
  },
  "usageOverTime": [
    {
      "date": "2024-01-01",
      "flows": 2,
      "workItems": 5
    }
  ],
  "associatedProjects": [
    {
      "projectId": "project-456",
      "projectName": "Mobile Testing",
      "usageCount": 28
    }
  ]
}

Label Synchronization​

POST /api/labels/fetch/:projectId​

Fetches labels from external project management tool.

Parameters:

  • projectId: Project identifier

Request Body:

{
  "forceSync": false,
  "updateExisting": true
}

Response:

{
  "success": true,
  "fetched": 15,
  "created": 8,
  "updated": 5,
  "skipped": 2,
  "syncId": "sync-labels-789"
}

POST /api/labels/sync/:integrationId​

Syncs labels for a specific integration.

Parameters:

  • integrationId: Integration identifier

Request Body:

{
  "projectIds": ["project-123", "project-456"],
  "syncOptions": {
    "createMissing": true,
    "updateExisting": true,
    "removeOrphaned": false
  }
}

Response:

{
  "success": true,
  "projectsProcessed": 2,
  "labelsSynced": 25,
  "errors": []
}

Label CRUD Operations​

POST /api/labels​

Creates a new label.

Request Body:

{
  "name": "performance-test",
  "color": "#9B59B6",
  "description": "Performance testing scenarios",
  "projectId": "project-456"
}

Response:

{
  "success": true,
  "label": {
    "id": "label-789",
    "name": "performance-test",
    "color": "#9B59B6",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

PUT /api/labels/:labelId​

Updates a label.

Parameters:

  • labelId: Label identifier

Request Body:

{
  "name": "performance-testing",
  "color": "#8E44AD",
  "description": "Updated description for performance tests"
}

DELETE /api/labels/:labelId​

Deletes a label.

Parameters:

  • labelId: Label identifier

Response:

{
  "success": true,
  "deleted": "label-789",
  "affectedItems": {
    "flows": 5,
    "workItems": 12
  }
}

Organization Features​

Label Colors​

Predefined color palette for consistent labeling:

  • Red: #FF6B6B (urgent, critical)
  • Orange: #FFA726 (high priority)
  • Yellow: #FFEB3B (medium priority)
  • Green: #4CAF50 (completed, success)
  • Blue: #2196F3 (info, default)
  • Purple: #9C27B0 (feature, enhancement)
  • Pink: #E91E63 (bug, issue)
  • Teal: #009688 (testing, qa)

Best Practices​

Label Naming​

  • Use kebab-case for multi-word labels: login-flow, performance-test
  • Keep names concise but descriptive
  • Use consistent prefixes for related labels: auth-*, ui-*, api-*

Label Usage​

  • Limit to 5-10 labels per item for clarity
  • Use colors consistently across projects
  • Regularly review and clean up unused labels
  • Document label meanings in project wiki

Organization Strategy​

  • Create project-specific label sets
  • Use labels for categorization AND priority
  • Implement label workflows (e.g., ready-for-review → in-review → approved)
  • Use automation to apply labels based on rules