### List Websets using cURL

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Shows how to retrieve a list of all websets using the Exa Websets API with cURL. This example includes pagination parameters to control the number of results returned. The API returns a paginated list of webset objects.

```bash
curl -X GET "https://api.exa.ai/websets/v0/websets?limit=20" \
  -H "x-api-key: YOUR_EXA_API_KEY"
```

--------------------------------

### Integration Guide

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Overview of the Exa Websets API's capabilities for data discovery and enrichment, including advanced workflows and API features.

```APIDOC
## Integration Guide

### Overview
The Exa Websets API facilitates two primary use cases: data discovery and data enrichment.

### Data Discovery
Create a webset with a natural language search query to find entities across the web. The API automatically interprets queries into searchable criteria and processes results.

### Data Enrichment
Import existing CSV data or reference websets to add new columns of information extracted using AI agents.

### Advanced Workflows
- **Combined Imports and Scoped Searches:** Filter imported datasets using targeted searches.
- **Hop Searches:** Perform graph traversal to find related entities (e.g., "investors of" companies).
- **Monitors:** Set up continuous updates for datasets.

### API Features
- **Pagination:** Supports cursor-based navigation for retrieving large datasets.
- **Progress Tracking:** Provides detailed progress for long-running operations like searches.
- **Webhooks:** Delivers real-time event notifications for integration into existing data pipelines.
```

--------------------------------

### GET /websets/v0/websets - List Websets

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Retrieves a list of all websets associated with the API key, with support for pagination.

```APIDOC
## GET /websets/v0/websets

### Description
Retrieve all websets with pagination support.

### Method
GET

### Endpoint
https://api.exa.ai/websets/v0/websets

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - Your Exa API key.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of websets to return (default is 20).
- **cursor** (string) - Optional - A cursor for fetching the next page of results.

### Request Example
```bash
curl -X GET "https://api.exa.ai/websets/v0/websets?limit=20" \
  -H "x-api-key: YOUR_EXA_API_KEY"
