> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1eye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Products

Manage Products programmatically using the 1eye API. Create, retrieve, update, and delete Product definitions to describe the solutions your business offers.

Products are part of the 1eye Knowledge Base. They help 1eye understand your company's offerings and evaluate buying activities related to those products.

Changes made through the API are reflected in the 1eye Console, and vice versa.

## Base URL

All Product API requests use:

```text theme={null}
https://api.1eye.ai/v1/kb/products
```

## Authentication

All endpoints require a valid 1eye API key.

```http theme={null}
Authorization: Bearer 1eye_live_xxxxxxxxx
```

API keys are scoped to a single workspace. All operations automatically apply to the workspace associated with your API key.

You do not need to provide a workspace ID.

The examples below use `$API_KEY` as the environment variable containing your API key.

For more information, see [Authentication](/api-reference/auth).

## Endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/kb/products` | List Products |
| `GET` | `/v1/kb/products/{id}` | Retrieve a Product |
| `POST` | `/v1/kb/products` | Create a Product |
| `PATCH` | `/v1/kb/products/{id}` | Update a Product |
| `DELETE` | `/v1/kb/products/{id}` | Delete a Product |

All endpoints return JSON responses, except DELETE, which returns no response body.

***

## Product Object

A Product defines a solution offered by your company, including its capabilities, target customers, and value proposition.

For example, Snowbricks, a fictional cloud data and AI platform, offers a unified data platform combining cloud warehousing, lakehouse analytics, data engineering, and machine learning capabilities.

### Fields

| Field | Type | Description |
| - | - | - |
| `name` | string | Product name |
| `short_name` | string | Unique short identifier |
| `description` | string | Detailed Product definition |

### Example Product

```json theme={null}
{
  "name": "Snowbricks Data Cloud",
  "short_name": "snowbricks-data-cloud",
  "description": "Snowbricks Data Cloud is a unified cloud data platform combining the performance of enterprise data warehouses with the flexibility of modern lakehouse architectures. It enables organizations to ingest, transform, govern, analyze, and activate structured and unstructured data across analytics and AI workloads. Key capabilities include scalable SQL analytics, ETL and ELT processing, open table formats, real-time data pipelines, collaborative notebooks, machine learning, and workload-based compute scaling. The platform helps data engineering and analytics teams reduce infrastructure complexity while supporting business intelligence and AI applications."
}
```

### System-Managed Fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique Product identifier |
| `client_id` | string | Workspace identifier |
| `created_by` | object | Information about who created the Product |
| `created_at` | datetime | Creation timestamp |
| `updated_at` | datetime | Last modification timestamp |

These fields are read-only and cannot be modified through Create or Update requests.

***

## 1. List Products

`GET /v1/kb/products`

Retrieve a paginated list of Products configured in your workspace.

### Query Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `limit` | integer | No | Maximum records to return. Default: 100. Maximum: 1,000 |
| `cursor` | string | No | Pagination cursor |

### Example Request

```bash theme={null}
curl "https://api.1eye.ai/v1/kb/products?limit=100" \
  -H "Authorization: Bearer $API_KEY"
```

### Example Response

