### Build Dataset Request Body Examples (JSON)

Source: https://docs.riveterhq.com/

Examples of request bodies for the build_dataset API endpoint. The first demonstrates building a dataset using a natural language prompt, while the second shows how to define a dataset using a structured specification with identifiers, qualifiers, and attributes.

```json
{
  "prompt": "Top 50 SaaS companies by revenue",
  "max_items": 50
}
```

```json
{
  "identifiers": ["Company Name"],
  "qualifiers": ["B2B SaaS", "revenue > $10M"],
  "attributes": ["CEO", "Headquarters"],
  "max_items": 50
}
```

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

### Initiate Data Enrichment Run (POST /run_new_enrichment)

Source: https://docs.riveterhq.com/

This snippet demonstrates how to initiate a new data enrichment run using the Riveter API. It shows how to provide input data, specify enrichment preferences (either prompt/attributes or output), and includes example headers and body for a cURL request. The response indicates the status of the initiated run.

```shell
curl 'https://api.riveterhq.com/v1/run_new_enrichment?run_key=&webhook_url=' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{ 
  "input": { 
    "Company Name": [ 
      "Acme Corp", 
      "Tech Solutions Inc" 
    ], 
    "Website": [ 
      "acme.com", 
      "techsolutions.com" 
    ] 
  }, 
  "prompt": "Find key business information about these companies", 
  "attributes": [ 
    "Employee Count", 
    "Industry", 
    "Annual Revenue", 
    "CEO" 
  ] 
}'
```

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

### Scrape Webpage Content with Curl

Source: https://docs.riveterhq.com/

This example shows how to scrape the text content from a given URL using a cURL command. It requires an API key for authentication and specifies the URL to be scraped. Optional parameters like proxy country code and cache skipping can be included. The response contains the extracted text and metadata about the scrape.

```Shell
curl https://api.riveterhq.com/v1/scrape \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "url": "https://example.com"
}'
```

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

### GET /account

Source: https://docs.riveterhq.com/

Retrieve information about the current account associated with the provided API key, including plan details and API key metadata.

```APIDOC
## GET /account

### Description
Retrieve information about the current account associated with the API key.

### Method
GET

### Endpoint
/account

### Request Example
curl https://api.riveterhq.com/v1/account \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

### Response
#### Success Response (200)
- **account** (object) - Account details including UUID, name, plan, and credit balance.
- **api_key_info** (object) - Metadata regarding the API key used.

#### Response Example
{
  "account": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "string",
    "plan": "free",
    "credit": {
      "count": 1,
      "max": 1,
      "balance": 1
    }
  },
  "api_key_info": {
    "name": "string",
    "last_used_at": null,
    "created_by": {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "name": "string",
      "email": "hello@example.com"
    }
  }
}
```

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

### GET /run_data

Source: https://docs.riveterhq.com/

Retrieve the final results of a completed enrichment or dataset build.

```APIDOC
## GET /run_data

### Description
Retrieve the final results of a completed enrichment or dataset build. This endpoint should only be called after confirming the run status is 'completed'.

### Method
GET

### Endpoint
/v1/run_data

### Parameters
#### Query Parameters
- **run_key** (string) - Required - The unique key for a completed enrichment run.
- **build_key** (string) - Required - The unique key for a completed dataset build.
  *Note: Provide either `run_key` or `build_key`.

### Response
#### Success Response (200)
- **request_status** (string) - Indicates the status of the run ('success' or 'error').
- **formatted_data** (object) - The enrichment or dataset results.
  - **[Column Name]** (array of objects) - An array of objects, each containing a 'value' field for the data in that column.

#### Response Example
```json
{
  "request_status": "success",
  "formatted_data": {
    "Company": [{"value": "Apple"}, {"value": "Google"}],
    "Revenue": [{"value": "383000000000"}, {"value": "307000000000"}]
  }
}
```
```

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

### GET /build_dataset_status

Source: https://docs.riveterhq.com/

Check the current status of a dataset build using its run_key.

