ForSURE.categorylist.models.version.endpoints

List versions for an organization with pagination.

This endpoint retrieves a paginated list of all categorylist versions for the current organization. Each version can contain multiple revisions.

Parameters

offset int, default 0 - Number of versions to skip for pagination.

limit int, optional - Maximum number of versions to return.

Returns

PaginatedResponse[CategorylistVersionResponse]

Paginated response containing:

• items list[CategorylistVersionResponse] - List of version objects
• total int - Total number of versions
• next_offset int, optional - Offset for next page
• prev_offset int, optional - Offset for previous page

Example

curl -X GET "https://api.example.com/saas/categorylist/versions?offset=0&limit=20" \
-H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
  "items": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Version 1",
      "number": 1,
      "latest_revision": 3,
      "has_draft": true
    }
  ],
  "total": 10,
  "next_offset": 20,
  "prev_offset": null
}

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

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Versions are filtered by organization.

Get a version by UUID.

This endpoint retrieves a complete version object including its metadata and associated revisions.

Parameters

version_uuid UUID - UUID of the version to retrieve.

Returns

CategorylistVersion

Complete version object containing:

• uuid UUID - Version UUID
• name str - Version name
• number int - Version number
• created_at datetime - Creation timestamp
• created_by str - Creator username
• updated_at datetime - Last update timestamp
• updated_by str - Last updater username
• validFrom date, optional - Start date for validity period
• validTo date, optional - End date for validity period

Example

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

Response Example

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Version 1",
  "number": 1,
  "created_at": "2024-01-15T10:30:00Z",
  "created_by": "user1"
}

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

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Version must be accessible by the user.

Create a new version with initial draft revision.

This endpoint creates a new categorylist version with an initial draft revision. The version is created for the current organization.

Parameters

version VersionCreateRequest - Request object containing:

• version_name str - Name for the new version

Returns

VersionCreateResponse

Response containing:

• uuid UUID - Version UUID
• name str - Version name
• number int - Version number
• created_at datetime - Creation timestamp
• created_by str - Creator username
• updated_at datetime - Last update timestamp
• updated_by str - Last updater username
• revisions list[CategorylistRevision] - List of revisions (includes initial draft)

Example

curl -X POST "https://api.example.com/saas/categorylist/versions" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "version_name": "Version 2.0"
}'

Response Example

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Version 2.0",
  "number": 2,
  "revisions": [{"uuid": "...", "number": 1, "is_draft": true}]
}

{
  "detail": "Failed to create version"
}

Note

Requires CATEGORYLIST_ADMIN permission. Creates an initial draft revision automatically.

Update a version (currently supports renaming).

This endpoint updates a version's properties. Currently, only renaming is supported.

Parameters

version_uuid UUID - UUID of the version to update.

name str, optional - New name for the version.

Returns

CategorylistVersion

Updated version object containing:

• uuid UUID - Version UUID
• name str - Updated version name
• number int - Version number
• created_at datetime - Creation timestamp
• created_by str - Creator username
• updated_at datetime - Last update timestamp
• updated_by str - Last updater username

Example

curl -X PUT "https://api.example.com/saas/categorylist/versions/123e4567-e89b-12d3-a456-426614174000" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "name=Updated Version Name"

Response Example

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Updated Version Name",
  "number": 1
}

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

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Version must exist and be accessible.

Clone a version from an existing version and revision.

This endpoint creates a new version by cloning an existing version from a specific revision. The new version includes all items and data from the source revision.

Parameters

from_version_uuid UUID - UUID of the source version to clone from.

from_revision int - Revision number to clone from.

new_version_name str - Name for the new cloned version.

Returns

VersionCreateResponse

Response containing:

• uuid UUID - New version UUID
• name str - New version name
• number int - New version number
• created_at datetime - Creation timestamp
• created_by str - Creator username
• updated_at datetime - Last update timestamp
• updated_by str - Last updater username
• revisions list[CategorylistRevision] - List of revisions (includes cloned revision)

Example

curl -X POST "https://api.example.com/saas/categorylist/versions2/clone" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "from_version_uuid=123e4567-e89b-12d3-a456-426614174000" \
-F "from_revision=3" \
-F "new_version_name=Cloned Version"

Response Example

{
  "uuid": "789e0123-e89b-12d3-a456-426614174002",
  "name": "Cloned Version",
  "number": 3,
  "revisions": [{"uuid": "...", "number": 1, "is_draft": true}]
}

{
  "detail": "Failed to clone version (v2)"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Source version and revision must exist. Creates a new version with a draft revision containing cloned data.