```

### Response
#### Success Response (200 OK)
- **data** (array) - A list of webset objects.
  - Each object contains details like 'id', 'object', 'status', 'externalId', 'title', 'createdAt', 'updatedAt'.
- **hasMore** (boolean) - Indicates if there are more results available.
- **nextCursor** (string) - A cursor to fetch the next page of results, or null if no more results.

#### Response Example
```json
{
  "data": [
    {
      "id": "webset_abc123",
      "object": "webset",
      "status": "idle",
      "externalId": "my-sf-tech-companies",
      "title": "Tech Companies",
      "searches": [],
      "imports": [],
      "enrichments": [],
      "monitors": [],
      "createdAt": "2025-12-03T10:00:00Z",
      "updatedAt": "2025-12-03T10:30:00Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```
```

--------------------------------

### GET /websets/v0/websets/{webset_id}/items

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Retrieve all items within a webset. Supports pagination using `limit` and `cursor` parameters for efficient data retrieval.

```APIDOC
## GET /websets/v0/websets/{webset_id}/items

### Description
Retrieve all items within a specified webset. This endpoint supports pagination to handle large datasets efficiently.

### Method
GET

### Endpoint
`/websets/v0/websets/{webset_id}/items`

### Parameters
#### Path Parameters
- **webset_id** (string) - Required - The ID of the webset to retrieve items from.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of items to return per page. Defaults to 20.
- **cursor** (string) - Optional - A cursor for fetching the next page of results.

#### Request Body
None

### Request Example
```bash
curl -X GET "https://api.exa.ai/websets/v0/websets/webset_abc123/items?limit=20" \
  -H "x-api-key: YOUR_EXA_API_KEY"
```

### Response
#### Success Response (200 OK)
- **data** (array) - An array of webset items.
  - Each item is an object containing details like `id`, `object`, `source`, `sourceId`, `websetId`, `properties`, `evaluations`, `enrichments`, `createdAt`, and `updatedAt`.
- **hasMore** (boolean) - Indicates if there are more items available beyond the current response.
- **nextCursor** (string|null) - A cursor to fetch the next page of results, or null if there are no more pages.

#### Response Example
```json
{
  "data": [
    {
      "id": "item_xyz789",
      "object": "webset_item",
      "source": "search",
      "sourceId": "search_def456",
      "websetId": "webset_abc123",
      "properties": {
        "type": "person",
        "url": "https://linkedin.com/in/johndoe",
        "description": "Marketing executive at tech company",
        "person": {
          "name": "John Doe",
          "location": "San Francisco, CA",
          "position": "VP Marketing",
          "company": {
            "name": "TechCorp",
            "location": "San Francisco, CA"
          },
          "pictureUrl": null
        }
      },
      "evaluations": [
        {
          "criterion": "Works in marketing",
          "reasoning": "Profile indicates VP Marketing position",
          "satisfied": "yes",
          "references": []
        }
      ],
      "enrichments": null,
      "createdAt": "2025-12-03T10:15:00Z",
      "updatedAt": "2025-12-03T10:15:00Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```
```

--------------------------------

### Get Webset by ID using cURL

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Illustrates how to fetch a specific webset by its ID using the Exa Websets API with cURL. This request demonstrates the use of the `expand` query parameter to include associated items in the response. The API returns the details of the specified webset.

```bash
curl -X GET "https://api.exa.ai/websets/v0/websets/webset_abc123?expand[]=items" \
  -H "x-api-key: YOUR_EXA_API_KEY"
```

--------------------------------

### GET /websets/v0/websets/{websetId} - Get Webset by ID

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Retrieves a specific webset by its unique identifier. Supports expanding related items.

```APIDOC
## GET /websets/v0/websets/{websetId}

### Description
Retrieve a specific webset with optional item expansion.

### Method
GET

### Endpoint
https://api.exa.ai/websets/v0/websets/{websetId}

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - Your Exa API key.

#### Path Parameters
- **websetId** (string) - Required - The unique identifier of the webset to retrieve.

#### Query Parameters
- **expand[]** (string) - Optional - Specifies related data to expand, e.g., `expand[]=items` to include webset items.

### Request Example
```bash
curl -X GET "https://api.exa.ai/websets/v0/websets/webset_abc123?expand[]=items" \
  -H "x-api-key: YOUR_EXA_API_KEY"
```

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier of the webset.
- **object** (string) - The type of object, should be 'webset'.
- **status** (string) - The current status of the webset.
- **searches** (array) - List of search configurations.
- **items** (array, optional) - If `expand[]=items` was used, this contains the webset items.
  - Each item object includes 'id', 'object', 'source', 'properties', 'createdAt', 'updatedAt'.

#### Response Example
```json
{
  "id": "webset_abc123",
  "object": "webset",
  "status": "idle",
  "searches": [],
  "items": [
    {
      "id": "item_xyz789",
      "object": "webset_item",
      "source": "search",
      "sourceId": "search_def456",
      "websetId": "webset_abc123",
      "properties": {
        "type": "company",
        "url": "https://example.com",
        "description": "Tech company based in San Francisco",
        "company": {
          "name": "Example Corp",
          "location": "San Francisco, CA",
          "employees": 500,
          "industry": "Technology",
          "about": "Leading SaaS provider"
        }
      },
      "evaluations": [],
      "enrichments": [],
      "createdAt": "2025-12-03T10:15:00Z",
      "updatedAt": "2025-12-03T10:15:00Z"
    }
  ]
}
```
```

--------------------------------

### Create Monitor for Webset

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Sets up an automated monitoring task for a webset to ensure data is kept up-to-date. This includes defining the webset ID, the monitoring cadence using cron syntax and timezone, and the behavior of the monitoring task, such as performing a search. The response confirms the monitor's creation and its schedule.

```bash
curl -X POST https://api.exa.ai/websets/v0/monitors \
  -H "x-api-key: YOUR_EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "websetId": "webset_abc123",
    "cadence": {
      "cron": "0 9 * * 1",
      "timezone": "America/New_York"
    },
    "behavior": {
      "type": "search",
      "config": {
        "query": "new companies to monitor",
        "count": 10,
        "behavior": "append"
      }
    }
  }'
```

--------------------------------

### Preview Webset Search using cURL

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Demonstrates how to preview the decomposition of a search query before creating a webset using the Exa Websets API with cURL. This allows users to understand how their natural language query will be interpreted into structured criteria and enrichment suggestions. The API returns a preview of the search and enrichment configurations.

```bash
curl -X POST https://api.exa.ai/websets/v0/websets/preview \
  -H "x-api-key: YOUR_EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "query": "Marketing agencies based in the US, that focus on consumer products. Get brands worked with and city"
    }
  }'
