Products & Projects

Products are organized into projects. A project groups related products and their generated assets (ads, copy, videos).

Projects

List Projects

GET /api/products?limit=20
Authorization: Bearer <token>

Response (200):

{
  "projects": [
    {
      "id": "uuid",
      "name": "Summer Campaign",
      "description": "Q3 ad creatives",
      "product_count": "3",
      "asset_count": "15",
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-09T14:00:00Z"
    }
  ]
}

List Products in a Project

GET /api/products?projectId=<uuid>&limit=50
Authorization: Bearer <token>

Response (200):

{
  "products": [
    {
      "id": "uuid",
      "name": "Widget Pro",
      "description": "The best widget on the market",
      "price": "29.99",
      "currency": "USD",
      "brand": "WidgetCo",
      "category": "Electronics",
      "source_url": "https://example.com/widget-pro",
      "image_url": "https://example.com/image.jpg",
      "created_at": "2026-03-05T10:00:00Z"
    }
  ]
}

Create Project

POST /api/products
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Summer Campaign",
  "description": "Q3 ad creatives"
}

Field	Type	Required	Constraints
name	string	Yes	1-200 chars
description	string	No	Max 1000 chars

Response (201):

{
  "project": {
    "id": "uuid",
    "name": "Summer Campaign",
    "description": "Q3 ad creatives",
    "user_id": "uuid",
    "status": "active",
    "created_at": "2026-03-09T10:00:00Z"
  }
}

Product Ingestion

Import a product by URL. CutX scrapes the page for structured data (name, description, price, images) using Open Graph, JSON-LD, and meta tags.

POST /api/products/ingest
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://example.com/product-page",
  "projectId": "uuid"
}

Response (201):

{
  "product": {
    "id": "uuid",
    "name": "Widget Pro",
    "description": "The best widget...",
    "price": "29.99",
    "currency": "USD",
    "brand": "WidgetCo",
    "category": "Electronics",
    "source_url": "https://example.com/product-page",
    "features": ["Wireless", "Waterproof"],
    "images": [
      { "id": "uuid", "url": "https://...", "is_primary": true }
    ]
  }
}

Assets

List Generated Assets

GET /api/assets?projectId=<uuid>&type=image&limit=20&offset=0
Authorization: Bearer <token>

Param	Type	Description
projectId	uuid	Filter by project
type	string	copy, image, video, audio
limit	number	Max 200, default 20
offset	number	Pagination offset

Response (200):

{
  "assets": [
    {
      "id": "uuid",
      "type": "image",
      "name": "Static Ad - Modern",
      "url": "https://cutx-media.r2.dev/...",
      "platform": "meta",
      "content": null,
      "metadata": { "style": "modern", "aspectRatio": "1:1" },
      "created_at": "2026-03-09T10:00:00Z"
    }
  ],
  "total": 15
}