Change Sets

Source-agnostic approval workflow

AI agents, ERP integrations, or users propose changes via Change Sets. Reviewers inspect diffs, rate individual attributes, annotate text snippets, leave messages, and approve or reject — per-operation or in bulk. Approved changes are applied atomically to entities.

Draft → Pending Approval → Approved → Applied

Also: Rejected Revision Requested Partially Applied

Source-Agnostic

Every change set has a source with type (agent, user, integration, import), a name, and optional context. Treat all sources equally.

Per-Operation Granularity

Each change set contains multiple operations. Each operation targets one entity and can be individually approved or rejected.

Feedback Loop

Rate individual attributes (good/bad), annotate text snippets, and exchange messages. Request revisions with an auto-computed feedback summary.

Confidence Scores

Each proposed change can include a confidence score (0–1) and reasoning text, letting reviewers focus on low-confidence suggestions first.

Endpoints

Method	Path	Description
GET	`/change-sets`	List change sets (filterable)
GET	`/change-sets/stats`	Get stats (pending, approved, applied)
POST	`/change-sets`	Create a change set
GET	`/change-sets/:id`	Get change set by ID
PUT	`/change-sets/:id`	Add operations (draft only)
DELETE	`/change-sets/:id`	Delete change set (draft only)
POST	`/change-sets/:id/submit`	Submit for approval
POST	`/change-sets/:id/approve`	Approve all operations
POST	`/change-sets/:id/reject`	Reject all operations
POST	`/change-sets/:id/apply`	Apply approved changes to entities
POST	`/change-sets/:id/operations/:opId/approve`	Approve a single operation
POST	`/change-sets/:id/operations/:opId/reject`	Reject a single operation
POST	`/change-sets/:id/operations/:opId/rate`	Rate an attribute (good/bad)
POST	`/change-sets/:id/operations/:opId/annotate`	Add snippet annotation
DELETE	`/change-sets/:id/annotations/:annotationId`	Remove snippet annotation
GET	`/change-sets/:id/messages`	Get feedback messages
POST	`/change-sets/:id/messages`	Send a message
POST	`/change-sets/:id/request-revision`	Request revision from source
POST	`/change-sets/:id/resubmit`	Resubmit after revision
GET	`/records/:id/pending-changes`	Get pending changes for an entity

GET /change-sets

Returns all change sets, optionally filtered by status, source type, or schema.

Query Parameters

Parameter	Type	Description
`status`	`string?`	Filter by status: `draft`, `pending_approval`, `approved`, `rejected`, `applied`, `partially_applied`, `revision_requested`
`sourceType`	`string?`	Filter by source type: `agent`, `user`, `integration`, `import`
`schemaId`	`string?`	Filter by schema ID

curl https://api.sigma-pim.com/api/v1/change-sets?status=pending_approval \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
[
  {
    "id": "cs-agent-enrichment",
    "title": "AI Product Enrichment",
    "description": "AI-generated descriptions for 2 products",
    "source": {
      "type": "agent",
      "id": "agent-claude",
      "name": "Claude",
      "context": "Enrichment pipeline run #47"
    },
    "status": "pending_approval",
    "createdAt": "2025-03-01T10:00:00Z",
    "updatedAt": "2025-03-01T10:05:00Z",
    "submittedAt": "2025-03-01T10:05:00Z",
    "revisionCount": 0,
    "operations": [
      {
        "id": "cop-enrich-1",
        "type": "update",
        "entityId": "ent-001",
        "entityName": "Classic Oxford Shirt",
        "entitySku": "OXF-001",
        "schemaId": "schema-apparel",
        "status": "pending",
        "changes": [
          {
            "attributeAlias": "short-description",
            "attributeName": "Short Description",
            "oldValue": "A classic shirt.",
            "newValue": "Timeless Oxford weave in premium cotton...",
            "confidence": 0.92,
            "reasoning": "Enhanced with fabric details and style context"
          }
        ]
      }
    ]
  }
]

GET /change-sets/stats

Returns aggregate statistics for the change set dashboard.

curl https://api.sigma-pim.com/api/v1/change-sets/stats \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
{
  "pending": 3,
  "approvedThisWeek": 12,
  "totalApplied": 47,
  "activeSourceCount": 4
}

POST /change-sets

Create a new change set in draft status. Add operations in the request body or later via PUT.

Request Body