```

--------------------------------

### Create Webset using cURL

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Demonstrates how to create a new webset using the Exa Websets API with cURL. This includes defining search parameters, enrichment configurations, and an external ID. The API responds with the created webset's details.

```bash
curl -X POST https://api.exa.ai/websets/v0/websets \
  -H "x-api-key: YOUR_EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search": {
      "query": "Tech companies in San Francisco",
      "count": 10
    },
    "enrichments": [
      {
        "description": "Company revenue information",
        "format": "text"
      }
    ],
    "externalId": "my-sf-tech-companies"
  }'
```

--------------------------------

### POST /websets/v0/websets/preview - Preview Webset Search

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Previews how a given search query will be decomposed into search criteria and enrichments before creating a webset.

```APIDOC
## POST /websets/v0/websets/preview

### Description
Preview how a query will be decomposed before creating a webset.

### Method
POST

### Endpoint
https://api.exa.ai/websets/v0/websets/preview

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - Your Exa API key.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **search** (object) - Required - Configuration for the search query preview.
  - **query** (string) - Required - The natural language query to preview.

### Request Example
```json
{
  "search": {
    "query": "Marketing agencies based in the US, that focus on consumer products. Get brands worked with and city"
  }
}
```

### Response
#### Success Response (200 OK)
- **search** (object) - The decomposed search configuration.
  - **entity** (object) - The inferred entity type.
  - **criteria** (array) - A list of criteria derived from the query.
- **enrichments** (array) - A list of suggested enrichments based on the query.
  - Each enrichment object contains 'description' and 'format'.
- **items** (array) - An empty array, as this endpoint is for preview only.

#### Response Example
```json
{
  "search": {
    "entity": {
      "type": "company"
    },
    "criteria": [
      {
        "description": "Based in the United States"
      },
      {
        "description": "Focuses on consumer products"
      }
    ]
  },
  "enrichments": [
    {
      "description": "Brands worked with",
      "format": "text"
    },
    {
      "description": "City location",
      "format": "text"
    }
  ],
  "items": []
}
```
```

--------------------------------

### Create Import for Webset Data

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Initiates an import process for a webset, allowing data to be uploaded via CSV or by referencing existing websets. The first step involves requesting an upload URL by specifying the data format, size, and entity type. The response provides the upload URL and its expiration time.

```bash
# Step 1: Create import to get upload URL
curl -X POST https://api.exa.ai/websets/v0/imports \
  -H "x-api-key: YOUR_EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "size": 1048576,
    "count": 100,
    "title": "Company List",
    "entity": {
      "type": "company"
    },
    "csv": {
      "identifier": 0
    }
  }'
```

```bash
# Step 2: Upload file to returned uploadUrl
# curl -X PUT "<uploadUrl>" --upload-file companies.csv
```

--------------------------------

### POST /websets/v0/imports

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Initiate an import process for a webset, typically for CSV data. This returns an upload URL to which the file should be uploaded.

```APIDOC
## POST /websets/v0/imports

### Description
Create an import job for a webset. This is used to upload data, typically from a CSV file, for enrichment and filtering purposes.

### Method
POST

### Endpoint
`/websets/v0/imports`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **format** (string) - Required - The format of the import data (e.g., "csv").
- **size** (integer) - Required - The expected size of the file in bytes.
- **count** (integer) - Required - The expected number of records in the file.
- **title** (string) - Required - A title for the import job.
- **entity** (object) - Required - Defines the type of entity being imported.
  - **type** (string) - Required - The type of entity (e.g., "company", "person").