```APIDOC
## GET /build_dataset_status

### Description
Check the current status of a dataset build.

### Method
GET

### Endpoint
/v1/build_dataset_status

### Parameters
#### Query Parameters
- **run_key** (string) - Required - The run_key returned by /build_dataset

### Request Example
```shell
curl 'https://api.riveterhq.com/v1/build_dataset_status?run_key=' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
- **request_status** (string) - Indicates the status of the request.
- **message** (string) - A message providing details about the status.
- **run_key** (string) - The unique identifier for the dataset build run.
- **state** (string) - The current state of the dataset build (e.g., 'running', 'completed', 'failed').
- **prompt** (string) - The prompt used for the dataset build, if applicable.
- **identifiers** (array) - A list of identifiers associated with the build.
- **qualifiers** (array) - A list of qualifiers associated with the build.
- **attributes** (array) - A list of attributes associated with the build.
- **max_items** (integer) - The maximum number of items for the build.
- **has_result** (boolean) - Indicates if the build has a result.
- **error** (any) - Contains error details if the build failed.
- **started_at** (string) - Timestamp when the build started.
- **completed_at** (string) - Timestamp when the build completed.
- **created_at** (string) - Timestamp when the build was created.
- **credits_charged** (any) - The number of credits charged for the build.
- **credits_refunded** (any) - The number of credits refunded for the build.
- **app_url** (string) - A URL to view the build in the Riveter application.
- **enrichment_uuid** (string) - The UUID for the enrichment process.

#### Response Example
```json
{
  "request_status": "success",
  "message": "string",
  "run_key": "string",
  "state": "string",
  "prompt": "string",
  "identifiers": [
    "string"
  ],
  "qualifiers": [
    "string"
  ],
  "attributes": [
    "string"
  ],
  "max_items": 1,
  "has_result": true,
  "error": null,
  "started_at": null,
  "completed_at": null,
  "created_at": "2026-03-26T17:20:40.374Z",
  "credits_charged": null,
  "credits_refunded": null,
  "app_url": "https://example.com",
  "enrichment_uuid": "123e4567-e89b-12d3-a456-426614174000"
}
```
```

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

### Webhook Event Payload Structure

Source: https://docs.riveterhq.com/

An example of the JSON payload sent to a configured webhook URL upon the successful completion of an enrichment run.

```json
{
  "event": "run.completed",
  "run_key": "abc-123",
  "status": "success",
  "enrichment_uuid": "...",
  "enrichment_name": "My Enrichment",
  "credits_used": 2.0,
  "completed_at": "2024-01-15T12:00:00Z",
  "formatted_data": {
    "Company": [{"value": "Apple"}, {"value": "Google"}],
    "Revenue": [{"value": "383000000000"}, {"value": "307000000000"}]
  }
}
```

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

### GET /api_stats

Source: https://docs.riveterhq.com/

Retrieve API usage statistics for the current account, including run counts grouped by status. Optionally include detailed run-level information for active tasks.

```APIDOC
## GET /api_stats

### Description
Retrieve API usage statistics for the current account. Returns counts of API runs grouped by status.

### Method
GET

### Endpoint
/api_stats

### Parameters
#### Query Parameters
- **detailed** (boolean) - Optional - Set to true to include run-level detail for active statuses (default: false)

### Request Example
curl 'https://api.riveterhq.com/v1/api_stats?detailed=false' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

### Response
#### Success Response (200)
- **stats** (object) - Object containing counts and details of API runs.

#### Response Example
{
  "request_status": "success",
  "stats": {
    "propertyName": {
      "count": 1,
      "detail": [
        {
          "run_key": "string",
          "url": "https://example.com"
        }
      ]
    }
  }
}
```

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

### GET /run_status

Source: https://docs.riveterhq.com/

Poll for the status of an ongoing enrichment or dataset build run using its unique key.

```APIDOC
## GET /run_status

### Description
Poll for the status of an ongoing enrichment or dataset build run. You need the `run_key` or `build_key` obtained from the initial request.

### Method
GET

### Endpoint
/v1/run_status

### Parameters
#### Query Parameters
- **run_key** (string) - Required - The unique key for an enrichment run.
- **build_key** (string) - Required - The unique key for a dataset build.
  *Note: Provide either `run_key` or `build_key`.

### Response
#### Success Response (200)
- **request_status** (string) - Indicates the status of the run ('pending', 'running', 'completed', 'failed').
- **progress** (number) - The percentage of completion (if applicable).

#### Response Example
```json
{
  "request_status": "running",
  "progress": 50
}
```
```

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

### GET /run_status

Source: https://docs.riveterhq.com/

Checks the current status of an initiated enrichment run using its unique run key.

```APIDOC
## GET /run_status

### Description
Check the current status of an enrichment run using its unique run key. This is useful for monitoring the progress of asynchronous enrichment operations.

### Method
GET

### Endpoint
`/v1/run_status`

