ForSURE.categorylist.models.labels.endpoints

FastAPI endpoints for label operations.

GET /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/labels
async def get_labels()

Get labels for a revision.

This endpoint retrieves all labels (column definitions) for a specific revision. Labels define the structure and metadata of columns in the categorylist.

Parameters

revision_uuid UUID - UUID of the revision to get labels for.

Returns

LabelsResponse

Response containing:

  • labels list[CategoryLabel] - List of label objects defining columns
  • column_order dict - Column order configuration

Example

curl -X GET "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/labels" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

{
  "labels": [
    {
      "internal_name": "general:SKU",
      "customer_name": "SKU",
      "label_type": "GENERAL"
    }
  ],
  "column_order": {}
}

Error response If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to get labels"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Returns empty labels list if revision has no labels.

PUT /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/labels
async def update_labels()

Update labels for a revision.

This endpoint allows you to update the labels (column definitions) and column order for a specific revision. Labels define the structure and metadata of columns in the categorylist, including their types, names, and optional metadata like country, report type, and PRO.

Parameters

revision_uuid UUID - UUID of the revision to update labels for.

request LabelsUpdateRequest - Request object containing:

  • labels list[CategoryLabel] - List of label objects defining columns. Each label contains:
    • label_type LabelType - Type of label (GENERAL, COUNTRY, GENERAL_PACKAGING, UNMAPPED)
    • internal_name str - Internal column identifier (e.g., "general:SKU")
    • customer_name str - Display name for the column
    • country str, optional - Country code for country-specific labels
    • report_type str, optional - Report type (WEEE, Batteries, Packaging)
    • pro str, optional - Product Registration Organization identifier
    • unit str, optional - Unit of measurement
    • has_data bool, optional - Whether the categorylist has data for this label
  • column_order CategoryLabelOrder, optional - Column order configuration containing:
    • organization_column_order list[str] - Default column order for the organization
    • user_column_orders dict[str, list[str]] - User-specific column orders (userid -> column list)
    • allowed_column_order_types list[ColumnOrderType] - Allowed order types (ORGANIZATION, USER)

Returns

LabelsUpdateResponse

Response containing:

  • success bool - True if labels were updated successfully
  • labels_count int - Number of labels after update
  • message str - Success message

Example

curl -X PUT "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/labels" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "labels": [
    {
      "label_type": "GENERAL",
      "internal_name": "general:SKU",
      "customer_name": "SKU",
      "has_data": true
    },
    {
      "label_type": "GENERAL",
      "internal_name": "general:Product Name",
      "customer_name": "Product Name",
      "has_data": true
    }
  ],
  "column_order": {
    "organization_column_order": ["general:SKU", "general:Product Name"],
    "user_column_orders": {},
    "allowed_column_order_types": ["ORGANIZATION", "USER"]
  }
}'

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

{
  "success": true,
  "labels_count": 2,
  "message": "Labels updated successfully"
}

Error response If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to update labels"
}

Or if there's a validation error:

{
  "detail": "Error message describing the validation issue"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. The labels list completely replaces the existing labels for the revision. If column_order is not provided, the existing column order configuration is preserved. Labels must be valid and match the expected structure for the revision's version.

GET /saas/categorylist/labels/options
async def get_label_options()

Get all possible label options.

This endpoint retrieves all available label/column options that can be used when creating or updating labels. The options are based on the selected PROs (Product Registration Organizations) for the current user.

Returns

list[Column]

List of available column/label options that can be used.

Example

curl -X GET "https://api.example.com/saas/categorylist/labels/options" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

Successful response If the request was successful you should receive the status code 200 and a response body like this:

[
  {
    "name": "general:SKU",
    "display_name": "SKU",
    "type": "string"
  }
]

Error response If the request failed you might receive status code 400, 401, 403, or 500 with a response body like this:

{
  "detail": "Failed to get label options"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Options are based on selected PROs.