- **csv** (object) - Optional - CSV specific configurations.
  - **identifier** (integer) - Optional - Index of the column to use as an identifier in the CSV.

### Request Example
```json
{
  "format": "csv",
  "size": 1048576,
  "count": 100,
  "title": "Company List",
  "entity": {
    "type": "company"
  },
  "csv": {
    "identifier": 0
  }
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The ID of the import job.
- **object** (string) - Type of the object, always "import".
- **status** (string) - The current status of the import (e.g., "pending").
- **format** (string) - The format of the imported data.
- **entity** (object) - The type of entity being imported.
- **title** (string) - The title of the import job.
- **count** (integer) - The number of records expected.
- **metadata** (object) - Any associated metadata.
- **failedReason** (string|null) - Reason if the import failed.
- **failedAt** (string|null) - Timestamp when the import failed.
- **failedMessage** (string|null) - Detailed message if the import failed.
- **createdAt** (string) - Timestamp when the import job was created.
- **updatedAt** (string) - Timestamp when the import job was last updated.
- **uploadUrl** (string) - The URL to which the file should be uploaded.
- **uploadValidUntil** (string) - The expiration timestamp for the upload URL.

#### Response Example
```json
{
  "id": "import_pqr678",
  "object": "import",
  "status": "pending",
  "format": "csv",
  "entity": {
    "type": "company"
  },
  "title": "Company List",
  "count": 100,
  "metadata": {},
  "failedReason": null,
  "failedAt": null,
  "failedMessage": null,
  "createdAt": "2025-12-03T13:00:00Z",
  "updatedAt": "2025-12-03T13:00:00Z",
  "uploadUrl": "https://upload.exa.ai/import_pqr678?signature=...",
  "uploadValidUntil": "2025-12-03T14:00:00Z"
}
```
```

--------------------------------

### POST /websets/v0/monitors

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Create a monitor to automate updates for a webset. Monitors can be scheduled using cron expressions to periodically refresh data.