### Parameters
#### Query Parameters
- **run_key** (string) - Required - The unique run key (UUID) of the run to check. This key is obtained from the response of the `/run_new_enrichment` endpoint.

### Request Example
```bash
curl -X GET "https://api.riveterhq.com/v1/run_status?run_key=YOUR_RUN_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **request_status** (string) - Indicates the status of the request.
- **message** (string) - A confirmation message.
- **run_key** (string) - The unique identifier for this run.
- **status** (string) - The current status of the run (e.g., 'pending', 'processing', 'completed', 'failed').
- **credits_used** (integer) - Number of credits consumed by the run.
- **total_cells_expected** (integer) - Total number of data cells expected to be processed.
- **completed_cells** (integer) - Number of data cells already completed.
- **not_found_cells** (integer) - Number of data cells not found.
- **project_name** (string) - The name of the project associated with the run.
- **project_uuid** (string) - The UUID of the project.
- **enrichment_name** (string) - The name of the enrichment process.
- **enrichment_uuid** (string) - The UUID of the enrichment process.
- **error_message** (null) - Will contain an error message if the run failed.
- **riveter_app_link** (string) - A link to the run in the RiveterHQ application.

#### Response Example
```json
{
  "request_status": "success",
  "message": "Status retrieved successfully",
  "run_key": "123e4567-e89b-12d3-a456-426614174000",
  "status": "completed",
  "credits_used": 1,
  "total_cells_expected": 2,
  "completed_cells": 2,
  "not_found_cells": 0,
  "project_name": "riveterhq",
  "project_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "enrichment_name": "company_enrichment",
  "enrichment_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "error_message": null,
  "riveter_app_link": "https://app.riveterhq.com/runs/123e4567-e89b-12d3-a456-426614174000"
}
```

#### Error Responses
- **400** Bad request - invalid input or missing required parameters
- **401** Unauthorized - invalid or missing API key
- **403** Forbidden - API access not enabled for account
- **404** Resource not found
```

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

### GET /v1/run_data

Source: https://docs.riveterhq.com/

Retrieves data for a specific run using its unique run key. This endpoint is useful for fetching the results of a completed enrichment process.

```APIDOC
## GET /v1/run_data

### Description
Retrieves data for a specific run using its unique run key. The run key is obtained from the `/run_enrichment` endpoint.

### Method
GET

### Endpoint
/v1/run_data

### Query Parameters
- **run_key** (string) - Required - The run key (UUID) of the run to retrieve data for.

### Request Example
```bash
curl -X GET "https://api.riveterhq.com/v1/run_data?run_key=YOUR_RUN_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **request_status** (string) - Indicates the status of the request.
- **message** (string) - A message describing the result of the request.
- **run_key** (string) - The run key for which data was retrieved.
- **formatted_data** (object) - Contains the processed data for the run. The structure may vary.
- **status** (object) - Details about the status of the enrichment run.
  - **status** (string) - The current status of the run (e.g., 'pending', 'completed').
  - **credits_used** (integer) - The number of credits consumed by the run.
  - **total_cells_expected** (integer) - The total number of cells expected for the run.
  - **completed_cells** (integer) - The number of cells that have been completed.
  - **not_found_cells** (integer) - The number of cells that were not found.
  - **project_name** (string) - The name of the project associated with the run.
  - **project_uuid** (string) - The UUID of the project.
  - **enrichment_name** (string) - The name of the enrichment that was run.
  - **enrichment_uuid** (string) - The UUID of the enrichment.
  - **error_message** (string) - An error message if the run failed.
  - **riveter_app_link** (string) - A link to the run in the RiveterHQ application.

#### Response Example
```json
{
  "request_status": "success",
  "message": "Run data retrieved successfully",
  "run_key": "string",
  "formatted_data": {
    "propertyName*": "anything"
  },
  "status": {
    "status": "pending",
    "credits_used": 1,
    "total_cells_expected": 1,
    "completed_cells": 1,
    "not_found_cells": 1,
    "project_name": "string",
    "project_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "enrichment_name": "string",
    "enrichment_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "error_message": null,
    "riveter_app_link": "string"
  }
}
```
```

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

### Check Enrichment Run Status (GET /run_status)

Source: https://docs.riveterhq.com/

This snippet shows how to check the current status of an ongoing or completed enrichment run using the Riveter API. It requires a `run_key` obtained from initiating a run and an authorization header. The response provides details about the run's progress, credits used, and expected outcomes.

```shell
curl -X GET "https://api.riveterhq.com/v1/run_status?run_key=YOUR_RUN_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

