Get Design Variants

Retrieve design variants created from a specific design, idea, or workspace. This endpoint allows you to access both generated and edited variants of designs in your Sivi account.

API Endpoint

POST enterprise/get-design-variants

GET enterprise/get-design-variants

Authentication

Note: This API is available exclusively for users on the Enterprise plan and requires an Enterprise admin account API key.

This endpoint requires API key authentication. Include your API key in the request header:

sivi-api-key: YOUR_API_KEY

POST Request Body

{
  "designId": "97026520-1f1b-11f0-ada0-01392001fe46",
  "workspaceId": "845df4t-rtfd-11f0-a4r4j5934k44432",
  "userId": "3eda4jjsdf-5ffd-42d4-23a0-013dflgk3fffq",
  "abstractUserId": "281743-2322-34i44sd3-dkfjgdkjf292",
  "type": "all",
  "cursor": "67ea6b92047ad842e0d4161b",
  "limit": 30
}

GET Request Parameters

For GET requests, you can pass the same parameters as in the POST request using a JSON object in the queryParams parameter:

GET enterprise/get-design-variants?queryParams={"designId":"97026520-1f1b-11f0-ada0-01392001fe46","workspaceId":"845df4t-rtfd-11f0-a4r4j5934k44432","userId":"3eda4jjsdf-5ffd-42d4-23a0-013dflgk3fffq","abstractUserId":"281743-2322-34i44sd3-dkfjgdkjf292","type":"all","cursor":"67ea6b92047ad842e0d4161b","limit":30}

The queryParams should be URL-encoded and contain a valid JSON object with all your request parameters.

POST Request Parameters

Parameter	Type	Required	Description
designId	string	Conditional	Unique identifier for a specific design
userId	string	Conditional	Unique identifier for a user (Enterprise API only)
workspaceId	string	Conditional	Unique identifier for a workspace (Enterprise API only)
abstractUserId	string	No	Unique identifier for the user whose designs to retrieve. If provided, returns designs for the specified user. If not provided, returns designs for the authenticated user.
type	string	No	Type of variants to retrieve: "all", "generated", or "edited". Default is "all"
cursor	string	No	Cursor for pagination. Pass the cursor received from the previous response to get the next page. If not provided, returns the first page.
limit	number	No	Number of variants to return per page (1-100). Default is 100

ID Priority

You must provide at least one of the ID fields. If multiple IDs are provided, first ID in the following order is considered:

1. designId
2. userId
3. workspaceId :::

Response

Successful Response

{
  "status": 200,
  "body": {
    "designId": "97026520-1f1b-11f0-ada0-01392001fe46",
    "variations": [
      {
        "variantImageUrl": "https://resources.hellosivi.com/user-data/e5ef6aa0-8d6c-11ec-bd33-8d2f1bec7c21/generated/sg0yMSZzNnU--97026520-1f1b-11f0-ada0-01392001fe46--sh0V7MlzOPm.jpg",
        "variantEditLink": "https://instant.sivi.ai/#/variant/sh0V7MlzOPm/independent-design-editor?type=edited",
        "variantId": "sh0V7MlzOPm",
      }
      // Additional variants...
    ],
    "cursor": "67ea6b92047ad842e0d4161b"
  }
}

Response Fields

Field	Type	Description
designId	string	Id sent in request for retrieving variants
variations	array	Array of variant objects containing URLs and links
variations.variantImageUrl	string	Direct URL to the variant image
variations.variantEditLink	string	Link to edit the variant in the Sivi editor
variations.variantId	string	Unique identifier for the variant
nextPage	boolean	Whether there are more variants to retrieve: true or false

Authentication Error

{
  "status": 401,
  "body": {
    "message": "Failed to authenticate request. Please add sivi-api-key header in request"
  }
}

Invalid Input

{
  "status": 422,
  "body": {
    "message": "Invalid input"
  }
}

Server Error

{
  "status": 500,
  "body": {
    "message": "Server internal error"
  }
}

Usage Notes

• The API returns a maximum of 100 variants per request
• When nextPage response is true, use the page parameter for paginated results when a design has many variants
• The type parameter allows filtering between AI-generated variants and user-edited variants
• Enterprise users can retrieve variants across all users in their workspace

Examples

GET Example

curl -X GET "https://connect.sivi.ai/api/prod/v2/enterprise/get-design-variants?queryParams=%7B%22designId%22%3A%2297026520-1f1b-11f0-ada0-01392001fe46%22%2C%22ideaId%22%3A%227823832-1f1b-11f0-ada0-43421d423ed2f64%22%2C%22workspaceId%22%3A%22845df4t-rtfd-11f0-a4r4j5934k44432%22%2C%22userId%22%3A%223eda4jjsdf-5ffd-42d4-23a0-013dflgk3fffq%22%2C%22type%22%3A%22all%22%2C%22page%22%3A1%2C%22limit%22%3A30%7D" \
  -H "sivi-api-key: YOUR_API_KEY"

Note: The queryParams value above is the URL-encoded version of the full JSON object matching the POST request body

POST Example

curl -X POST "https://connect.sivi.ai/api/prod/v2/enterprise/get-design-variants" \
  -H "sivi-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "designId": "97026520-1f1b-11f0-ada0-01392001fe46",
  "type": "all",
  "limit": 10
}'

Get Generated Variants Only

curl -X POST "https://connect.sivi.ai/api/prod/v2/enterprise/get-design-variants" \
  -H "sivi-api-key: YOUR_ENTERPRISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "workspaceId": "845df4t-rtfd-11f0-a4r4j5934k44432",
  "type": "generated",
  "cursor": "67ea6b92047ad842e0d4161b",
  "limit": 50
}'