```APIDOC
## POST /websets/v0/monitors

### Description
Set up automated monitoring to keep websets updated on a schedule. This allows for periodic data refreshes based on defined cadences and behaviors.

### Method
POST

### Endpoint
`/websets/v0/monitors`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **websetId** (string) - Required - The ID of the webset to monitor.
- **cadence** (object) - Required - Defines the schedule for the monitor.
  - **cron** (string) - Required - A cron expression defining the schedule (e.g., "0 9 * * 1" for 9 AM every Monday).
  - **timezone** (string) - Required - The timezone for the cron schedule (e.g., "America/New_York").
- **behavior** (object) - Required - Defines the action to perform on schedule.
  - **type** (string) - Required - The type of behavior, e.g., "search".
  - **config** (object) - Required - Configuration for the behavior type. For "search", this includes `query`, `count`, and `behavior`.
    - **query** (string) - Required - The search query for the monitor.
    - **count** (integer) - Optional - Number of results to fetch.
    - **behavior** (string) - Optional - How to handle results (e.g., `append`).

### Request Example
```json
{
  "websetId": "webset_abc123",
  "cadence": {
    "cron": "0 9 * * 1",
    "timezone": "America/New_York"
  },
  "behavior": {
    "type": "search",
    "config": {
      "query": "new companies to monitor",
      "count": 10,
      "behavior": "append"
    }
  }
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The ID of the created monitor.
- **object** (string) - Type of the object, always "monitor".
- **status** (string) - The current status of the monitor (e.g., "enabled").
- **websetId** (string) - The ID of the webset being monitored.
- **cadence** (object) - The scheduled cadence for the monitor.
- **behavior** (object) - The action performed by the monitor.
- **lastRun** (string|null) - Timestamp of the last time the monitor ran.
- **nextRunAt** (string) - Timestamp for the next scheduled run.
- **metadata** (object) - Any associated metadata.
- **createdAt** (string) - Timestamp when the monitor was created.
- **updatedAt** (string) - Timestamp when the monitor was last updated.

#### Response Example
```json
{
  "id": "monitor_mno345",
  "object": "monitor",
  "status": "enabled",
  "websetId": "webset_abc123",
  "cadence": {
    "cron": "0 9 * * 1",
    "timezone": "America/New_York"
  },
  "behavior": {
    "type": "search",
    "config": {
      "query": "new companies to monitor",
      "count": 10,
      "behavior": "append"
    }
  },
  "lastRun": null,
  "nextRunAt": "2025-12-08T14:00:00Z",
  "metadata": {},
  "createdAt": "2025-12-03T12:00:00Z",
  "updatedAt": "2025-12-03T12:00:00Z"
}
```
```

--------------------------------

### POST /websets/v0/websets - Create a Webset

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Creates a new webset with specified search, import, and enrichment configurations. A webset is a collection of entities discovered through natural language queries.

```APIDOC
## POST /websets/v0/websets

### Description
Create a new webset with search, import, and enrichment configurations.

### Method
POST

### Endpoint
https://api.exa.ai/websets/v0/websets

### Parameters
#### Header Parameters
- **x-api-key** (string) - Required - Your Exa API key.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **search** (object) - Required - Configuration for the search query.
  - **query** (string) - Required - The natural language query to perform.
  - **count** (integer) - Optional - The number of results to retrieve.
- **enrichments** (array) - Optional - A list of enrichment configurations.
  - **description** (string) - Required - Description of the enrichment.
  - **format** (string) - Required - The desired format for the enrichment (e.g., 'text').
- **externalId** (string) - Optional - A custom identifier for the webset.

### Request Example
```json
{
  "search": {
    "query": "Tech companies in San Francisco",
    "count": 10
  },
  "enrichments": [
    {
      "description": "Company revenue information",
      "format": "text"
    }
  ],
  "externalId": "my-sf-tech-companies"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier of the created webset.
- **object** (string) - The type of object, should be 'webset'.
- **status** (string) - The current status of the webset (e.g., 'pending').
- **externalId** (string) - The external ID provided in the request.
- **title** (string) - The title of the webset (can be null).
- **searches** (array) - List of search configurations.
- **imports** (array) - List of import configurations.
- **enrichments** (array) - List of enrichment configurations.
- **monitors** (array) - List of monitor configurations.
- **createdAt** (string) - Timestamp when the webset was created.
- **updatedAt** (string) - Timestamp when the webset was last updated.

#### Response Example
```json
{
  "id": "webset_abc123",
  "object": "webset",
  "status": "pending",
  "externalId": "my-sf-tech-companies",
  "title": null,
  "searches": [],
  "imports": [],
  "enrichments": [],
  "monitors": [],
  "createdAt": "2025-12-03T10:00:00Z",
  "updatedAt": "2025-12-03T10:00:00Z"
}
```
```

--------------------------------

### List Items in Webset

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Retrieves all items within a specified webset, supporting pagination. This endpoint is useful for iterating through the data stored in a webset. The response includes a list of items and pagination controls.

```bash
curl -X GET "https://api.exa.ai/websets/v0/websets/webset_abc123/items?limit=20" \
  -H "x-api-key: YOUR_EXA_API_KEY"
```

--------------------------------

### List System Events - Exa API

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Queries system events with filtering and pagination capabilities. Allows specifying event types and a limit for the number of results returned. Requires an API key for authentication.

```bash
curl -X GET "https://api.exa.ai/websets/v0/events?types[]=webset.created&types[]=webset.search.completed&limit=20" \
  -H "x-api-key: YOUR_EXA_API_KEY"
```

--------------------------------

### Create Webhook

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Subscribe to events for real-time notifications by creating a webhook. This endpoint allows you to specify the URL where event notifications should be sent and the types of events you are interested in.

```APIDOC
## POST /webhooks

### Description
Subscribe to events for real-time notifications.

### Method
POST

### Endpoint
https://api.exa.ai/websets/v0/webhooks

### Parameters
#### Headers
- **x-api-key** (string) - Required - Your Exa API key.
- **Content-Type** (string) - Required - application/json

#### Request Body
- **url** (string) - Required - The URL to receive webhook notifications.
- **events** (array of strings) - Required - A list of event types to subscribe to (e.g., "webset.completed", "enrichment.completed").

### Request Example
```json
{
  "url": "https://api.yourapp.com/webhooks/exa",
  "events": ["webset.completed", "enrichment.completed"]
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier for the webhook.
- **object** (string) - The type of object, always "webhook".
- **status** (string) - The current status of the webhook (e.g., "active").
- **events** (array of strings) - The list of events the webhook is subscribed to.
- **url** (string) - The URL configured for the webhook.
- **secret** (string) - A secret used for verifying webhook authenticity.
- **createdAt** (string) - The timestamp when the webhook was created.
- **updatedAt** (string) - The timestamp when the webhook was last updated.

#### Response Example
```json
{
  "id": "webhook_stu901",
  "object": "webhook",
  "status": "active",
  "events": ["webset.completed", "enrichment.completed"],
  "url": "https://api.yourapp.com/webhooks/exa",
  "secret": "whsec_abc123def456",
  "createdAt": "2025-12-03T14:00:00Z",
  "updatedAt": "2025-12-03T14:00:00Z"
}
```
```

--------------------------------

### Create Webhook Subscription - Exa API

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Subscribes to events for real-time notifications from the Exa API. Requires an API key and specifies the callback URL and events to subscribe to. Returns webhook details including a secret for verification.

```bash
curl -X POST https://api.exa.ai/websets/v0/webhooks \
  -H "x-api-key: YOUR_EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/exa",
    "events": ["webset.completed", "enrichment.completed"]
  }'
```

--------------------------------

### Create Search in Webset

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Adds a new search to an existing webset. This operation requires the webset ID and specifies the search query, the number of results to retrieve, and how to append them. The response includes the new search's ID and status.

```bash
curl -X POST https://api.exa.ai/websets/v0/websets/webset_abc123/searches \
  -H "x-api-key: YOUR_EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "additional companies to add",
    "count": 5,
    "behavior": "append"
  }'