### POST /build_dataset

Source: https://docs.riveterhq.com/

Initiates an asynchronous dataset build process using either a natural-language prompt, a structured specification, or both.

```APIDOC
## POST /build_dataset

### Description
Build a dataset by providing either a natural-language prompt, a structured spec (identifiers, qualifiers, attributes), or both. The dataset is generated asynchronously.

### Method
POST

### Endpoint
/build_dataset

### Parameters
#### Request Body
- **prompt** (string) - Optional - Natural-language description of the dataset
- **identifiers** (array) - Optional - Column names that uniquely identify each row (max 3)
- **qualifiers** (array) - Optional - Filters or constraints on the dataset (max 10)
- **attributes** (array) - Optional - Additional columns to include (max 10)
- **max_items** (integer) - Optional - Maximum number of rows to generate (default: 100)
- **auto_run_enrichment** (boolean) - Optional - Automatically create and run an enrichment when complete

### Request Example
{
  "prompt": "Top 50 SaaS companies by revenue",
  "max_items": 50
}

### Response
#### Success Response (200)
- **request_status** (string) - Status of the request
- **run_key** (string) - Unique key to track the build status
- **app_url** (string) - URL to view the build in the dashboard

#### Response Example
{
  "request_status": "success",
  "message": "Dataset build started",
  "run_key": "abc-123-xyz",
  "app_url": "https://example.com"
}
```

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

### POST /build_dataset

Source: https://docs.riveterhq.com/

Initiate the process of building a dataset programmatically. Datasets can be generated from a natural-language prompt or a structured specification.

```APIDOC
## POST /build_dataset

### Description
Start generating rows for a dataset. This can be done using a natural-language prompt (e.g., "top 100 SaaS companies") or a structured specification.

### Method
POST

### Endpoint
/v1/build_dataset

### Parameters
#### Query Parameters
- **dataset_webhook_url** (string) - Optional - The URL to send dataset build results to upon completion.

#### Request Body
- **prompt** (string) - Required - A natural-language prompt describing the dataset to build.
  *Alternatively, a structured specification can be provided.
- **output_columns** (array of strings) - Required - A list of desired column names for the dataset.

### Request Example
```json
{
  "prompt": "List of the top 50 largest technology companies by market cap.",
  "output_columns": ["Company Name", "Market Cap"]
}
```

### Response
#### Success Response (200)
- **request_status** (string) - Indicates if the request was successful ('success' or 'error').
- **build_key** (string) - A unique key to track the dataset build status.

#### Response Example
```json
{
  "request_status": "success",
  "build_key": "dataset-abc-123"
}
```
```

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

### Build Dataset API Request (Shell Curl)

Source: https://docs.riveterhq.com/

This snippet shows how to initiate a dataset build process using the Riveter API with a cURL command. It supports building datasets from natural language prompts or structured specifications, and requires an authorization token. The dataset build is asynchronous.

```shell
curl https://api.riveterhq.com/v1/build_dataset \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{ 
  "prompt": "Top 50 SaaS companies by revenue", 
  "max_items": 50 
}'
```

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

### POST /v1/run_new_enrichment

Source: https://docs.riveterhq.com/

Creates and executes a new enrichment process in a single request by providing a prompt and output attributes.

```APIDOC
## POST /v1/run_new_enrichment

### Description
Creates and runs a new enrichment in a single request. Users can define output columns using a natural-language prompt and an attributes array, allowing the AI to configure the enrichment automatically.

### Method
POST

### Endpoint
https://api.riveterhq.com/v1/run_new_enrichment

### Parameters
#### Request Body
- **prompt** (string) - Required - Natural-language description of the desired enrichment task.
- **attributes** (array) - Required - List of output column names to be generated.

### Request Example
{
  "prompt": "Extract contact information from company websites",
  "attributes": ["CEO Name", "Company Revenue"]
}

### Response
#### Success Response (200)
- **run_key** (string) - The identifier for the newly created enrichment run.
```

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

### POST /v1/run_enrichment

Source: https://docs.riveterhq.com/

Initiates an enrichment run for a pre-configured enrichment project using a provided UUID.

