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

# Competitors

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:

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

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

```json theme={null}
{
  "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

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

### Example Response

**200 OK**

```json theme={null}
{
  "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.

```bash theme={null}
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](/api-reference/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

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

### Example Response

**200 OK**

```json theme={null}
{
  "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

```bash theme={null}
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**

```json theme={null}
{
  "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:

1. 1eye generates a unique Competitor ID.
2. The Competitor is associated with your workspace.
3. The Competitor appears in the Knowledge Base.
4. Its configuration becomes available for future competitor-related Signal processing.
5. 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

```bash theme={null}
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**

```json theme={null}
{
  "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

```bash theme={null}
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**

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

See [Errors](/api-reference/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](/api-reference/pagination) and [Rate Limits](/api-reference/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

```text theme={null}
databricks
snowflake
google-bigquery
amazon-redshift
```

### Keep Competitor Information Current

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

***

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


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