```

--------------------------------

### List Events

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Query system events with filtering and pagination. This endpoint allows you to retrieve a list of events that have occurred, with options to filter by event types and control the number of results.

```APIDOC
## GET /events

### Description
Query system events with filtering and pagination.

### Method
GET

### Endpoint
https://api.exa.ai/websets/v0/events

### Parameters
#### Headers
- **x-api-key** (string) - Required - Your Exa API key.

#### Query Parameters
- **types[]** (array of strings) - Optional - Filter events by their types (e.g., "webset.created", "webset.search.completed").
- **limit** (integer) - Optional - The maximum number of events to return per page. Defaults to 20.

### Request Example
```bash
curl -X GET "https://api.exa.ai/websets/v0/events?types[]=webset.created&types[]=webset.search.completed&limit=20" \
  -H "x-api-key: YOUR_EXA_API_KEY"
```

### Response
#### Success Response (200 OK)
- **data** (array) - A list of event objects.
  - **id** (string) - The unique identifier for the event.
  - **object** (string) - The type of object, always "event".
  - **type** (string) - The type of the event.
  - **data** (object) - The payload of the event, containing details specific to the event type.
  - **createdAt** (string) - The timestamp when the event occurred.
- **hasMore** (boolean) - Indicates if there are more events available.
- **nextCursor** (string | null) - A cursor for fetching the next page of results, or null if there are no more pages.

#### Response Example
```json
{
  "data": [
    {
      "id": "event_vwx234",
      "object": "event",
      "type": "webset.search.completed",
      "data": {
        "id": "search_def456",
        "object": "webset_search",
        "status": "completed",
        "websetId": "webset_abc123",
        "query": "Tech companies in San Francisco",
        "progress": {
          "found": 10,
          "analyzed": 150,
          "completion": 100,
          "timeLeft": 0
        }
      },
      "createdAt": "2025-12-03T10:30:00Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```
```

--------------------------------

### POST /websets/v0/websets/{webset_id}/searches

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Add a new search to an existing webset. This allows you to find and append new data to your webset based on a specified query.

```APIDOC
## POST /websets/v0/websets/{webset_id}/searches

