Skip to main content

Products API

The Products API allows you to manage products in your workspace. Products represent your own offerings that you want to compare against competitors.

List Products​

Get all products for your workspace.

GET /api/products

Response​

{
  "products": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "workspace-id",
      "name": "My Product",
      "description": "Product description",
      "audience": "Primary buyer persona",
      "valueProps": ["Value prop 1", "Value prop 2"],
      "features": [],
      "categories": [],
      "capabilities": [],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "createdByUserId": "user-id"
    }
  ]
}

Get Product​

Get a specific product by ID.

GET /api/products/{id}

Path Parameters​

  • id (string, required) - Product ID

Response​

{
  "product": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "name": "My Product",
    "description": "Product description",
    "audience": "Primary buyer persona",
    "valueProps": ["Value prop 1"],
    "features": [],
    "categories": [],
    "capabilities": [],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "createdByUserId": "user-id"
  }
}

Create Product​

Create a new product. Requires EDITOR role or higher.

POST /api/products

Request Body​

{
  "name": "My Product",
  "description": "Product description",
  "audience": "Primary buyer persona",
  "valueProps": ["Value prop 1", "Value prop 2"],
  "features": [],
  "categories": [],
  "capabilities": []
}

Required Fields​

  • name (string) - Product name
  • description (string) - Product description
  • audience (string) - Primary buyer persona

Optional Fields​

  • valueProps (array of strings) - Value propositions
  • features (array of objects) - Product features
  • categories (array of objects) - Product categories
  • capabilities (array of objects) - Product capabilities

Response​

{
  "product": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "name": "My Product",
    "description": "Product description",
    "audience": "Primary buyer persona",
    "valueProps": ["Value prop 1"],
    "features": [],
    "categories": [],
    "capabilities": [],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "createdByUserId": "user-id"
  }
}

Update Product​

Update a product. Requires EDITOR role or higher.

PATCH /api/products/{id}

Path Parameters​

  • id (string, required) - Product ID

Request Body​

All fields are optional. Only include fields you want to update:

{
  "name": "Updated Product Name",
  "description": "Updated description",
  "audience": "Updated audience",
  "valueProps": ["New value prop"],
  "features": [],
  "categories": [],
  "capabilities": []
}

Response​

{
  "product": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "name": "Updated Product Name",
    "description": "Updated description",
    "audience": "Updated audience",
    "valueProps": ["New value prop"],
    "features": [],
    "categories": [],
    "capabilities": [],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "createdByUserId": "user-id"
  }
}

Delete Product​

Delete a product. Requires EDITOR role or higher.

DELETE /api/products/{id}

Path Parameters​

  • id (string, required) - Product ID

Response​

{
  "success": true
}

Error Responses​

  • 400 - Bad Request (missing required fields, invalid data)
  • 401 - Unauthorized (invalid or missing API key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found (product doesn't exist)