Field	Type	Description
`title`	`string`	Human-readable title
`description`	`string?`	Optional description
`source.type`	`string`	`agent`, `user`, `integration`, or `import`
`source.id`	`string?`	Optional source identifier
`source.name`	`string`	Display name of the source
`source.context`	`string?`	Optional context (e.g. pipeline run ID)
`operations`	`Operation[]`	Array of change operations (can be empty)
`operations[].type`	`string`	`create`, `update`, or `delete`
`operations[].entityId`	`string?`	Target entity ID (required for update/delete)
`operations[].schemaId`	`string`	Schema ID for the target entity
`operations[].changes`	`Change[]`	Array of proposed attribute changes
`operations[].changes[].attributeAlias`	`string`	Attribute alias to change
`operations[].changes[].attributeName`	`string`	Display name of the attribute
`operations[].changes[].scope`	`object?`	Dimension scope (e.g. `{"language":"en"}`)
`operations[].changes[].oldValue`	`any?`	Current value (for diff display)
`operations[].changes[].newValue`	`any`	Proposed new value
`operations[].changes[].confidence`	`number?`	Confidence score (0–1)
`operations[].changes[].reasoning`	`string?`	Explanation for the change

curl -X POST https://api.sigma-pim.com/api/v1/change-sets \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "AI Product Enrichment",
    "description": "AI-generated descriptions for 2 products",
    "source": {
      "type": "agent",
      "id": "agent-claude",
      "name": "Claude",
      "context": "Enrichment pipeline run #47"
    },
    "operations": [
      {
        "type": "update",
        "entityId": "ent-001",
        "schemaId": "schema-apparel",
        "changes": [
          {
            "attributeAlias": "short-description",
            "attributeName": "Short Description",
            "oldValue": "A classic shirt.",
            "newValue": "Timeless Oxford weave in premium cotton...",
            "confidence": 0.92,
            "reasoning": "Enhanced with fabric details and style context"
          }
        ]
      }
    ]
  }'

// Response — 201 Created
{
  "id": "cs_xK9mP2vL",
  "title": "AI Product Enrichment",
  "status": "draft",
  "revisionCount": 0,
  "operations": [ /* ... */ ],
  /* ... */
}

GET /change-sets/:id

Retrieve a single change set by ID, including all operations and proposed changes.

curl https://api.sigma-pim.com/api/v1/change-sets/cs-agent-enrichment \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

PUT /change-sets/:id

Add more operations to a draft change set. Only works when status is draft.

curl -X PUT https://api.sigma-pim.com/api/v1/change-sets/cs_xK9mP2vL \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "type": "update",
        "entityId": "ent-002",
        "schemaId": "schema-apparel",
        "changes": [
          {
            "attributeAlias": "long-description",
            "attributeName": "Long Description",
            "newValue": "Crafted from 100% organic cotton...",
            "confidence": 0.88
          }
        ]
      }
    ]
  }'

DELETE /change-sets/:id

Delete a change set. Only works when status is draft.

curl -X DELETE https://api.sigma-pim.com/api/v1/change-sets/cs_xK9mP2vL \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
{
  "deleted": true
}

POST /change-sets/:id/submit

Submit a draft change set for approval. Validates that all referenced schemas and entities exist, and that the change set has at least one operation. Transitions status to pending_approval.

curl -X POST https://api.sigma-pim.com/api/v1/change-sets/cs_xK9mP2vL/submit \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response — full change set with status "pending_approval"
{
  "id": "cs_xK9mP2vL",
  "status": "pending_approval",
  "submittedAt": "2025-03-01T10:05:00Z",
  /* ... */
}

POST /change-sets/:id/approve

Approve all pending operations in the change set. Sets overall status to approved. Optionally include a review note.

curl -X POST https://api.sigma-pim.com/api/v1/change-sets/cs_xK9mP2vL/approve \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "reviewNote": "Looks great, applying to catalog." }'

POST /change-sets/:id/reject

Reject all pending operations. Sets overall status to rejected.

curl -X POST https://api.sigma-pim.com/api/v1/change-sets/cs_xK9mP2vL/reject \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "reviewNote": "Descriptions too generic, need product-specific details." }'

POST /change-sets/:id/apply

Apply all approved operations to entities. Creates/updates/deletes entities atomically. Creates audit entries for each change. Returns a summary of applied, skipped, and errored operations. Status becomes applied or partially_applied.

curl -X POST https://api.sigma-pim.com/api/v1/change-sets/cs_xK9mP2vL/apply \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
{
  "applied": 2,
  "skipped": 1,
  "errors": []
}

Per-Operation Actions

POST /change-sets/:id/operations/:opId/approve

Approve a single operation within the change set. Only works when the change set is pending_approval and the operation is pending.

curl -X POST https://api.sigma-pim.com/api/v1/change-sets/cs_xK9mP2vL/operations/cop-enrich-1/approve \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

POST /change-sets/:id/operations/:opId/reject

Reject a single operation. Optionally include a review note.