### Description
Add a new search to an existing webset. This operation allows you to append new data to your webset based on a specified query, count, and behavior.

### Method
POST

### Endpoint
`/websets/v0/websets/{webset_id}/searches`

### Parameters
#### Path Parameters
- **webset_id** (string) - Required - The ID of the webset to which the search will be added.

#### Query Parameters
None

#### Request Body
- **query** (string) - Required - The search query to execute.
- **count** (integer) - Optional - The number of results to retrieve for the search. Defaults to 10.
- **behavior** (string) - Optional - Specifies how the search results should be handled. Options: `append` (default), `overwrite`.

### Request Example
```json
{
  "query": "additional companies to add",
  "count": 5,
  "behavior": "append"
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The ID of the newly created search.
- **object** (string) - Type of the object, always "webset_search".
- **status** (string) - The current status of the search (e.g., "pending").
- **websetId** (string) - The ID of the webset associated with this search.
- **query** (string) - The search query that was performed.
- **count** (integer) - The number of results requested.
- **behavior** (string) - The behavior applied to the search results.
- **progress** (object) - Object detailing the progress of the search.
  - **found** (integer) - Number of items found.
  - **analyzed** (integer) - Number of items analyzed.
  - **completion** (number) - Percentage of completion.
  - **timeLeft** (string|null) - Estimated time left for completion.
- **createdAt** (string) - Timestamp when the search was created.
- **updatedAt** (string) - Timestamp when the search was last updated.

#### Response Example
```json
{
  "id": "search_ghi789",
  "object": "webset_search",
  "status": "pending",
  "websetId": "webset_abc123",
  "query": "additional companies to add",
  "count": 5,
  "behavior": "append",
  "progress": {
    "found": 0,
    "analyzed": 0,
    "completion": 0,
    "timeLeft": null
  },
  "createdAt": "2025-12-03T11:00:00Z",
  "updatedAt": "2025-12-03T11:00:00Z"
}
```
```

--------------------------------

### OpenAPI Specification for Websets API

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

The OpenAPI 3.1.0 specification for the Exa Websets API. This document defines the structure and available endpoints for interacting with the API, including request and response formats.

```yaml
openapi: 3.1.0
info:
  title: Exa Websets API
  version: v0
servers:
  - url: https://api.exa.ai/websets/v0
paths:
  /websets:
    post:
      summary: Create a Webset
      operationId: createWebset
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebsetCreateRequest'
      responses:
        '201':
          description: Webset created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webset'
    get:
      summary: List Websets
      operationId: listWebsets
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A list of websets
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webset'
                  hasMore:
                    type: boolean
                  nextCursor:
                    type: string
  /websets/{websetId}:
    get:
      summary: Get Webset by ID
      operationId: getWebsetById
      parameters:
        - name: websetId
          in: path
          required: true
          schema:
            type: string
        - name: expand
          in: query
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Webset details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webset'
  /websets/preview:
    post:
      summary: Preview Webset Search
      operationId: previewWebsetSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebsetPreviewRequest'
      responses:
        '200':
          description: Preview of search decomposition
          content:
            application/json:
              schema:
                type: object
                properties:
                  search:
                    type: object
                    properties:
                      entity:
                        type: object
                        properties:
                          type:
                            type: string
                      criteria:
                        type: array
                        items:
                          type: object
                          properties:
                            description:
                              type: string
                  enrichments:
                    type: array
                    items:
                      type: object
                      properties:
                        description:
                          type: string
                        format:
                          type: string
                  items:
                    type: array
components:
  schemas:
    WebsetCreateRequest:
      type: object
      properties:
        search:
          $ref: '#/components/schemas/SearchConfig'
        enrichments:
          type: array
          items:
            $ref: '#/components/schemas/EnrichmentConfig'
        externalId:
          type: string
        title:
          type: string
    WebsetPreviewRequest:
      type: object
      properties:
        search:
          $ref: '#/components/schemas/SearchConfig'
    SearchConfig:
      type: object
      properties:
        query:
          type: string
        count:
          type: integer
    EnrichmentConfig:
      type: object
      properties:
        description:
          type: string
        format:
          type: string
    Webset:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        status:
          type: string
        externalId:
          type: string
        title:
          type: string
        searches:
          type: array
          items: {}
        imports:
          type: array
          items: {}
        enrichments:
          type: array
          items: {}
        monitors:
          type: array
          items: {}
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: '#/components/schemas/WebsetItem'
    WebsetItem:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        source:
          type: string
        sourceId:
          type: string
        websetId:
          type: string
        properties:
          type: object
          properties:
            type:
              type: string
            url:
              type: string
            description:
              type: string
            company:
              type: object
              properties:
                name:
                  type: string
                location:
                  type: string
                employees:
                  type: integer
                industry:
                  type: string
                about:
                  type: string
        evaluations:
          type: array
          items: {}
        enrichments:
          type: array
          items: {}
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
```

