> ## 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.

# Topics

Manage Market Topics programmatically using the 1eye API. Create, retrieve, update, and delete Topics to define the subjects and technologies your ideal customers are researching.

Topics are part of the 1eye Knowledge Base. They provide context for identifying and evaluating Market Signals, helping 1eye understand which research activities are relevant to your business.

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

## Base URL

All Topic API requests use:

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

## 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/topics` | List Topics |
| `GET` | `/v1/kb/topics/{id}` | Retrieve a Topic |
| `POST` | `/v1/kb/topics` | Create a Topic |
| `PATCH` | `/v1/kb/topics/{id}` | Update a Topic |
| `DELETE` | `/v1/kb/topics/{id}` | Delete a Topic |

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

***

## Topic Object

A Topic represents a subject, technology, or business challenge relevant to your ideal customers.

For example, Snowbricks, a fictional cloud data and AI platform, might track interest in lakehouse architecture, cloud data warehousing, data engineering, and machine learning infrastructure.

### Fields

| Field | Type | Description |
| - | - | - |
| `name` | string | Full name of the Topic |
| `short_name` | string | Unique short identifier |
| `description` | string | Detailed definition of the Topic and its business relevance |

### Example Topic

```json theme={null}
{
  "name": "Lakehouse Architecture",
  "short_name": "lakehouse-architecture",
  "description": "Modern data architectures that combine the scalability and flexibility of data lakes with the performance, governance, and SQL analytics capabilities of data warehouses. Organizations researching lakehouse architecture are typically evaluating ways to unify structured and unstructured data, simplify ETL pipelines, support real-time analytics, and enable AI and machine learning workloads on a common data platform. Related concepts include open table formats, Apache Iceberg, Delta Lake, cloud data warehouses, and unified analytics."
}
```

### System-Managed Fields

1eye automatically generates and maintains additional fields.

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique Topic identifier |
| `client_id` | string | Workspace identifier |
| `created_by` | object | Information about who created the Topic |
| `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 Topics

`GET /v1/kb/topics`

Retrieve a paginated list of Topics 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 returned by a previous request |

### Example Request

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

### Example Response

**200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "<topic_id>",
      "client_id": "wor_123456789012345678",
      "name": "Lakehouse Architecture",
      "short_name": "lakehouse-architecture",
      "description": "Modern data architectures that combine the flexibility of data lakes with the performance and governance capabilities of data warehouses.",
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-18T18:00:00Z"
    },
    {
      "id": "<another_topic_id>",
      "client_id": "wor_123456789012345678",
      "name": "Cloud Data Warehousing",
      "short_name": "cloud-data-warehousing",
      "description": "Cloud-based analytical data platforms that provide scalable storage, SQL querying, data integration, and business intelligence capabilities.",
      "created_at": "2026-10-18T18:05:00Z",
      "updated_at": "2026-10-18T18:05:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}
```

### Pagination

When additional results are available, `pagination.next_cursor` contains a continuation token.

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

When `next_cursor` is `null`, there are no additional results.

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

### Behavior

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

***

## 2. Retrieve a Topic

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

Retrieve a specific Topic using its unique identifier.

### Path Parameters

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

### Example Request

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

### Example Response

**200 OK**

```json theme={null}
{
  "id": "<topic_id>",
  "client_id": "wor_123456789012345678",
  "name": "Lakehouse Architecture",
  "short_name": "lakehouse-architecture",
  "description": "Modern data architectures that combine the scalability and flexibility of data lakes with the performance, governance, and SQL analytics capabilities of data warehouses. Organizations researching lakehouse architecture are typically evaluating ways to unify structured and unstructured data, simplify ETL pipelines, support real-time analytics, and enable AI and machine learning workloads on a common data platform. Related concepts include open table formats, Apache Iceberg, Delta Lake, cloud data warehouses, and unified analytics.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}
```

### Behavior

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

***

## 3. Create a Topic

`POST /v1/kb/topics`

Create a new Topic in your workspace.

New Topics become available for future Market Signals processing.

### Request Body

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

### Example Request

```bash theme={null}
curl -X POST "https://api.1eye.ai/v1/kb/topics" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lakehouse Architecture",
    "short_name": "lakehouse-architecture",
    "description": "Modern data architectures that combine the scalability and flexibility of data lakes with the performance, governance, and SQL analytics capabilities of data warehouses. Organizations researching lakehouse architecture are typically evaluating ways to unify structured and unstructured data, simplify ETL pipelines, support real-time analytics, and enable AI and machine learning workloads on a common data platform. Related concepts include open table formats, Apache Iceberg, Delta Lake, cloud data warehouses, and unified analytics."
  }'
```

### Example Response

**201 Created**