```APIDOC
## POST /v1/run_enrichment

### Description
Initiates an enrichment run for a specific enrichment project. The input data must match the column headers defined in the enrichment configuration.

### Method
POST

### Endpoint
https://api.riveterhq.com/v1/run_enrichment

### Parameters
#### Query Parameters
- **enrichment_uuid** (string, uuid) - Required - The UUID of the enrichment to run.
- **run_key** (string) - Optional - A custom identifier for this run.
- **webhook_url** (string, uri) - Optional - URL to receive a POST request when the run completes.

#### Request Body
- **input** (object) - Required - Input data as key-value pairs where keys are column headers and values are arrays of strings.

### Request Example
{
  "input": {
    "Company Name": ["Acme Corp", "Tech Solutions Inc"],
    "Website": ["acme.com", "techsolutions.com"]
  }
}

### Response
#### Success Response (200)
- **request_status** (string) - Status of the request.
- **run_key** (string) - The identifier for the initiated run.
- **status** (string) - Current status of the enrichment.

#### Response Example
{
  "request_status": "success",
  "run_key": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending"
}
```

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

### POST /v1/monitor_enrichment

Source: https://docs.riveterhq.com/

Creates a monitor for an enrichment, allowing it to run on a schedule and send webhook notifications. This endpoint replaces the older `/monitor_project` endpoint.

```APIDOC
## POST /v1/monitor_enrichment

### Description
Creates a monitor for an enrichment. Monitors run your enrichment on a schedule and can send webhook notifications with results. This endpoint is a successor to `/monitor_project`.

### Method
POST

### Endpoint
/v1/monitor_enrichment

### Query Parameters
- **enrichment_uuid** (string) - Required - UUID of the enrichment to monitor. `project_uuid` is also accepted.

### Request Body
- **cadence** (string) - Required - Enum: `daily`, `weekly`, `monthly`. How often the monitor runs.
- **hour** (integer) - Required - Minimum: 0, Maximum: 23. The hour of the day to run.
- **minute** (integer) - Required - Minimum: 0, Maximum: 59. The minute of the hour to run.
- **timezone** (string) - Required - The timezone (e.g., 'UTC', 'America/New_York').
- **alert_rule** (string) - Optional - Enum: `each_run`, `only_on_change`. When to send alerts (defaults to `each_run`).
- **day_of_month** (integer) - Optional - Minimum: 1, Maximum: 28. Required for `monthly` cadence. The day of the month to run.
- **day_of_week** (integer) - Optional - Minimum: 0, Maximum: 6. Required for `weekly` cadence. The day of the week to run (0=Sunday).
- **input** (object) - Optional - Input data for the monitor.
  - **output_format** (string) - Optional - Enum: `current_only`, `current_and_previous`. Output format (defaults to `current_only`).
- **run_immediately** (boolean) - Optional - Whether to run the monitor immediately after creation.
- **webhook_url** (string) - Optional - URL to receive webhook notifications.

### Request Example
```bash
curl 'https://api.riveterhq.com/v1/monitor_enrichment?enrichment_uuid=' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{ 
  "cadence": "daily",
  "minute": 0,
  "hour": 0,
  "day_of_week": 0,
  "day_of_month": 1,
  "timezone": "",
  "webhook_url": "",
  "alert_rule": "each_run",
  "output_format": "current_only",
  "run_immediately": true,
  "input": {
    "propertyName*": [
      ""
    ]
  }
}'
```

### Response
#### Success Response (201)
- **request_status** (string) - Indicates the status of the request.
- **message** (string) - A message describing the result of the request.
- **monitor** (object) - Details about the created monitor.
  - **uuid** (string) - The unique identifier for the monitor.
  - **name** (string) - The name of the monitor.
  - **cadence** (string) - The scheduled cadence of the monitor.
  - **enabled** (boolean) - Whether the monitor is currently enabled.
  - **project_uuid** (string) - The UUID of the project associated with the monitor.
  - **project_name** (string) - The name of the project.
  - **enrichment_uuid** (string) - The UUID of the enrichment being monitored.
  - **enrichment_name** (string) - The name of the enrichment.
  - **next_run_at** (string) - The timestamp for the next scheduled run.
  - **schedule_summary** (string) - A human-readable summary of the schedule.

#### Response Example
```json
{
  "request_status": "success",
  "message": "Monitor created successfully",
  "monitor": {
    "uuid": "string",
    "name": "string",
    "cadence": "string",
    "enabled": true,
    "project_uuid": "string",
    "project_name": "string",
    "enrichment_uuid": "string",
    "enrichment_name": "string",
    "next_run_at": "string",
    "schedule_summary": "string"
  }
}
```
```

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

### Execute Enrichment with Webhook

Source: https://docs.riveterhq.com/

