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

# Target Pages

Manage Target Pages programmatically using the 1eye API. Create, retrieve, update, and delete Target Pages to identify the website pages that matter most to your business.

Target Pages are part of the 1eye Knowledge Base. They help 1eye understand which website visits indicate meaningful buying interest, such as visits to pricing, product, or demo pages.

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

## Base URL

All Target Page API requests use:

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

## 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/target-pages` | List Target Pages |
| `GET` | `/v1/kb/target-pages/{id}` | Retrieve a Target Page |
| `POST` | `/v1/kb/target-pages` | Create a Target Page |
| `PATCH` | `/v1/kb/target-pages/{id}` | Update a Target Page |
| `DELETE` | `/v1/kb/target-pages/{id}` | Delete a Target Page |

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

***

## Target Page Object

A Target Page identifies a webpage that represents meaningful visitor interest.

For example, Snowbricks, a fictional cloud data and AI platform, might track visits to its pricing page because visitors reviewing pricing are often evaluating data infrastructure solutions.

### Fields

| Field | Type | Description |
| - | - | - |
| `name` | string | Descriptive name of the Target Page |
| `short_name` | string | Unique short identifier |
| `url` | string | Website URL to track |
| `description` | string | Explanation of why visits to this page matter |

### Example Target Page

```json theme={null}
{
  "name": "Pricing",
  "short_name": "pricing",
  "url": "snowbricks.io/pricing",
  "description": "High-intent page where prospective customers evaluate Snowbricks pricing, consumption-based billing, and plans for cloud data warehousing, lakehouse analytics, and AI workloads."
}
```

### System-Managed Fields

1eye automatically generates and maintains additional fields.

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

These fields are read-only.

***

## 1. List Target Pages

`GET /v1/kb/target-pages`

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

### Example Request

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

### Example Response

**200 OK**

```json theme={null}
{
  "data": [
    {
      "id": "<target_page_id>",
      "client_id": "wor_123456789012345678",
      "name": "Pricing",
      "short_name": "pricing",
      "url": "snowbricks.io/pricing",
      "description": "High-intent page where prospective customers evaluate Snowbricks pricing, consumption-based billing, and plans for cloud data warehousing, lakehouse analytics, and AI workloads.",
      "created_at": "2026-10-18T18:00:00Z",
      "updated_at": "2026-10-18T18:00: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/target-pages?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 Target Pages belonging to the authenticated workspace.
* Excludes deleted Target Pages.
* Supports cursor-based pagination.
* Returns an empty `data` array when no records exist.

***

## 2. Retrieve a Target Page

`GET /v1/kb/target-pages/{id}`

Retrieve a Target Page using its unique identifier.

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Target Page identifier |

### Example Request

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

### Example Response

**200 OK**

```json theme={null}
{
  "id": "<target_page_id>",
  "client_id": "wor_123456789012345678",
  "name": "Pricing",
  "short_name": "pricing",
  "url": "snowbricks.io/pricing",
  "description": "High-intent page where prospective customers evaluate Snowbricks pricing, consumption-based billing, and plans for cloud data warehousing, lakehouse analytics, and AI workloads.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}
```

### Behavior

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

***

## 3. Create a Target Page

`POST /v1/kb/target-pages`

Create a new Target Page in your workspace.

### Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | Target Page name |
| `short_name` | string | Yes | Unique short identifier |
| `url` | string | Yes | Website URL |
| `description` | string | Yes | Description of the page's significance |

### Example Request

```bash theme={null}
curl -X POST "https://api.1eye.ai/v1/kb/target-pages" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pricing",
    "short_name": "pricing",
    "url": "snowbricks.io/pricing",
    "description": "High-intent page where prospective customers evaluate Snowbricks pricing, consumption-based billing, and plans for cloud data warehousing, lakehouse analytics, and AI workloads."
  }'
```

### Example Response

**201 Created**

```json theme={null}
{
  "id": "<target_page_id>",
  "client_id": "wor_123456789012345678",
  "name": "Pricing",
  "short_name": "pricing",
  "url": "snowbricks.io/pricing",
  "description": "High-intent page where prospective customers evaluate Snowbricks pricing, consumption-based billing, and plans for cloud data warehousing, lakehouse analytics, and AI workloads.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:00:00Z"
}
```

### Behavior

When a Target Page is created:

1. 1eye generates a unique identifier.
2. The Target Page is associated with your workspace.
3. It appears in the Knowledge Base.
4. It becomes available to the Website Signals processing pipeline.
5. It can be retrieved or updated through the API.

**Important:** Creating a Target Page does not generate historical Website Signals or retroactively process previous visits.

### Validation

* All four fields must contain valid values.
* `short_name` must be unique among active Target Pages in the workspace.
* `url` must identify a valid website location.
* System-managed fields cannot be supplied in the request.

***

## 4. Update a Target Page

`PATCH /v1/kb/target-pages/{id}`

Update an existing Target Page.

The API supports partial updates. Only supplied fields are modified.

### Request Body

| Field | Type | Required |
| - | - | - |
| `name` | string | No |
| `short_name` | string | No |
| `url` | 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/target-pages/$TARGET_PAGE_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "High-intent commercial evaluation page where prospective Snowbricks customers compare pricing, compute consumption, storage costs, and enterprise data platform plans."
  }'
```

