Brands and Product images

Create and maintain workspace Brands and their directly owned Product images for generation.

GET /api/v2/brands

READ

MCP twin: list_brands

List Brands and their website enrichment and image-harvest status. Use list_product_images for their directly owned Product images.

Query parameters

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Per page (max 40; lower than other tools because these rows carry long descriptions). Each tool documents its own default.",
      "type": "integer",
      "minimum": 1,
      "maximum": 40
    },
    "workspace": {
      "description": "Target workspace: a slug, id, or exact name from list_workspaces. Omit to use this connection's default workspace. Must be inside the credential's grant and your current access; overrides the connection-level X-Workspace-Id header.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example response

{
  "success": true,
  "data": {
    "workspace": {
      "id": "workspace_1",
      "name": "Acme",
      "slug": "acme"
    },
    "brands": [
      {
        "id": "507f1f77bcf86cd799439011",
        "name": "Acme",
        "description": "Everyday essentials",
        "enrichmentStatus": "ready",
        "imageCount": 2
      }
    ],
    "total": 1,
    "page": 1,
    "pages": 1
  }
}

GET /api/v2/brands/:brandId

READ

MCP twin: get_brand

Read full Brand details, website enrichment status, and image-harvest status.

Path parameters: brandId (from the URL).

Query parameters

{
  "type": "object",
  "properties": {
    "brandId": {
      "type": "string",
      "pattern": "^[a-f\\d]{24}$"
    },
    "workspace": {
      "description": "Target workspace: a slug, id, or exact name from list_workspaces. Omit to use this connection's default workspace. Must be inside the credential's grant and your current access; overrides the connection-level X-Workspace-Id header.",
      "type": "string"
    }
  },
  "required": [
    "brandId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example response

{
  "success": true,
  "data": {
    "brand": {
      "id": "507f1f77bcf86cd799439011",
      "name": "Acme",
      "description": "Everyday essentials",
      "enrichmentStatus": "ready",
      "imageHarvestStatus": "ready"
    }
  }
}

POST /api/v2/brands

WRITE

MCP twin: create_brand

Create a Brand from a website URL or a name and description. Website enrichment and Product image harvesting run asynchronously; poll get_brand for status.

Workspace-scoped writes name workspace in the body (or as a ?workspace= query param on a bodyless DELETE); the X-Workspace-Id header is for reads only.

Request body

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 3000
    },
    "url": {
      "type": "string",
      "maxLength": 2000
    },
    "workspace": {
      "type": "string",
      "minLength": 1,
      "description": "Required write target: a workspace slug or id from list_workspaces. Writes never inherit the connection default."
    }
  },
  "required": [
    "workspace"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example response

{
  "success": true,
  "data": {
    "brand": {
      "id": "507f1f77bcf86cd799439011",
      "name": "Acme",
      "enrichmentStatus": "pending",
      "imageHarvestStatus": "pending"
    },
    "nextSteps": "Use get_brand to check website enrichment and image-harvest status."
  }
}

PATCH /api/v2/brands/:brandId

WRITE

MCP twin: update_brand

Update Brand details. An empty URL clears it. Updating the URL does not automatically re-run website enrichment or image harvesting.

Path parameters: brandId (from the URL).

Workspace-scoped writes name workspace in the body (or as a ?workspace= query param on a bodyless DELETE); the X-Workspace-Id header is for reads only.

Request body

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 3000
    },
    "url": {
      "type": "string",
      "maxLength": 2000
    },
    "workspace": {
      "type": "string",
      "minLength": 1,
      "description": "Required write target: a workspace slug or id from list_workspaces. Writes never inherit the connection default."
    },
    "brandId": {
      "type": "string",
      "pattern": "^[a-f\\d]{24}$"
    }
  },
  "required": [
    "workspace",
    "brandId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example response

{
  "success": true,
  "data": {
    "brand": {
      "id": "507f1f77bcf86cd799439011",
      "name": "Acme",
      "description": "Everyday essentials"
    }
  }
}

GET /api/v2/brands/:brandId/images

READ

MCP twin: list_product_images

List directly owned Product images for a Brand, including editable names, naming status, and capacity. Images with deletionPending are unavailable for generation.

Path parameters: brandId (from the URL).

Query parameters

{
  "type": "object",
  "properties": {
    "brandId": {
      "type": "string",
      "pattern": "^[a-f\\d]{24}$"
    },
    "workspace": {
      "description": "Target workspace: a slug, id, or exact name from list_workspaces. Omit to use this connection's default workspace. Must be inside the credential's grant and your current access; overrides the connection-level X-Workspace-Id header.",
      "type": "string"
    }
  },
  "required": [
    "brandId"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example response

{
  "success": true,
  "data": {
    "brandId": "507f1f77bcf86cd799439011",
    "images": [
      {
        "id": "507f1f77bcf86cd799439012",
        "brandId": "507f1f77bcf86cd799439011",
        "name": "Bottle front",
        "url": "https://media.example.com/bottle.png",
        "namingStatus": "ready"
      }
    ],
    "total": 1,
    "limit": 50
  }
}

POST /api/v2/brands/:brandId/images/upload-url

WRITE

MCP twin: request_product_image_upload

Request a Brand-bound upload URL for one JPEG, PNG, or WebP image of at most 10 MB. Upload its bytes then call add_product_images.

Path parameters: brandId (from the URL).

Workspace-scoped writes name workspace in the body (or as a ?workspace= query param on a bodyless DELETE); the X-Workspace-Id header is for reads only.

Request body

{
  "type": "object",
  "properties": {
    "brandId": {
      "type": "string",
      "pattern": "^[a-f\\d]{24}$"
    },
    "contentType": {
      "type": "string",
      "enum": [
        "image/jpeg",
        "image/png",
        "image/webp"
      ]
    },
    "workspace": {
      "type": "string",
      "minLength": 1,
      "description": "Required write target: a workspace slug or id from list_workspaces. Writes never inherit the connection default."
    }
  },
  "required": [
    "brandId",
    "contentType",
    "workspace"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example response

{
  "success": true,
  "data": {
    "brandId": "507f1f77bcf86cd799439011",
    "uploadKey": "users/user_1/brand-image-uploads/workspace_1/507f1f77bcf86cd799439011/93ad2002-d933-4d27-877c-1e8ebc000000.png",
    "uploadUrl": "https://uploads.example.com/presigned",
    "contentType": "image/png",
    "expiresInSeconds": 900,
    "maxBytes": 10485760
  }
}

POST /api/v2/brands/:brandId/images

WRITE

MCP twin: add_product_images

Add up to 20 uploaded Product images directly to a Brand. Accepts only upload keys from request_product_image_upload for this user, workspace, and Brand. Repeat the identical ordered input on retries; naming runs in the background without user credit charges.

Path parameters: brandId (from the URL).

Workspace-scoped writes name workspace in the body (or as a ?workspace= query param on a bodyless DELETE); the X-Workspace-Id header is for reads only.

Request body

{
  "type": "object",
  "properties": {
    "brandId": {
      "type": "string",
      "pattern": "^[a-f\\d]{24}$"
    },
    "images": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uploadKey": {
            "type": "string",
            "minLength": 1,
            "maxLength": 600,
            "description": "uploadKey returned by request_product_image_upload after uploading the file bytes."
          },
          "filename": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Original filename used as the initial editable image name."
          }
        },
        "required": [
          "uploadKey",
          "filename"
        ],
        "additionalProperties": false
      }
    },
    "workspace": {
      "type": "string",
      "minLength": 1,
      "description": "Required write target: a workspace slug or id from list_workspaces. Writes never inherit the connection default."
    }
  },
  "required": [
    "brandId",
    "images",
    "workspace"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example response

{
  "success": true,
  "data": {
    "brandId": "507f1f77bcf86cd799439011",
    "uploaded": 1,
    "images": [
      {
        "id": "507f1f77bcf86cd799439012",
        "name": "bottle",
        "namingStatus": "pending"
      }
    ]
  }
}

PATCH /api/v2/brands/:brandId/images/:imageId

WRITE

MCP twin: rename_product_image

Change the editable name of a directly owned Product image.

Path parameters: brandId, imageId (from the URL).

Workspace-scoped writes name workspace in the body (or as a ?workspace= query param on a bodyless DELETE); the X-Workspace-Id header is for reads only.

Request body

{
  "type": "object",
  "properties": {
    "brandId": {
      "type": "string",
      "pattern": "^[a-f\\d]{24}$"
    },
    "imageId": {
      "type": "string",
      "pattern": "^[a-f\\d]{24}$"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    },
    "workspace": {
      "type": "string",
      "minLength": 1,
      "description": "Required write target: a workspace slug or id from list_workspaces. Writes never inherit the connection default."
    }
  },
  "required": [
    "brandId",
    "imageId",
    "name",
    "workspace"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example response

{
  "success": true,
  "data": {
    "image": {
      "id": "507f1f77bcf86cd799439012",
      "name": "Bottle front",
      "namingStatus": "manual"
    }
  }
}

DELETE /api/v2/brands/:brandId/images/:imageId

DESTRUCTIVE

MCP twin: remove_product_image

Permanently remove a Product image from its Brand, including exclusively owned stored media. Only call when the user requests removal.

Path parameters: brandId, imageId (from the URL).

Workspace-scoped writes name workspace in the body (or as a ?workspace= query param on a bodyless DELETE); the X-Workspace-Id header is for reads only.

Request body

{
  "type": "object",
  "properties": {
    "brandId": {
      "type": "string",
      "pattern": "^[a-f\\d]{24}$"
    },
    "imageId": {
      "type": "string",
      "pattern": "^[a-f\\d]{24}$"
    },
    "workspace": {
      "type": "string",
      "minLength": 1,
      "description": "Required write target: a workspace slug or id from list_workspaces. Writes never inherit the connection default."
    }
  },
  "required": [
    "brandId",
    "imageId",
    "workspace"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Example response

{
  "success": true,
  "data": {
    "brandId": "507f1f77bcf86cd799439011",
    "imageId": "507f1f77bcf86cd799439012",
    "removed": true
  }
}

On this page