ForSURE.categorylist.models.revision.endpoints

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

Get a revision by UUID.

This endpoint retrieves a complete revision object including its metadata, labels, and associated data.

Parameters

revision_uuid UUID - UUID of the revision to retrieve.

Returns

CategorylistRevision

Complete revision object containing:

  • uuid UUID - Revision UUID
  • number int - Revision number
  • name str - Revision name
  • is_draft bool - Whether this is a draft revision
  • labels CategoryLabelsData - Labels/columns for this revision
  • version_uuid UUID - UUID of the parent version

Example

curl -X GET "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000" \
-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:

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "number": 1,
  "name": "Revision 1",
  "is_draft": true,
  "labels": {"labels": [], "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 revision"
}

Note

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

GET /saas/categorylist/versions/123e4567-e89b-12d3-a456-426614174000/revisions?offset=0&limit=20
async def list_revisions()

List revisions for a version with pagination.

This endpoint retrieves a paginated list of all revisions for a specific version. Revisions are returned in order with their metadata.

Parameters

version_uuid UUID - UUID of the version to list revisions for.

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

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

Returns

list[RevisionResponse]

List of revision objects containing:

  • uuid UUID - Revision UUID
  • number int - Revision number
  • name str - Revision name
  • is_draft bool - Whether this is a draft revision
  • approved_at datetime, optional - When the revision was approved/published

Example

curl -X GET "https://api.example.com/saas/categorylist/versions/123e4567-e89b-12d3-a456-426614174000/revisions?offset=0&limit=20" \
-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:

[
  {
    "uuid": "456e7890-e89b-12d3-a456-426614174001",
    "number": 1,
    "name": "Revision 1",
    "is_draft": false,
    "approved_at": "2024-01-15T10:30:00Z"
  }
]

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 list revisions"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Revisions are filtered by version.

GET /saas/categorylist/versions/123e4567-e89b-12d3-a456-426614174000/revisions/latest
async def get_latest_published_revision()

Get the latest published revision for a version.

This endpoint retrieves the most recent published (non-draft) revision for a version. Published revisions are immutable and represent approved versions of the categorylist.

Parameters

version_uuid UUID - UUID of the version to get the latest published revision for.

Returns

CategorylistRevision

Complete revision object containing:

  • uuid UUID - Revision UUID
  • number int - Revision number
  • name str - Revision name
  • is_draft bool - False for published revisions
  • labels CategoryLabelsData - Labels/columns for this revision
  • version_uuid UUID - UUID of the parent version

Example

curl -X GET "https://api.example.com/saas/categorylist/versions/123e4567-e89b-12d3-a456-426614174000/revisions/latest" \
-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:

