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

Manage Competitors programmatically using the 1eye API. Create, retrieve, update, and delete Competitors to define the companies that compete with your business. Competitors are part of the 1eye Knowledge Base. They help 1eye identify buying activity related to competing products and services, including competitor research and relevant LinkedIn activity. Changes made through the API are reflected in the 1eye Console, and vice versa.

Base URL

All Competitor API requests use:

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

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/competitors`	List Competitors
`GET`	`/v1/kb/competitors/{id}`	Retrieve a Competitor
`POST`	`/v1/kb/competitors`	Create a Competitor
`PATCH`	`/v1/kb/competitors/{id}`	Update a Competitor
`DELETE`	`/v1/kb/competitors/{id}`	Delete a Competitor

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

Competitor Object

A Competitor represents a company offering products or services that compete with your business. For example, Snowbricks, a fictional cloud data and AI platform, might identify Databricks as a competitor because both platforms serve organizations building modern data infrastructure, analytics, and AI applications.

Fields

Field	Type	Description
`name`	string	Competitor company name
`short_name`	string	Unique short identifier
`domain`	string	Competitor’s primary website domain
`linkedin`	string	LinkedIn company page URL
`logo`	string	Company logo URL
`description`	string	Description of the competitor and its relevance to your business

linkedin and logo are optional when creating a Competitor.

Example Competitor

{
  "name": "Databricks",
  "short_name": "databricks",
  "domain": "databricks.com",
  "linkedin": "linkedin.com/company/databricks",
  "logo": "https://cdn.jsdelivr.net/npm/simple-icons@v15/icons/databricks.svg",
  "description": "Databricks provides a unified data intelligence platform combining lakehouse architecture, data engineering, SQL analytics, machine learning, and AI capabilities. It directly competes with Snowbricks for organizations modernizing cloud data infrastructure, consolidating data warehouses and data lakes, and building AI applications. Data engineering leaders, analytics executives, and AI platform teams evaluating Snowbricks could realistically consider Databricks as an alternative."
}

System-Managed Fields

1eye automatically generates and maintains additional fields.

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

These fields are read-only. Competitor identifiers use the cmp_ prefix.

1. List Competitors

GET /v1/kb/competitors Retrieve a paginated list of Competitors 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

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

Example Response

200 OK

{
  "data": [
    {
      "id": "cmp_363625571470372864",
      "client_id": "wor_123456789012345678",
      "name": "Databricks",
      "short_name": "databricks",
      "domain": "databricks.com",
      "linkedin": "linkedin.com/company/databricks",
      "logo": "https://cdn.jsdelivr.net/npm/simple-icons@v15/icons/databricks.svg",
      "description": "Databricks provides a unified data intelligence platform combining lakehouse architecture, data engineering, SQL analytics, machine learning, and AI capabilities. It directly competes with Snowbricks for modern cloud data infrastructure.",
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-18T18:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null
  }
}

Pagination

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

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

A null cursor indicates the end of the collection. See Pagination.

Behavior

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

2. Retrieve a Competitor

GET /v1/kb/competitors/{id} Retrieve a specific Competitor using its unique identifier.

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Competitor identifier

Example Request

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

Example Response

200 OK

{
  "id": "cmp_363625571470372864",
  "client_id": "wor_123456789012345678",
  "name": "Databricks",
  "short_name": "databricks",
  "domain": "databricks.com",
  "linkedin": "linkedin.com/company/databricks",
  "logo": "https://cdn.jsdelivr.net/npm/simple-icons@v15/icons/databricks.svg",
  "description": "Databricks provides a unified data intelligence platform combining lakehouse architecture, data engineering, SQL analytics, machine learning, and AI capabilities. It directly competes with Snowbricks for organizations modernizing cloud data infrastructure, consolidating data warehouses and data lakes, and building AI applications. Data engineering leaders, analytics executives, and AI platform teams evaluating Snowbricks could realistically consider Databricks as an alternative.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}

Behavior

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

3. Create a Competitor

POST /v1/kb/competitors Create a new Competitor in your workspace. New Competitors become available for future competitor-related Signal processing.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Competitor company name
`short_name`	string	Yes	Unique short identifier
`domain`	string	Yes	Company website domain
`linkedin`	string	No	LinkedIn company page
`logo`	string	No	Company logo URL
`description`	string	No	Competitor description

Example Request

curl -X POST "https://api.1eye.ai/v1/kb/competitors" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Databricks",
    "short_name": "databricks",
    "domain": "databricks.com"  
}'

Example Response

201 Created

{
  "id": "cmp_363625571470372864",
  "client_id": "wor_123456789012345678",
  "name": "Databricks",
  "short_name": "databricks",
  "domain": "databricks.com",
  "linkedin": "linkedin.com/company/databricks",
  "logo": "https://cdn.jsdelivr.net/npm/simple-icons@v15/icons/databricks.svg",
  "description": "Databricks provides a unified data intelligence platform combining lakehouse architecture, data engineering, SQL analytics, machine learning, and AI capabilities. It directly competes with Snowbricks for organizations modernizing cloud data infrastructure, consolidating data warehouses and data lakes, and building AI applications. Data engineering leaders, analytics executives, and AI platform teams evaluating Snowbricks could realistically consider Databricks as an alternative.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}

Behavior

When a Competitor is created:

1eye generates a unique Competitor ID.
The Competitor is associated with your workspace.
The Competitor appears in the Knowledge Base.
Its configuration becomes available for future competitor-related Signal processing.
It can be retrieved or updated through the API.

Important: Creating a Competitor does not automatically generate historical Signals or initiate new Buyer evaluations.

Validation

name must not be empty.
short_name must not be empty.
domain must be a valid website domain.
description must not be empty.
linkedin, when supplied, must be a valid LinkedIn company URL.
logo, when supplied, must be a valid image URL.
short_name must be unique among active Competitors in the workspace.
System-managed fields cannot be supplied.

4. Update a Competitor

PATCH /v1/kb/competitors/{id} Update an existing Competitor. Only supplied fields are modified.

Request Body

Field	Type	Required
`name`	string	No
`short_name`	string	No
`domain`	string	No
`linkedin`	string	No
`logo`	string	No
`description`	string	No

At least one editable field must be supplied.

Example Request

curl -X PATCH "https://api.1eye.ai/v1/kb/competitors/$COMPETITOR_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Databricks is a direct competitor to Snowbricks in unified data platforms, lakehouse analytics, data engineering, SQL warehousing, and enterprise AI infrastructure. Both platforms target data engineering leaders, analytics executives, and AI teams seeking to consolidate data workloads, modernize cloud infrastructure, and reduce platform complexity."
  }'

Example Response

200 OK

{
  "id": "cmp_363625571470372864",
  "client_id": "wor_123456789012345678",
  "name": "Databricks",
  "short_name": "databricks",
  "domain": "databricks.com",
  "linkedin": "linkedin.com/company/databricks",
  "logo": "https://cdn.jsdelivr.net/npm/simple-icons@v15/icons/databricks.svg",
  "description": "Databricks is a direct competitor to Snowbricks in unified data platforms, lakehouse analytics, data engineering, SQL warehousing, and enterprise AI infrastructure. Both platforms target data engineering leaders, analytics executives, and AI teams seeking to consolidate data workloads, modernize cloud infrastructure, and reduce platform complexity.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:30:00Z"
}

Behavior

Supports partial updates.
Preserves omitted fields.
Preserves the original Competitor ID.
Updates modification metadata.
Reflects changes in the Console.
Uses updated information for future processing.

Important: Updating a Competitor does not automatically regenerate historical Signals.

5. Delete a Competitor

DELETE /v1/kb/competitors/{id} Delete a Competitor from your workspace. Deletion performs a soft delete.

Example Request

curl -X DELETE "https://api.1eye.ai/v1/kb/competitors/$COMPETITOR_ID" \
  -H "Authorization: Bearer $API_KEY"

Response

204 No Content The response body is empty.

What Happens When a Competitor Is Deleted?

The Competitor is removed from the active Knowledge Base.
It no longer appears in List Competitors.
Retrieving the deleted record returns 404 Not Found.
It is excluded from future competitor-specific processing associated with that configuration.
Historical competitor-related Signals remain preserved.

Deleting a Competitor does not delete Buyers, historical Signals, or previously generated evaluation results. Restoring deleted Competitors is not currently exposed through the public API.

6. How Competitors Affect Signal Intelligence

Competitor definitions help 1eye recognize relevant competitive buying activity. For example, Snowbricks might monitor:

Competitor	Competitive Area
Databricks	Lakehouse and AI infrastructure
Snowflake	Cloud data warehousing and analytics
Google BigQuery	Cloud-native analytical warehousing
Amazon Redshift	AWS data warehousing

Market Signals

Competitor-related Market Signals may identify activity such as: evaluated_competitor This can indicate that a potential buyer is actively comparing solutions in your product category.

LinkedIn Signals

Competitor configurations also provide context for LinkedIn activities such as:

followed_page
commented_post
reacted_post
authored_post

These activities are considered when supported by 1eye’s existing LinkedIn Signals infrastructure.

Competitors vs. Exclusions

Competitors and Exclusions serve different purposes.

Resource	Purpose
Competitors	Identify relevant competitive buying activity
Exclusions	Prevent companies from qualifying as active targets

Adding a Competitor does not automatically exclude that company. If you also want to exclude a competitor from targeting, configure it separately under Exclusions.

Console Synchronization

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

7. Error Handling

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

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

Example Error

404 Not Found

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

See Errors.

8. Pagination & Rate Limits

List Competitors 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.

Competitor API requests count toward your workspace API rate limits. See Pagination and Rate Limits.

9. Best Practices

Track Direct Competitors

Prioritize companies that your customers realistically consider as alternatives. Avoid adding unrelated businesses merely because they operate in the same broad industry.

Use Accurate Domains and LinkedIn URLs

Correct company identifiers help 1eye associate relevant activities with the intended company.

Write Competitive Descriptions

Explain:

What the competitor sells.
Where its products overlap with yours.
Which customer segments both companies target.
Why a potential customer might evaluate both platforms.

Use Consistent Short Names

databricks
snowflake
google-bigquery
amazon-redshift

Keep Competitor Information Current

Update definitions when competitors launch new products, enter new markets, or change their positioning.

​Base URL

​Authentication

​Endpoints

​Competitor Object

​Fields

​Example Competitor

​System-Managed Fields

​1. List Competitors

​Query Parameters

​Example Request

​Example Response

​Pagination

​Behavior

​2. Retrieve a Competitor

​Path Parameters

​Example Request

​Example Response

​Behavior

​3. Create a Competitor

​Request Body

​Example Request

​Example Response

​Behavior

​Validation

​4. Update a Competitor

​Request Body

​Example Request

​Example Response

​Behavior

​5. Delete a Competitor

​Example Request

​Response

​What Happens When a Competitor Is Deleted?

​6. How Competitors Affect Signal Intelligence

​Market Signals

​LinkedIn Signals

​Competitors vs. Exclusions

​Console Synchronization

​7. Error Handling

​Example Error

​8. Pagination & Rate Limits

​9. Best Practices

​Track Direct Competitors

​Use Accurate Domains and LinkedIn URLs

​Write Competitive Descriptions

​Use Consistent Short Names

​Keep Competitor Information Current

​10. Related Documentation

Base URL

Authentication

Endpoints

Competitor Object

Fields

Example Competitor

System-Managed Fields

1. List Competitors

Query Parameters

Example Request

Example Response

Pagination

Behavior

2. Retrieve a Competitor

Path Parameters

Example Request

Example Response

Behavior

3. Create a Competitor

Request Body

Example Request

Example Response

Behavior

Validation

4. Update a Competitor

Request Body

Example Request

Example Response

Behavior

5. Delete a Competitor

Example Request

Response

What Happens When a Competitor Is Deleted?

6. How Competitors Affect Signal Intelligence

Market Signals

LinkedIn Signals

Competitors vs. Exclusions

Console Synchronization

7. Error Handling

Example Error

8. Pagination & Rate Limits

9. Best Practices

Track Direct Competitors

Use Accurate Domains and LinkedIn URLs

Write Competitive Descriptions

Use Consistent Short Names

Keep Competitor Information Current

10. Related Documentation