Demonstrates how to trigger an enrichment run using cURL while specifying a webhook URL for asynchronous result delivery. The request requires an Authorization header with a Bearer token and a JSON body containing the input data.

```shell
curl -X POST "https://api.riveterhq.com/v1/run_enrichment?enrichment_uuid=xxx&webhook_url=https://your-server.com/webhook" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"input": {"Company": ["Apple", "Google"]}}'
```

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

### POST /run_new_enrichment

Source: https://docs.riveterhq.com/

Initiate a new enrichment process by providing input data, a prompt, and specific attributes to extract.

```APIDOC
## POST /run_new_enrichment

### Description
Send a request to trigger a new data enrichment process.

### Method
POST

### Endpoint
/run_new_enrichment

### Parameters
#### Query Parameters
- **run_key** (string) - Optional - Identifier for the run.
- **webhook_url** (string) - Optional - URL to receive notifications upon completion.

#### Request Body
- **input** (object) - Data to be enriched.
- **prompt** (string) - Instructions for the enrichment engine.
- **attributes** (array) - List of specific fields to extract.

### Request Example
{
  "input": {
    "Company Name": ["Acme Corp", "Tech Solutions Inc"],
    "Website": ["acme.com", "techsolutions.com"]
  },
  "prompt": "Find key business information about these companies",
  "attributes": ["Employee Count", "Industry", "Annual Revenue", "CEO"]
}
```

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

### POST /run_new_enrichment

Source: https://docs.riveterhq.com/

Run a new enrichment directly via the API. This can be done using a prompt and attributes or a full specification.

```APIDOC
## POST /run_new_enrichment

### Description
Define and execute a new enrichment in a single API request. Supports two options: prompt + attributes (recommended) or a full specification.

### Method
POST

### Endpoint
/v1/run_new_enrichment

### Parameters
#### Query Parameters
- **webhook_url** (string) - Optional - The URL to send results to upon completion.

#### Request Body
This endpoint accepts two types of request bodies:

**Option A: Prompt + Attributes (Recommended)**
- **input** (object) - Required - The input data for the enrichment.
  - **[Column Name]** (array of strings) - Required - An array of values for the specified column.
- **prompt** (string) - Required - A natural-language prompt describing the desired enrichment.
- **output_columns** (array of strings) - Required - A list of desired output column names.

**Option B: Full Specification**
- **input** (object) - Required - The input data for the enrichment.
  - **[Column Name]** (array of strings) - Required - An array of values for the specified column.
- **output_columns** (object) - Required - Defines the output columns and their configurations.
  - **[Column Name]** (object) - Configuration for a specific output column.
    - **prompt** (string) - Required - The prompt for this column.
    - **format** (string) - Optional - Formatting rules for the column.

### Request Example (Option A)
```json
{
  "input": {
    "Company": ["Apple", "Google"]
  },
  "prompt": "Get the revenue and employee count for each company.",
  "output_columns": ["Revenue", "Employee Count"]
}
```

### Response
#### Success Response (200)
- **request_status** (string) - Indicates if the request was successful ('success' or 'error').
- **run_key** (string) - A unique key to track the run status.

#### Response Example
```json
{
  "request_status": "success",
  "run_key": "xyz-789"
}
```
```

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

### Create Enrichment Monitor

Source: https://docs.riveterhq.com/

Creates a scheduled monitor for an enrichment process. Supports various cadences and webhook notifications.

```shell
curl 'https://api.riveterhq.com/v1/monitor_enrichment?enrichment_uuid=' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "cadence": "daily",
  "minute": 0,
  "hour": 0,
  "day_of_week": 0,
  "day_of_month": 1,
  "timezone": "",
  "webhook_url": "",
  "alert_rule": "each_run",
  "output_format": "current_only",
  "run_immediately": true,
  "input": {
    "propertyName*": [
      ""
    ]
  }
}'
```

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

### Check Dataset Build Status with Curl

Source: https://docs.riveterhq.com/

This snippet demonstrates how to check the current status of a dataset build using a cURL command. It requires a run_key obtained from a previous /build_dataset operation and an API key for authentication. The response indicates the success or failure of the build process.

```Shell
curl 'https://api.riveterhq.com/v1/build_dataset_status?run_key=' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

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

### POST /run_new_enrichment

Source: https://docs.riveterhq.com/

Initiates a new data enrichment run. You can specify either a prompt and attributes for enrichment or an output configuration. The endpoint supports backward compatibility with the older /run endpoint.

```APIDOC
## POST /run_new_enrichment