{
  "uuid": "456e7890-e89b-12d3-a456-426614174001",
  "number": 3,
  "name": "Revision 3",
  "is_draft": false,
  "labels": {"labels": [], "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 latest published revision"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Returns error if no published revision exists.

GET /saas/categorylist/versions/123e4567-e89b-12d3-a456-426614174000/revisions/draft
async def get_draft_revision()

Get the draft revision for a version (if it exists).

This endpoint retrieves the draft revision for a version. Draft revisions are mutable and can be edited. Only one draft revision can exist per version.

Parameters

version_uuid UUID - UUID of the version to get the draft revision for.

Returns

CategorylistRevision

Complete revision object containing:

  • uuid UUID - Revision UUID
  • number int - Revision number
  • name str - Revision name
  • is_draft bool - True for draft revisions
  • labels CategoryLabelsData - Labels/columns for this revision
  • version_uuid UUID - UUID of the parent version

Example

curl -X GET "https://api.example.com/saas/categorylist/versions/123e4567-e89b-12d3-a456-426614174000/revisions/draft" \
-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:

{
  "uuid": "456e7890-e89b-12d3-a456-426614174001",
  "number": 4,
  "name": "Draft Revision",
  "is_draft": true,
  "labels": {"labels": [], "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 draft revision"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Returns error if no draft revision exists.

POST /saas/categorylist/revisions
async def create_revision()

Create a new draft revision for a version.

This endpoint creates a new draft revision for a version. If a draft already exists, it may return an error or the existing draft depending on the implementation.

Parameters

version_uuid UUID - UUID of the version to create a revision for.

revision_name str, optional - Name for the new revision.

Returns

CategorylistRevision

Complete revision object containing:

  • uuid UUID - Revision UUID
  • number int - Revision number
  • name str - Revision name
  • is_draft bool - True for newly created revisions
  • labels CategoryLabelsData - Labels/columns for this revision
  • version_uuid UUID - UUID of the parent version

Example

curl -X POST "https://api.example.com/saas/categorylist/revisions" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "version_uuid=123e4567-e89b-12d3-a456-426614174000" \
-F "revision_name=New Draft"

Response Example

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

{
  "uuid": "456e7890-e89b-12d3-a456-426614174001",
  "number": 4,
  "name": "New Draft",
  "is_draft": true,
  "labels": {"labels": [], "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 create revision"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Only one draft revision can exist per version.

POST /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/request
async def request_review()

Request review for a draft revision.

This endpoint saves a draft revision and sends review requests to specified users. Notifications and emails are sent to the reviewers with a link to review the revision.

Parameters

revision_uuid UUID - UUID of the draft revision to request review for.

usernames list[str] - List of usernames to send review requests to.

Returns

dict

Response indicating success (typically empty or status message).

Example

curl -X POST "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/request" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "usernames=reviewer1" \
-F "usernames=reviewer2"

Response Example

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

{
  "message": "Review requested 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 request review"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Sends notifications and emails to reviewers.

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

Check if a draft revision can be published.

This endpoint checks whether the current user has permission to publish a draft revision and returns a list of admin emails if review is required.

Parameters

revision_uuid UUID - UUID of the draft revision to check.

Returns

dict

Response containing:

  • can_publish bool - True if user can publish the revision
  • emails_to_request list[str] - List of admin emails if review is required

Example

curl -X GET "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/canPublish" \
-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:

{
  "can_publish": true,
  "emails_to_request": []
}

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 check if revision can be published"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Only users with CATEGORYLIST_ADMIN role can publish revisions. Returns admin emails if review is required.

POST /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/publish
async def publish_revision()

Publish a draft revision, making it immutable.

This endpoint publishes a draft revision, making it immutable and available for use. Published revisions cannot be modified. The revision becomes the latest published version of the categorylist.

Parameters

revision_uuid UUID - UUID of the draft revision to publish.

name str, optional - Name for the published revision.

validFrom date, optional - Start date for the revision's validity period.

validTo date, optional - End date for the revision's validity period.

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 including the published one

Example

curl -X POST "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/publish" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "name=Published Revision 1" \
-F "validFrom=2024-01-01" \
-F "validTo=2024-12-31"

Response Example

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

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

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 publish revision"
}

Note

Requires CATEGORYLIST_ADMIN permission. Published revisions are immutable.

POST /saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/upload
async def upload_categorylist()

Upload and merge categorylist CSV file data into a revision.

This endpoint uploads a CSV file and merges its data into a revision. For existing SKUs, it merges data (only updates if new value is not None/'' and different). For new SKUs, it creates new items with all data.

Parameters

revision_uuid UUID - UUID of the revision to upload data to.

category_list UploadFile - CSV file containing categorylist data.

categorylabels str - JSON string containing column mapping from CSV columns to internal column names.

Returns

dict

Response containing:

  • message str - Success message
  • created int - Number of new items created
  • updated int - Number of existing items updated
  • total_rows int - Total number of rows processed

Example

curl -X POST "https://api.example.com/saas/categorylist/revisions/123e4567-e89b-12d3-a456-426614174000/upload" \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "category_list=@categorylist.csv" \
-F 'categorylabels={"SKU": "general:SKU", "Product Name": "general:Product Name"}'

Response Example

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

{
  "message": "Categorylist uploaded successfully",
  "created": 50,
  "updated": 25,
  "total_rows": 75
}

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 upload catalog"
}

Note

Requires CATEGORYLIST_SUGGEST-EDIT permission. Revision must be a draft. CSV must contain a SKU column mapped to 'general:SKU'. Only merges non-empty values.