1eye Docs – Buyer Signals API, Webhooks, MCP & Integrations

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:

https://api.1eye.ai/v1/kb/topics

Authentication

All endpoints require a valid 1eye API key.

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.

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

{
  "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

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

Example Response

200 OK

{
  "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.

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.

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

curl "https://api.1eye.ai/v1/kb/topics/$TOPIC_ID" \
  -H "Authorization: Bearer $API_KEY"

Example Response

200 OK

{
  "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

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

{
  "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:

1eye generates a unique Topic ID.
The Topic is associated with your workspace.
The Topic appears in the Knowledge Base.
The Topic becomes available for future Market Signals processing.
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

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

{
  "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

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

{
  "error": {
    "code": "not_found",
    "message": "Topic not found.",
    "request_id": "req_359051753366339585"
  }
}

See 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 and 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

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.

​Base URL

​Authentication

​Endpoints

​Topic Object

​Fields

​Example Topic

​System-Managed Fields

​1. List Topics

​Query Parameters

​Example Request

​Example Response

​Pagination

​Behavior

​2. Retrieve a Topic

​Path Parameters

​Example Request

​Example Response

​Behavior

​3. Create a Topic

​Request Body

​Example Request

​Example Response

​Behavior

​Validation

​4. Update a Topic

​Request Body

​Example Request

​Example Response

​Behavior

​5. Delete a Topic

​Example Request

​Response

​What Happens When a Topic Is Deleted?

​6. How Topics Affect Market Signals

​Knowledge Base Integration

​Historical Data

​Console Synchronization

​7. Error Handling

​Example Error

​8. Pagination & Rate Limits

​9. Best Practices

​Use Specific Topics

​Use Consistent Short Names

​Provide Business Context

​Avoid Unnecessary Overlap

​Keep Topics Current

​10. Related Documentation

Base URL

Authentication

Endpoints

Topic Object

Fields

Example Topic

System-Managed Fields

1. List Topics

Query Parameters

Example Request

Example Response

Pagination

Behavior

2. Retrieve a Topic

Path Parameters

Example Request

Example Response

Behavior

3. Create a Topic

Request Body

Example Request

Example Response

Behavior

Validation

4. Update a Topic

Request Body

Example Request

Example Response

Behavior

5. Delete a Topic

Example Request

Response

What Happens When a Topic Is Deleted?

6. How Topics Affect Market Signals

Knowledge Base Integration

Historical Data

Console Synchronization

7. Error Handling

Example Error

8. Pagination & Rate Limits

9. Best Practices

Use Specific Topics

Use Consistent Short Names

Provide Business Context

Avoid Unnecessary Overlap

Keep Topics Current

10. Related Documentation