```json theme={null}
{
  "id": "<topic_id>",
  "client_id": "wor_123456789012345678",
  "name": "Lakehouse Architecture",
  "short_name": "lakehouse-architecture",
  "description": "Modern data architectures that combine the scalability and flexibility of data lakes with the performance, governance, and SQL analytics capabilities of data warehouses. Organizations researching lakehouse architecture are typically evaluating ways to unify structured and unstructured data, simplify ETL pipelines, support real-time analytics, and enable AI and machine learning workloads on a common data platform. Related concepts include open table formats, Apache Iceberg, Delta Lake, cloud data warehouses, and unified analytics.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}
```

### Behavior

When a Topic is created:

1. 1eye generates a unique Topic ID.
2. The Topic is associated with your workspace.
3. The Topic appears in the Knowledge Base.
4. The Topic becomes available for future Market Signals processing.
5. The Topic can be retrieved or updated through the API.

**Important:** Creating a Topic does not automatically generate historical Market Signals or trigger new Buyer evaluations.

### Validation

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

***

## 4. Update a Topic

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

Update an existing Topic.

The API supports partial updates.

### 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/topics/$TOPIC_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Unified lakehouse data architectures supporting scalable SQL analytics, data engineering, AI, and machine learning workloads. Organizations exploring this topic are often evaluating the convergence of data warehouses and data lakes, Apache Iceberg or Delta Lake adoption, data governance, platform consolidation, and cloud infrastructure cost optimization."
  }'
```

### Example Response

**200 OK**

```json theme={null}
{
  "id": "<topic_id>",
  "client_id": "wor_123456789012345678",
  "name": "Lakehouse Architecture",
  "short_name": "lakehouse-architecture",
  "description": "Unified lakehouse data architectures supporting scalable SQL analytics, data engineering, AI, and machine learning workloads. Organizations exploring this topic are often evaluating the convergence of data warehouses and data lakes, Apache Iceberg or Delta Lake adoption, data governance, platform consolidation, and cloud infrastructure cost optimization.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:30:00Z"
}
```

### Behavior

* Updates only supplied fields.
* Preserves omitted fields.
* Preserves the original Topic ID.
* Reflects changes in the Console.
* Applies the updated Topic definition to future Market Signals processing.

**Important:** Updating a Topic does not automatically reprocess historical Signals or reevaluate existing Buyers.

***

## 5. Delete a Topic

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

Delete a Topic from your workspace.

Deletion performs a **soft delete**.

### Example Request

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

### Response

**204 No Content**

The response body is empty.

### What Happens When a Topic Is Deleted?

* The Topic is removed from the active Knowledge Base.
* It no longer appears in List Topics.
* Retrieving the deleted Topic returns `404 Not Found`.
* The Topic is excluded from future Market Signals processing.
* Historical Signals associated with the Topic remain preserved.

Deleting a Topic does not delete Buyers, existing Signals, or historical market activity.

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

***

## 6. How Topics Affect Market Signals

Topics help 1eye understand which areas of market research are relevant to your business.

For example, Snowbricks might configure:

| Topic | Market Interest |
| - | - |
| Lakehouse Architecture | Unified analytics platforms |
| Cloud Data Warehousing | Cloud-native data infrastructure |
| Data Pipeline Orchestration | Data engineering modernization |
| AI Infrastructure | AI and machine learning workloads |
| Data Governance | Security, compliance, and data management |

Market Signals can include activities such as:

* `researched_topic`
* `explored_product`
* `evaluated_competitor`

Topics primarily provide context for topic-related Market Signals.

Products and Competitors are configured separately in the Knowledge Base.

### Knowledge Base Integration

| Operation | Impact |
| - | - |
| Create | Topic becomes available for future processing |
| Update | Updated definition is used for future processing |
| Delete | Topic is excluded from future processing |

### Historical Data

Creating, updating, or deleting Topics does not automatically trigger historical signal generation or reevaluation.

Existing records remain preserved.

### Console Synchronization

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

***

## 7. Error Handling

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

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

### Example Error

**404 Not Found**

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

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

***

## 8. Pagination & Rate Limits

List Topics supports cursor-based pagination.

* Default page size: 100.
* Maximum page size: 1,000.
* Use `cursor` for subsequent pages.
* `next_cursor: null` indicates no additional results.

Topic API requests count toward your workspace API rate limits.

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

***

## 9. Best Practices

### Use Specific Topics

Choose topics that describe meaningful areas of customer interest.

Avoid overly broad categories such as "Technology" or "Software."

### Use Consistent Short Names

```text theme={null}
lakehouse-architecture
cloud-data-warehousing
data-pipeline-orchestration
ai-infrastructure
data-governance
```

### Provide Business Context

Descriptions should explain the subject and why companies researching it may be relevant to your business.

### Avoid Unnecessary Overlap

Use distinct Topics that represent different areas of interest.

For example, Lakehouse Architecture and Data Governance are related but represent different evaluation needs.

### Keep Topics Current

Update Topics as new technologies, business needs, and market terminology emerge.

***

## 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 – Topics](/knowledge-base/topics)


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