### Description
Initiates a new data enrichment run. This endpoint allows for precise control over output by defining the exact structure of each output column using either a natural language prompt with desired attributes or a detailed output configuration. It is backward compatible with the `/run` endpoint.

### Method
POST

### Endpoint
`/v1/run_new_enrichment`

### Parameters
#### Query Parameters
- **run_key** (string) - Optional - Custom identifier for this run. If not provided, one will be generated.
- **webhook_url** (string, uri) - Optional - URL to receive a POST request when the run completes. The payload includes full results.

#### Request Body
- **input** (object) - Required - Input data as key-value pairs where keys are column headers and values are arrays of strings.
  - **attributes** (array of strings) - Required (if `prompt` is provided) - Output column names to generate (max 10). Must be provided together with `prompt`. Cannot be combined with `output`.
  - **output** (object) - Optional - Output configuration defining what data to extract. Cannot be combined with `prompt`/`attributes`.
  - **prompt** (string) - Required (if `attributes` is provided) - Natural-language description of the enrichment you want. Must be provided together with `attributes`. Cannot be combined with `output`.

### Request Example
```json
{
  "input": {
    "Company Name": [
      "Acme Corp",
      "Tech Solutions Inc"
    ],
    "Website": [
      "acme.com",
      "techsolutions.com"
    ]
  },
  "prompt": "Find key business information about these companies",
  "attributes": [
    "Employee Count",
    "Industry",
    "Annual Revenue",
    "CEO"
  ]
}
```

### Response
#### Success Response (200)
- **request_status** (string) - Indicates the status of the request.
- **message** (string) - A confirmation message.
- **run_key** (string) - The unique identifier for this run.
- **status** (string) - The current status of the run (e.g., 'pending').
- **credits_used** (integer) - Number of credits consumed by the run.
- **total_cells_expected** (integer) - Total number of data cells expected to be processed.
- **completed_cells** (integer) - Number of data cells already completed.
- **not_found_cells** (integer) - Number of data cells not found.
- **project_name** (string) - The name of the project associated with the run.
- **project_uuid** (string) - The UUID of the project.
- **enrichment_name** (string) - The name of the enrichment process.
- **enrichment_uuid** (string) - The UUID of the enrichment process.
- **error_message** (null) - Will contain an error message if the run failed.
- **riveter_app_link** (string) - A link to the run in the RiveterHQ application.

#### Response Example
```json
{
  "request_status": "success",
  "message": "Run initiated successfully",
  "run_key": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "credits_used": 1,
  "total_cells_expected": 2,
  "completed_cells": 0,
  "not_found_cells": 0,
  "project_name": "riveterhq",
  "project_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "enrichment_name": "company_enrichment",
  "enrichment_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "error_message": null,
  "riveter_app_link": "https://app.riveterhq.com/runs/123e4567-e89b-12d3-a456-426614174000"
}
```

#### Error Responses
- **400** Bad request - invalid input or missing required parameters
- **401** Unauthorized - invalid or missing API key
- **403** Forbidden - API access not enabled for account
- **409** Conflict - resource already exists or conflicting state
- **422** Unprocessable entity - validation failed
```

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

### Retrieve Run Data via API

Source: https://docs.riveterhq.com/

Fetches data for a specific enrichment run using a run key. Requires a valid Bearer token for authorization.

```shell
curl -X GET "https://api.riveterhq.com/v1/run_data?run_key=YOUR_RUN_KEY" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

### POST /run_enrichment

Source: https://docs.riveterhq.com/

Execute an API-enabled enrichment with provided input data. This endpoint allows you to run enrichments that have been pre-configured and enabled in the Riveter UI.

```APIDOC
## POST /run_enrichment

### Description
Run an enrichment with input data. The enrichment must be API-enabled (you can turn this on from your enrichment view).

### Method
POST

### Endpoint
/v1/run_enrichment

### Parameters
#### Query Parameters
- **enrichment_uuid** (string) - Required - The unique identifier for the enrichment to run.
- **webhook_url** (string) - Optional - The URL to send results to upon completion.

#### Request Body
- **input** (object) - Required - The input data for the enrichment.
  - **[Column Name]** (array of strings) - Required - An array of values for the specified column.

### Request Example
```json
{
  "input": {
    "Company": ["Apple", "Google"]
  }
}
```

### Response
#### Success Response (200)
- **request_status** (string) - Indicates if the request was successful ('success' or 'error').
- **run_key** (string) - A unique key to track the run status.

#### Response Example
```json
{
  "request_status": "success",
  "run_key": "abc-123"
}
```
```

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