--------------------------------

### Create Enrichment Column in Webset

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Adds a new enrichment column to a webset, designed to extract specific types of data from webset items. This involves defining the column's description and data format. The response confirms the creation of the enrichment, including its ID and status.

```bash
curl -X POST https://api.exa.ai/websets/v0/websets/webset_abc123/enrichments \
  -H "x-api-key: YOUR_EXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Company revenue information",
    "format": "number"
  }'
```

--------------------------------

### POST /websets/v0/websets/{webset_id}/enrichments

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

Add an enrichment to a webset. This defines a new column to extract specific data from webset items, such as revenue or contact information.

```APIDOC
## POST /websets/v0/websets/{webset_id}/enrichments

### Description
Add an enrichment column to a webset. This allows you to define a new field to extract specific data from webset items.

### Method
POST

### Endpoint
`/websets/v0/websets/{webset_id}/enrichments`

### Parameters
#### Path Parameters
- **webset_id** (string) - Required - The ID of the webset to add the enrichment to.

#### Query Parameters
None

#### Request Body
- **description** (string) - Required - A description of the data to be enriched.
- **format** (string) - Required - The expected data format (e.g., "number", "text", "email").
- **title** (string) - Optional - A title for the enrichment column. If not provided, it will be inferred from the description.
- **options** (object) - Optional - Additional options for the enrichment (e.g., specific extraction rules).
- **instructions** (string) - Optional - Specific instructions for the AI model on how to perform the enrichment.

### Request Example
```json
{
  "description": "Company revenue information",
  "format": "number"
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The ID of the newly created enrichment.
- **object** (string) - Type of the object, always "webset_enrichment".
- **status** (string) - The current status of the enrichment (e.g., "pending").
- **websetId** (string) - The ID of the webset associated with this enrichment.
- **title** (string) - The title of the enrichment column.
- **description** (string) - The description of the enrichment.
- **format** (string) - The data format of the enrichment.
- **options** (object|null) - Additional options configured for the enrichment.
- **instructions** (string) - Specific instructions provided for the enrichment.
- **createdAt** (string) - Timestamp when the enrichment was created.
- **updatedAt** (string) - Timestamp when the enrichment was last updated.

#### Response Example
```json
{
  "id": "enrich_jkl012",
  "object": "webset_enrichment",
  "status": "pending",
  "websetId": "webset_abc123",
  "title": "Revenue",
  "description": "Company revenue information",
  "format": "number",
  "options": null,
  "instructions": "Extract the annual revenue of the company",
  "createdAt": "2025-12-03T11:30:00Z",
  "updatedAt": "2025-12-03T11:30:00Z"
}
```
```

--------------------------------

### Validate OpenAPI Specification - TypeScript Utility

Source: https://context7.com/samihalawa/openapi-spec/llms.txt

A TypeScript utility for validating OpenAPI specifications before client generation. It performs basic structure validation, reference resolution, discriminator property checks, and detects unused schemas. The tool can be run via npm scripts and supports a strict mode.

```typescript
import { OpenAPIValidator } from './validate-openapi';

// Validate a single spec file
const validator = new OpenAPIValidator('exa-websets-spec.yaml');
const isValid = validator.validate();

if (!isValid) {
  console.error('Validation failed');
  process.exit(1);
}
```