**200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "<product_id>",
      "client_id": "wor_123456789012345678",
      "name": "Snowbricks Data Cloud",
      "short_name": "snowbricks-data-cloud",
      "description": "A unified cloud data platform combining scalable data warehousing, lakehouse analytics, data engineering, and machine learning capabilities.",
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-18T18:00:00Z"
    },
    {
      "id": "<another_product_id>",
      "client_id": "wor_123456789012345678",
      "name": "Snowbricks AI",
      "short_name": "snowbricks-ai",
      "description": "An integrated environment for building, training, evaluating, and deploying AI and machine learning applications using governed enterprise data.",
      "created_at": "2026-10-18T18:05:00Z",
      "updated_at": "2026-10-18T18:05:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}
```

### Pagination

When additional results are available, use `pagination.next_cursor` to retrieve the next page.

```bash theme={null}
curl "https://api.1eye.ai/v1/kb/products?limit=100&cursor=YOUR_CURSOR" \
  -H "Authorization: Bearer $API_KEY"
```

A `null` cursor indicates the end of the collection.

See [Pagination](/api-reference/pagination).

### Behavior

* Returns Products belonging to the authenticated workspace.
* Excludes deleted Products.
* Supports cursor-based pagination.
* Returns an empty `data` array when no Products exist.

***

## 2. Retrieve a Product

`GET /v1/kb/products/{id}`

Retrieve a specific Product using its unique identifier.

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Product identifier |

### Example Request

```bash theme={null}
curl "https://api.1eye.ai/v1/kb/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $API_KEY"
```

### Example Response

**200 OK**

```json theme={null}
{
  "id": "<product_id>",
  "client_id": "wor_123456789012345678",
  "name": "Snowbricks Data Cloud",
  "short_name": "snowbricks-data-cloud",
  "description": "Snowbricks Data Cloud is a unified cloud data platform combining the performance of enterprise data warehouses with the flexibility of modern lakehouse architectures. It enables organizations to ingest, transform, govern, analyze, and activate structured and unstructured data across analytics and AI workloads. Key capabilities include scalable SQL analytics, ETL and ELT processing, open table formats, real-time data pipelines, collaborative notebooks, machine learning, and workload-based compute scaling. The platform helps data engineering and analytics teams reduce infrastructure complexity while supporting business intelligence and AI applications.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}
```

### Behavior

* Returns the complete Product record.
* Includes system-generated metadata.
* Returns `404 Not Found` if the Product does not exist, has been deleted, or belongs to another workspace.

***

## 3. Create a Product

`POST /v1/kb/products`

Create a new Product in your workspace.

New Products become available to the relevant Buyer Intelligence and Market Signals processing logic.

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Product name |
| `short_name` | string | Yes | Unique short identifier |
| `description` | string | Yes | Detailed Product definition |

### Example Request

```bash theme={null}
curl -X POST "https://api.1eye.ai/v1/kb/products" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Snowbricks Data Cloud",
    "short_name": "snowbricks-data-cloud",
    "description": "Snowbricks Data Cloud is a unified cloud data platform combining the performance of enterprise data warehouses with the flexibility of modern lakehouse architectures. It enables organizations to ingest, transform, govern, analyze, and activate structured and unstructured data across analytics and AI workloads. Key capabilities include scalable SQL analytics, ETL and ELT processing, open table formats, real-time data pipelines, collaborative notebooks, machine learning, and workload-based compute scaling. The platform helps data engineering and analytics teams reduce infrastructure complexity while supporting business intelligence and AI applications."
  }'
```

### Example Response

**201 Created**

```json theme={null}
{
  "id": "<product_id>",
  "client_id": "wor_123456789012345678",
  "name": "Snowbricks Data Cloud",
  "short_name": "snowbricks-data-cloud",
  "description": "Snowbricks Data Cloud is a unified cloud data platform combining the performance of enterprise data warehouses with the flexibility of modern lakehouse architectures. It enables organizations to ingest, transform, govern, analyze, and activate structured and unstructured data across analytics and AI workloads. Key capabilities include scalable SQL analytics, ETL and ELT processing, open table formats, real-time data pipelines, collaborative notebooks, machine learning, and workload-based compute scaling. The platform helps data engineering and analytics teams reduce infrastructure complexity while supporting business intelligence and AI applications.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}
```

### Behavior

When a Product is created:

1. 1eye generates a unique Product ID.
2. The Product is associated with your workspace.
3. The Product appears in the Knowledge Base.
4. It becomes available to relevant future signal evaluation and buyer intelligence processing.
5. It can be retrieved or updated through the API.

**Important:** Creating a Product does not automatically generate historical Signals or reevaluate existing Buyers.

### Validation

* `name` must not be empty.
* `short_name` must not be empty.
* `description` must not be empty.
* `short_name` must be unique among active Products in the workspace.
* System-managed fields cannot be supplied.

***

## 4. Update a Product

`PATCH /v1/kb/products/{id}`

Update an existing Product.

Only fields supplied in the request are modified.

### Request Body

| Field | Type | Required |
| - | - | - |
| `name` | string | No |
| `short_name` | string | No |
| `description` | string | No |

At least one editable field must be supplied.

### Example Request

```bash theme={null}
curl -X PATCH "https://api.1eye.ai/v1/kb/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Snowbricks Data Cloud is a unified enterprise data platform for warehousing, lakehouse analytics, data engineering, and AI. It supports scalable SQL workloads, governed data sharing, open table formats, real-time pipelines, machine learning, and compute optimization. Snowbricks helps organizations consolidate fragmented data infrastructure into a single platform for analytics and AI applications."
  }'
```

### Example Response

**200 OK**

```json theme={null}
{
  "id": "<product_id>",
  "client_id": "wor_123456789012345678",
  "name": "Snowbricks Data Cloud",
  "short_name": "snowbricks-data-cloud",
  "description": "Snowbricks Data Cloud is a unified enterprise data platform for warehousing, lakehouse analytics, data engineering, and AI. It supports scalable SQL workloads, governed data sharing, open table formats, real-time pipelines, machine learning, and compute optimization. Snowbricks helps organizations consolidate fragmented data infrastructure into a single platform for analytics and AI applications.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:30:00Z"
}
```

### Behavior

* Supports partial updates.
* Preserves omitted fields.
* Preserves the original Product ID.
* Reflects changes in the Console.
* Applies updated definitions to future processing.

**Important:** Updating a Product does not automatically reevaluate historical Buyers or Signals.

***

## 5. Delete a Product

`DELETE /v1/kb/products/{id}`

Delete a Product from your workspace.

Deletion performs a **soft delete**.

### Example Request

```bash theme={null}
curl -X DELETE "https://api.1eye.ai/v1/kb/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $API_KEY"
```

### Response

**204 No Content**

The response body is empty.

### What Happens When a Product Is Deleted?

* The Product is removed from the active Knowledge Base.
* It no longer appears in List Products.
* Retrieving the deleted record returns `404 Not Found`.
* It is excluded from future product-related processing.
* Historical Product information and associated Signals remain preserved.

Deleting a Product does not delete Buyers, Signals, or historical evaluations.

**Restoring deleted Products is not currently exposed through the public API.**

***

## 6. How Products Affect Buyer Intelligence

Product definitions help 1eye understand what your business sells and identify relevant buying activity.

For example, Snowbricks might define:

| Product | Description |
| - | - |
| Snowbricks Data Cloud | Unified data platform |
| Snowbricks AI | AI and machine learning infrastructure |
| Snowbricks Streaming | Real-time data ingestion and processing |
| Snowbricks Governance | Enterprise data governance and security |

### Products vs. Topics

| Resource | Purpose |
| - | - |
| Products | Define the solutions your company offers |
| Topics | Define the broader subjects your ideal customers research |

For example:

**Product:** Snowbricks Data Cloud

**Topic:** Lakehouse Architecture

A Product describes a specific offering. A Topic describes an area of market interest that may indicate demand for that offering.

### Market Signals

Products may provide context for product-related Market Signals, including the `explored_product` trigger.

1eye uses the existing Signal Intelligence pipeline to identify relevant activity.

### Impact of Product Changes

| Operation | Impact |
| - | - |
| Create | New Product becomes available for future processing |
| Update | Updated Product definition is used for future processing |
| Delete | Product is removed from active processing |

### Console Synchronization

Changes made through the API are reflected in the 1eye Console, and vice versa.

***

## 7. Error Handling

All Product endpoints use the standard 1eye API error format.

| HTTP Status | Description |
| - | - |
| `200` | Successful retrieval or update |
| `201` | Product created |
| `204` | Product deleted |
| `400` | Invalid request |
| `401` | Invalid or missing API key |
| `403` | Insufficient permissions |
| `404` | Product not found or inaccessible |
| `409` | Duplicate or conflicting Product |
| `429` | Workspace rate limit exceeded |
| `500` | Internal server error |

### Example Error

**404 Not Found**

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Product not found.",
    "request_id": "req_359051753366339585"
  }
}
```

See [Errors](/api-reference/errors).

***

## 8. Pagination & Rate Limits

List Products supports cursor-based pagination.

* Default page size: 100.
* Maximum page size: 1,000.
* Use `cursor` for subsequent pages.
* `next_cursor: null` indicates the end of the collection.

Product API requests count toward your workspace API rate limits.

See [Pagination](/api-reference/pagination) and [Rate Limits](/api-reference/rate-limits).

***

## 9. Best Practices

### Define Meaningful Products

Create Products corresponding to distinct customer-facing solutions.

Avoid creating multiple Products that describe the same offering.

### Use Consistent Short Names

```text theme={null}
snowbricks-data-cloud
snowbricks-ai
snowbricks-streaming
snowbricks-governance
```

### Describe What the Product Does

Include the Product's:

* Primary capabilities.
* Target customers.
* Business problems solved.
* Key use cases.
* Relevant technologies.
* Differentiating capabilities.

### Separate Products from Topics

A Product should represent what you sell.

A Topic should represent what your buyers are researching.

### Keep Product Definitions Current

Update descriptions when capabilities, positioning, or use cases change.

***

## 10. Related Documentation

* [Authentication](/api-reference/auth)
* [Pagination](/api-reference/pagination)
* [Errors](/api-reference/errors)
* [Rate Limits](/api-reference/rate-limits)
* [List Signals](/api-reference/list-signals)
* [Knowledge Base – Products](/knowledge-base/products)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.