curl -X POST https://api.sigma-pim.com/api/v1/change-sets/cs_xK9mP2vL/operations/cop-enrich-2/reject \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "reviewNote": "Price change too aggressive" }'

Feedback

POST /change-sets/:id/operations/:opId/rate

Rate an individual attribute change as good or bad. This feedback is stored on the proposed change and included in revision request summaries.

Request Body

Field	Type	Description
`attributeAlias`	`string`	The attribute to rate
`rating`	`string`	`good` or `bad`

curl -X POST https://api.sigma-pim.com/api/v1/change-sets/cs_xK9mP2vL/operations/cop-enrich-1/rate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "attributeAlias": "short-description", "rating": "good" }'

POST /change-sets/:id/operations/:opId/annotate

Add a snippet annotation to a proposed change. Highlight specific text spans as good or bad with an optional note.

Request Body

Field	Type	Description
`attributeAlias`	`string`	The attribute containing the text
`text`	`string`	The selected text snippet
`startOffset`	`number`	Character offset where the snippet starts
`endOffset`	`number`	Character offset where the snippet ends
`sentiment`	`string`	`good` or `bad`
`note`	`string?`	Optional explanation

curl -X POST https://api.sigma-pim.com/api/v1/change-sets/cs_xK9mP2vL/operations/cop-enrich-1/annotate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "attributeAlias": "short-description",
    "text": "premium cotton",
    "startOffset": 28,
    "endOffset": 42,
    "sentiment": "good",
    "note": "Good use of material specification"
  }'

DELETE /change-sets/:id/annotations/:annotationId

Remove a snippet annotation by its ID.

curl -X DELETE https://api.sigma-pim.com/api/v1/change-sets/cs_xK9mP2vL/annotations/snip_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Messages

GET /change-sets/:id/messages

Retrieve all feedback messages for a change set. Messages are ordered chronologically. Both humans and agents can participate in the thread.

curl https://api.sigma-pim.com/api/v1/change-sets/cs-agent-enrichment/messages \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
[
  {
    "id": "fmsg_r2d2",
    "changeSetId": "cs-agent-enrichment",
    "authorId": "user-admin",
    "authorName": "Product Manager",
    "authorType": "user",
    "timestamp": "2025-03-01T11:30:00Z",
    "body": "The descriptions look great but could use more SEO keywords."
  }
]

POST /change-sets/:id/messages

Send a feedback message. Works in any status except draft. Can optionally target a specific operation.

Request Body

Field	Type	Description
`authorId`	`string`	ID of the message author
`authorName`	`string`	Display name
`authorType`	`string`	`user` or `agent`
`body`	`string`	Message text
`operationId`	`string?`	Optional operation ID to scope the message

curl -X POST https://api.sigma-pim.com/api/v1/change-sets/cs-agent-enrichment/messages \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "authorId": "user-admin",
    "authorName": "Product Manager",
    "authorType": "user",
    "body": "Please add SEO keywords for summer 2025 collection."
  }'

Revision Loop

POST /change-sets/:id/request-revision

Request the source to revise the change set. Auto-computes a feedback summary (good/bad/unrated attribute counts, snippet count) and transitions status to revision_requested. Only works when status is pending_approval.

Request Body

Field	Type	Description
`requestedBy`	`string`	ID of the reviewer requesting revision
`message`	`string?`	Optional message to the source

curl -X POST https://api.sigma-pim.com/api/v1/change-sets/cs-agent-enrichment/request-revision \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "requestedBy": "user-admin",
    "message": "Descriptions need more product-specific details."
  }'

// Response includes feedbackSummary
{
  "id": "cs-agent-enrichment",
  "status": "revision_requested",
  "revisionCount": 1,
  /* ... */
}

POST /change-sets/:id/resubmit

Resubmit a change set after revision. Resets all operation statuses to pending, increments revisionCount, and transitions to pending_approval. Only works when status is revision_requested.

curl -X POST https://api.sigma-pim.com/api/v1/change-sets/cs-agent-enrichment/resubmit \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Entity Integration

GET /records/:id/pending-changes

Get all pending change set operations that target a specific entity. Useful for showing "incoming changes" on the product detail page.

curl https://api.sigma-pim.com/api/v1/records/ent-001/pending-changes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response — array of change sets with operations filtered to this entity
[
  {
    "changeSetId": "cs-agent-enrichment",
    "changeSetTitle": "AI Product Enrichment",
    "source": { "type": "agent", "name": "Claude" },
    "operation": {
      "id": "cop-enrich-1",
      "type": "update",
      "status": "pending",
      "changes": [ /* proposed changes for this entity */ ]
    }
  }
]

Previous Export Jobs Next Channels