### Run New Enrichment (Curl)

Source: https://docs.riveterhq.com/

Initiates a new data enrichment process. This endpoint accepts a JSON body containing input data, a prompt for the enrichment, and specific attributes to extract. Authentication is handled via a Bearer token in the Authorization header.

```Curl
curl -X POST https://api.riveterhq.com/v1/run_new_enrichment \
  -H "Authorization: Bearer YOUR_SECRET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "Company Name": [
        "Acme Corp",
        "Tech Solutions Inc"
      ],
      "Website": [
        "acme.com",
        "techsolutions.com"
      ]
    },
    "prompt": "Find key business information about these companies",
    "attributes": [
      "Employee Count",
      "Industry",
      "Annual Revenue",
      "CEO"
    ]
  }'
```

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

### Retrieve Account Information (Shell Curl)

Source: https://docs.riveterhq.com/

Retrieves information about the current account associated with the provided API key. This includes account details, plan information, and API key specifics. Requires an API key for authentication.

```Shell
curl https://api.riveterhq.com/v1/account \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

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

### Retrieve API Usage Statistics (Shell Curl)

Source: https://docs.riveterhq.com/

Fetches API usage statistics for the current account. The `detailed` parameter can be set to `true` to include run-level details for active runs. Requires an API key for authentication.

```Shell
curl 'https://api.riveterhq.com/v1/api_stats?detailed=false' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

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

### Initiate Data Enrichment via cURL

Source: https://docs.riveterhq.com/

This snippet demonstrates how to trigger an enrichment run by sending a POST request to the RiveterHQ API. It requires an enrichment UUID and a valid Bearer token for authentication.

```shell
curl -X POST "https://api.riveterhq.com/v1/run_enrichment?enrichment_uuid=YOUR_ENRICHMENT_UUID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"Company Name": ["Acme Corp", "Tech Solutions Inc"]}}'
```

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

### Configure Authentication Header

Source: https://docs.riveterhq.com/

Shows the standard format for the Authorization header required for all API requests to the Riveter service.

```http
Authorization: Bearer YOUR_API_KEY
```

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

### POST /scrape

Source: https://docs.riveterhq.com/

Scrape a webpage and return the text content. This endpoint allows you to extract text content from any public webpage.

```APIDOC
## POST /scrape

### Description
Scrape a webpage and return the text content. This endpoint allows you to extract text content from any public webpage.

### Method
POST

### Endpoint
/v1/scrape

### Parameters
#### Request Body
- **url** (string) - Required - The URL to scrape
- **proxy_country_code** (string) - Optional - Two-character country code for proxy (e.g., 'us', 'gb', 'de'). Pattern: `^[a-z]{2}$`
- **skip_cache** (boolean) - Optional - Set to true to bypass cache and always fetch fresh content. Default: `false`

### Request Example
```shell
curl https://api.riveterhq.com/v1/scrape \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{ 
  "url": "https://example.com"
}'
```

### Response
#### Success Response (200)
- **request_status** (string) - Indicates the status of the request.
- **message** (string) - A message providing details about the scrape.
- **data** (object) - Contains the scraped data.
  - **url** (string) - The URL that was scraped.
  - **text** (string) - The extracted text content from the webpage.
  - **base_url_for_links** (string) - The base URL for resolving relative links.
  - **status_code** (integer) - The HTTP status code returned by the server (e.g., 200, 404, 500).
  - **possibly_blocked** (boolean) - Optional. Boolean flag if the page may be blocked by anti-scraping measures.
  - **credit_used** (integer) - The number of credits consumed for the scrape.
  - **riveter_app_link** (string) - Direct link to view this scrape in the Riveter application.

#### Response Example
```json
{
  "request_status": "success",
  "message": "string",
  "run_key": "string",
  "data": {
    "url": "https://example.com",
    "text": "string",
    "base_url_for_links": "https://example.com",
    "status_code": 200,
    "possibly_blocked": true,
    "credit_used": 1,
    "riveter_app_link": "https://example.com"
  }
}
```
```

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

### Pause Monitor API Request (Shell Curl)

Source: https://docs.riveterhq.com/

This snippet demonstrates how to pause an active monitor using the Riveter API via a cURL command. It requires the monitor's UUID and an authorization token. If the monitor is already paused, this operation is a no-op.

```shell
curl 'https://api.riveterhq.com/v1/pause_monitor?monitor_uuid=' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
```