### Example Response

**200 OK**

```json theme={null}
{
  "id": "<target_page_id>",
  "client_id": "wor_123456789012345678",
  "name": "Pricing",
  "short_name": "pricing",
  "url": "snowbricks.io/pricing",
  "description": "High-intent commercial evaluation page where prospective Snowbricks customers compare pricing, compute consumption, storage costs, and enterprise data platform plans.",
  "created_at": "2026-10-18T18:00:00Z",
  "updated_at": "2026-10-18T18:30:00Z"
}
```

### Behavior

* Updates only supplied fields.
* Preserves the original resource identifier.
* Reflects changes in the Console.
* Applies the updated configuration to future Website Signals processing.
* Does not automatically reprocess historical visits.

***

## 5. Delete a Target Page

`DELETE /v1/kb/target-pages/{id}`

Delete a Target Page from your workspace.

Deletion performs a **soft delete**, preserving historical data.

### Example Request

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

### Response

**204 No Content**

The response body is empty.

### What Happens When a Target Page Is Deleted?

* The Target Page disappears from the active Knowledge Base.
* It is excluded from future Target Page matching.
* It no longer appears in List Target Pages.
* Retrieving the deleted record returns `404 Not Found`.
* Historical Website Signals remain preserved.

Deleting a Target Page does not delete Buyers, historical visits, or previously generated Signals.

Website visits may continue to be collected by the installed 1eye pixel. Deleting a Target Page only removes its active targeting configuration.

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

***

## 6. URL Matching & Normalization

1eye uses canonical URL matching to identify configured Target Pages.

Customers provide the page URL. 1eye handles normalization internally.

### URL Normalization

1eye normalizes URLs to avoid differences caused by:

* `http` versus `https`.
* Hostname capitalization.
* Unnecessary trailing slashes.
* URL fragments.
* Tracking parameters such as `utm_source`, `utm_medium`, `gclid`, and `fbclid`.

Meaningful path segments and query parameters that identify distinct pages are preserved.

### Example

The following URLs should resolve to the same Target Page:

```text theme={null}
https://snowbricks.io/pricing
https://snowbricks.io/pricing/
https://snowbricks.io/pricing?utm_source=google
snowbricks.io/pricing
```

### Exact Canonical Matching

Target Pages use exact matching against the normalized canonical URL.

There is no configurable `match_type` field.

There is also no need to supply a separate `domain` field. The domain is derived from the URL.

### Target Page vs. Target Form

A Target Page represents a page visit.

A Target Form represents a form submission.

**Visiting a page containing a form does not, by itself, mean the visitor submitted that form.**

***

## 7. Error Handling

All Target Page endpoints use the standard 1eye API error format.

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

### Example Error

**404 Not Found**

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

For more information, see [Errors](/api-reference/errors).

***

## 8. Pagination & Rate Limits

List Target Pages uses the existing cursor-based pagination system.

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

Target Page requests count toward your workspace API rate limits.

Rate limits are shared across API keys within the same workspace.

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

***

## 9. How Target Pages Affect Website Signals

Target Pages help 1eye identify website activity associated with meaningful buying interest.

For example, Snowbricks might configure:

| Target Page | Buying Intent |
| - | - |
| Pricing | Commercial evaluation |
| Enterprise | Enterprise platform evaluation |
| Data Warehousing | Product research |
| AI & Machine Learning | AI infrastructure interest |

### Knowledge Base Integration

| Operation | Impact |
| - | - |
| Create | New page becomes available for future matching |
| Update | Updated page definition is used for future matching |
| Delete | Page is excluded from future Target Page matching |

### Console Synchronization

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

***

## 10. Best Practices

### Track High-Intent Pages

Prioritize pages that indicate meaningful buying interest, such as pricing, product, integrations, and demo pages.

### Use Descriptive Names

Choose names that identify the purpose of the page.

Examples:

```text theme={null}
Pricing
Enterprise
Data Warehousing
AI & Machine Learning
```

### Use Consistent Short Names

```text theme={null}
pricing
enterprise
data-warehousing
ai-machine-learning
```

### Write Meaningful Descriptions

Explain what the page represents and why visiting it matters.

A description should provide useful business context rather than simply repeat the page title.

### Use Canonical URLs

Provide the primary page URL without unnecessary campaign or tracking parameters.

1eye handles canonical normalization automatically.

### Delete Carefully

Deleting a Target Page removes its active targeting configuration. Historical Signals remain available.

***

## 11. 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 – Target Pages](/knowledge-base/target-pages)


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