### cURL Example for API Request

Source: https://docs.boltroute.ai/api-reference/authorization

An example of making a POST request to the '/api/v1/verify' endpoint using cURL. This demonstrates the inclusion of the 'Authorization' header and 'Content-Type' for JSON data.

```bash
curl -X POST \
  'https://api.boltroute.ai/api/v1/verify' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com"}'
```

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

### Create API Key Request Example (cURL)

Source: https://docs.boltroute.ai/api-reference/endpoints/api-keys/create-key

An example of how to create a new API key using a cURL command. This demonstrates the HTTP method, endpoint, headers, and the JSON payload.

```bash
curl -X POST \
  'https://api.boltroute.ai/api/v1/api-keys' \
  -H 'Content-Type: application/json' \
  -d '{"name":"My Production Key","purpose":"zapier"}'
```

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

### Fetch API Key Usage Metrics (Bash)

Source: https://docs.boltroute.ai/api-reference/endpoints/api-keys/usage-summary

Retrieve aggregated API key usage metrics for the authenticated user. This example demonstrates a GET request to the /api/v1/api-keys/usage endpoint, optionally including 'from' and 'to' query parameters for date range filtering. Series data is only returned when both parameters are provided.

```bash
curl -X GET \
  'https://api.boltroute.ai/api/v1/api-keys/usage?from=2025-01-01T00:00:00Z&to=2025-01-07T00:00:00Z'
```

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

### POST /api/v1/verify

Source: https://docs.boltroute.ai/api-reference/authorization

Example of verifying a user's email using the API.

```APIDOC
## POST /api/v1/verify

### Description
Verify a user's email address.

### Method
POST

### Endpoint
`/api/v1/verify`

### Headers
- **Authorization** (string) - Required - `Bearer <api_key>`
- **Content-Type** (string) - Required - `application/json`

### Request Body
- **email** (string) - Required - The email address to verify.

### Request Example
```json
{
  "email": "user@example.com"
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message.

#### Response Example
```json
{
  "message": "Email verified successfully."
}
```
```

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

### Fetch Batch Verification Task by ID (Bash)

Source: https://docs.boltroute.ai/api-reference/endpoints/batch-verification/get-task

Retrieves a single batch verification task using its unique ID. This command-line example demonstrates how to make a GET request to the API endpoint. It requires the task ID as a path parameter and returns the task details along with aggregated metrics.

```bash
curl -X GET \
  'https://api.boltroute.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000'
```

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

### Create API Key Response Example (JSON)

Source: https://docs.boltroute.ai/api-reference/endpoints/api-keys/create-key

Illustrates the JSON response received after successfully creating an API key. It includes the key's ID, user ID, the generated plaintext key, name, purpose, and creation timestamp.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "sk_live_example",
  "name": "My Production Key",
  "purpose": "zapier",
  "created_at": "2025-01-01T12:00:00Z"
}
```

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

### Get Verification Metrics

Source: https://docs.boltroute.ai/integrations/make

Retrieve usage analytics and metrics for email verification services.

```APIDOC
## GET /v1/analytics/verification

### Description
Provides usage analytics and metrics for email verification services.

### Method
GET

### Endpoint
https://api.boltroute.ai/v1/analytics/verification

### Parameters
#### Query Parameters
- **start_date** (string) - Optional - Start date for the metrics (YYYY-MM-DD).
- **end_date** (string) - Optional - End date for the metrics (YYYY-MM-DD).

### Response
#### Success Response (200)
- **total_verifications** (integer) - Total number of email verifications performed.
- **valid_emails** (integer) - Number of valid emails verified.
- **invalid_emails** (integer) - Number of invalid emails verified.
- **disposable_emails** (integer) - Number of disposable emails identified.

#### Response Example
```json
{
  "total_verifications": 1000,
  "valid_emails": 800,
  "invalid_emails": 150,
  "disposable_emails": 50
}
```
```

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

### GET /plants

Source: https://docs.boltroute.ai/api-reference/endpoint/get

Retrieves a list of all plants accessible to the user. Supports pagination via a limit parameter.

```APIDOC
## GET /plants

### Description
Returns all plants from the system that the user has access to.

### Method
GET

### Endpoint
/plants

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of results to return

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **name** (string) - The name of the plant
- **tag** (string) - Tag to specify the type

#### Response Example
```json
{
  "example": "[
  {
    "name": "string",
    "tag": "string"
  }
]"
}
```

#### Error Response (400)
- **error** (integer) - Error code
- **message** (string) - Error message
```

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

### Example Response for Daily Metrics Series (JSON)

Source: https://docs.boltroute.ai/api-reference/endpoints/batch-verification/task-series

This is an example of a successful JSON response (Status: 200 OK) when requesting daily metrics series for a batch verification task. The response includes the task ID, source of the data, and a list of daily metrics points, each containing date, total email addresses, job status breakdown, progress, verification status breakdown, and timestamps for verification requests and completion.

```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "source": "frontend",
  "series": [
    {
      "date": "2025-01-01",
      "total_email_addresses": 2,
      "job_status": {
        "pending": 0,
        "processing": 0,
        "completed": 2,
        "failed": 0
      },
      "progress": 1,
      "progress_percent": 100,
      "verification_status": {
        "valid": 2,
        "invalid": 0,
        "catchall": 0,
        "invalid_syntax": 0,
        "disposable_domain": 0,
        "unknown": 0,
        "role_based": 0,
        "disposable_domain_emails": 0
      },
      "last_verification_requested_at": "2025-01-01T12:00:01Z",
      "last_verification_completed_at": "2025-01-01T12:04:59Z"
    }
  ]
}
```

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

### List Batch Verification Jobs (API Response)

Source: https://docs.boltroute.ai/api-reference/endpoints/batch-verification/task-jobs

Example JSON response for listing batch verification jobs. It includes a list of jobs, each with details about the email verification status and associated email data. The response also provides pagination information.

```json
{
  "jobs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "task_id": "550e8400-e29b-41d4-a716-446655440000",
      "email_address": "user1@example.com",
      "status": "completed",
      "email": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "email": "user1@example.com",
        "status": "valid",
        "is_role_based": false,
        "is_disposable": false,
        "has_mx_records": true,
        "has_reverse_dns": true,
        "domain_name": "example.com",
        "host_name": "mx.example.com",
        "server_type": "Unknown",
        "is_catchall": false,
        "validated_at": "2025-01-01T12:04:59Z",
        "unknown_reason": null,
        "needs_physical_verify": false
      },
      "created_at": "2025-01-01T12:00:01Z",
      "updated_at": "2025-01-01T12:05:00Z"
    }
  ],
  "count": 1,
  "limit": 10,
  "offset": 0
}
```

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

### Get Task Status

Source: https://docs.boltroute.ai/integrations/make

Retrieve the status and progress of a previously created verification task.

```APIDOC
## GET /v1/verify/task/{task_id}

### Description
Retrieves the status and progress of a specific verification task.

### Method
GET

### Endpoint
https://api.boltroute.ai/v1/verify/task/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the verification task.

### Response
#### Success Response (200)
- **status** (string) - The overall status of the task (e.g., "pending", "processing", "completed", "failed").
- **progress** (integer) - The percentage of completion for the task.

#### Response Example
```json
{
  "status": "processing",
  "progress": 50
}
```
```

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

### Get Plants API Endpoint (OpenAPI)

Source: https://docs.boltroute.ai/api-reference/endpoint/get

Defines the OpenAPI 3.1.0 specification for the GET /plants endpoint. It details the API's purpose, server URL, security scheme, request parameters (limit), and possible responses (200 OK with Plant schema, 400 Bad Request with Error schema).

```yaml
GET /plants
openapi: 3.1.0
info:
  title: OpenAPI Plant Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: http://sandbox.mintlify.com
security:
  - bearerAuth: []
paths:
  /plants:
    get:
      description: Returns all plants from the system that the user has access to
      parameters:
        - name: limit
          in: query
          description: The maximum number of results to return
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Plant response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Plant'
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Plant:
      required:
        - name
      type: object
      properties:
        name:
          description: The name of the plant
          type: string
        tag:
          description: Tag to specify the type
          type: string
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

```

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

### GET /api/v1/tasks/{id}/jobs

Source: https://docs.boltroute.ai/api-reference/endpoints/batch-verification/task-jobs

Lists email jobs for a batch verification task, including per-email results when available. Supports pagination.

```APIDOC
## GET /api/v1/tasks/{id}/jobs

### Description
List the email jobs for a batch verification task, including nested verification results (when available). This endpoint provides a paginated list of jobs associated with a specific task.

### Method
GET

### Endpoint
`/api/v1/tasks/{id}/jobs`

### Parameters
#### Path Parameters
- **id** (UUID) - Required - The unique identifier of the batch verification task.

#### Query Parameters
- **limit** (int) - Optional - The maximum number of jobs to return per page. Defaults to 10, with a maximum of 100.
- **offset** (int) - Optional - The number of jobs to skip before starting to collect the result set. Defaults to 0.

### Request Example
```bash
curl -X GET \
  'https://api.boltroute.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/jobs?limit=10&offset=0'
```

### Response
#### Success Response (200 OK)
- **jobs** (array) - A list of job objects, each containing email and verification details.
- **count** (int) - The total number of jobs matching the query.
- **limit** (int) - The limit parameter used for pagination.
- **offset** (int) - The offset parameter used for pagination.

**Job Object Fields:**
- `id` (string) - The job's unique identifier.
- `task_id` (string) - The ID of the associated task.
- `email_address` (string) - The email address associated with the job.
- `status` (string) - The status of the job (e.g., 'completed').
- `email` (object | null) - Nested email verification details if available, otherwise null.
  - `id` (string) - The email's unique identifier.
  - `email` (string) - The email address.
  - `status` (string) - The verification status of the email.
  - `is_role_based` (boolean) - Indicates if the email is role-based.
  - `is_disposable` (boolean) - Indicates if the email is disposable.
  - `has_mx_records` (boolean) - Indicates if the email domain has MX records.
  - `has_reverse_dns` (boolean) - Indicates if the email domain has reverse DNS records.
  - `domain_name` (string) - The domain name of the email.
  - `host_name` (string) - The host name associated with the email.
  - `server_type` (string) - The type of mail server.
  - `is_catchall` (boolean) - Indicates if the domain is a catch-all.
  - `validated_at` (string) - Timestamp of when the email was validated.
  - `unknown_reason` (string | null) - Reason for unknown status, if applicable.
  - `needs_physical_verify` (boolean) - Indicates if physical verification is needed.
- `created_at` (string) - Timestamp when the job was created.
- `updated_at` (string) - Timestamp when the job was last updated.

#### Response Example
```json
{
  "jobs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "task_id": "550e8400-e29b-41d4-a716-446655440000",
      "email_address": "user1@example.com",
      "status": "completed",
      "email": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "email": "user1@example.com",
        "status": "valid",
        "is_role_based": false,
        "is_disposable": false,
        "has_mx_records": true,
        "has_reverse_dns": true,
        "domain_name": "example.com",
        "host_name": "mx.example.com",
        "server_type": "Unknown",
        "is_catchall": false,
        "validated_at": "2025-01-01T12:04:59Z",
        "unknown_reason": null,
        "needs_physical_verify": false
      },
      "created_at": "2025-01-01T12:00:01Z",
      "updated_at": "2025-01-01T12:05:00Z"
    }
  ],
  "count": 1,
  "limit": 10,
  "offset": 0
}
```

### Errors
- **400 Bad Request**: Invalid ID or pagination parameters.
- **401 Unauthorized**: Authentication failed.
- **404 Not Found**: The specified batch verification task was not found.
- **500 Internal Server Error**: An unexpected error occurred on the server.
```

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

### Create Batch Email Verification Task using cURL

Source: https://docs.boltroute.ai/scenarios/batch-list-cleaning

This example demonstrates how to initiate a batch email verification task using a cURL command. It sends a POST request to the Boltroute AI API with a JSON payload containing a list of emails. The API returns a task ID and counts for emails and domains processed.

```bash
curl -X POST \
  'https://api.boltroute.ai/api/v1/tasks' \
  -H 'Content-Type: application/json' \
  -d '{"emails":["user1@example.com","user2@example.com"]}'
```

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

### Fetch Verification Metrics with Date Range (Bash)

Source: https://docs.boltroute.ai/api-reference/endpoints/metrics-controller

This snippet demonstrates how to fetch verification metrics using the BoltRoute AI API. It utilizes a curl command with GET method and specifies optional 'from' and 'to' query parameters for date filtering. An API key is required for authentication.

```bash
curl -X GET \
  'https://api.boltroute.ai/api/v1/metrics/verifications?from=2025-01-01T00:00:00Z&to=2025-01-07T00:00:00Z'
```

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

### GET /api/v1/api-keys/{id}/usage

Source: https://docs.boltroute.ai/api-reference/endpoints/api-keys/get-key-usage

Retrieve usage data for a single API key. This endpoint allows you to fetch the usage statistics for a specific API key, with options to include daily usage series within a specified date range.

```APIDOC
## GET /api/v1/api-keys/{id}/usage

### Description
Retrieve usage data for a single API key. This endpoint allows you to fetch the usage statistics for a specific API key, with options to include daily usage series within a specified date range.

### Method
GET

### Endpoint
/api/v1/api-keys/{id}/usage

### Parameters
#### Path Parameters
- **id** (UUID) - Required - The unique identifier of the API key.

#### Query Parameters
- **from** (RFC3339 timestamp) - Optional - Include daily usage from this timestamp (used for time series). Defaults to the key's `created_at` when only `to` is provided.
- **to** (RFC3339 timestamp) - Optional - Include daily usage up to this timestamp (used for time series). Defaults to the current time when only `from` is provided.

### Request Example
```bash
curl -X GET \
  'https://api.boltroute.ai/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000/usage?from=2025-01-01T00:00:00Z&to=2025-01-07T00:00:00Z'
```

### Response
#### Success Response (200 OK)
- **id** (UUID) - The unique identifier of the API key.
- **user_id** (UUID) - The unique identifier of the user associated with the API key.
- **name** (string) - The name of the API key.
- **purpose** (string) - The purpose of the API key.
- **usage_count** (integer) - The total usage count for the API key.
- **last_used_at** (RFC3339 timestamp) - The timestamp when the API key was last used.
- **created_at** (RFC3339 timestamp) - The timestamp when the API key was created.
- **is_active** (boolean) - Indicates if the API key is currently active.
- **series** (array of objects) - An array of objects, where each object contains a `date` (string) and `usage_count` (integer) for a specific day, included when `from` or `to` parameters are provided.

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Production Key",
  "purpose": "zapier",
  "usage_count": 1234,
  "last_used_at": "2025-01-07T12:00:00Z",
  "created_at": "2025-01-01T12:00:00Z",
  "is_active": true,
  "series": [
    { "date": "2025-01-01", "usage_count": 120 },
    { "date": "2025-01-02", "usage_count": 98 }
  ]
}
```

#### Error Responses
- **400** - Invalid UUID format for the `id` parameter.
- **401** - Unauthorized: Authentication credentials are missing or invalid.
- **404** - Key not found: The specified API key ID does not exist.
- **500** - Internal error: An unexpected error occurred on the server.
```

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

### X-API-Key Header

Source: https://docs.boltroute.ai/api-reference/authorization

Demonstrates how to authorize requests using the X-API-Key header.

```APIDOC
## X-API-Key Header

### Description
Authorize requests using the `X-API-Key` header.

### Method
Any

### Endpoint
Any

### Headers
- **X-API-Key** (string) - Required - `<api_key>`

### Request Example
```text
X-API-Key: <api_key>
```
```

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

### General Information

Source: https://context7_llms

Endpoints and documentation related to general API behavior, authorization, and introduction.

```APIDOC
## API Behavior

### Description
Global request/response conventions, error format, and dependency behavior.

### Endpoint
/api-reference/api-behavior.md

## Authorization

### Description
Authorize requests with your API key.

### Endpoint
/api-reference/authorization.md

## Introduction

### Description
Verify emails with Bolt Route's API before you send. A practical guide to verifying emails and protecting deliverability.

### Endpoint
/api-reference/introduction.md or /index.md

## Webhooks

### Description
Receive per-email and task completion webhook notifications.

### Endpoint
/api-reference/webhooks.md
```

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

### Get Credit Balance

Source: https://docs.boltroute.ai/integrations/make

Retrieve the current credit balance of your Bolt Route account.

```APIDOC
## GET /v1/billing/balance

### Description
Fetches the current credit balance for the account.

### Method
GET

### Endpoint
https://api.boltroute.ai/v1/billing/balance

### Response
#### Success Response (200)
- **balance** (number) - The current credit balance.

#### Response Example
```json
{
  "balance": 150.75
}
```
```

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

### Create Bulk Verification Task

Source: https://docs.boltroute.ai/integrations/make

Create a task to verify a list of email addresses. This is suitable for processing multiple emails efficiently.

```APIDOC
## POST /v1/verify/task

### Description
Creates a task to verify a list of email addresses. Supports up to 10,000 emails.

### Method
POST

### Endpoint
https://api.boltroute.ai/v1/verify/task

### Parameters
#### Request Body
- **emails** (array[string]) - Required - An array of email addresses to verify.
- **webhook_url** (string) - Optional - A URL to receive a callback when the task is completed.

### Request Example
```json
{
  "emails": [
    "test1@example.com",
    "test2@example.com"
  ],
  "webhook_url": "https://your.webhook.com/callback"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the verification task.

#### Response Example
```json
{
  "id": "task_abc123"
}
```
```

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

### Get Batch Upload Status

Source: https://docs.boltroute.ai/integrations/make

Check the processing status of a batch file upload.

```APIDOC
## GET /v1/verify/upload/{upload_id}/status

### Description
Checks the processing status of a batch file upload.

### Method
GET

### Endpoint
https://api.boltroute.ai/v1/verify/upload/{upload_id}/status

### Parameters
#### Path Parameters
- **upload_id** (string) - Required - The ID of the file upload.

### Response
#### Success Response (200)
- **status** (string) - The status of the upload (e.g., "pending", "processing", "completed", "failed").

#### Response Example
```json
{
  "status": "completed"
}
```
```

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

### Get Task Jobs

Source: https://docs.boltroute.ai/integrations/make

Retrieve detailed results for each email within a verification task.

```APIDOC
## GET /v1/verify/task/{task_id}/jobs

### Description
Retrieves detailed results for each email processed within a verification task.

### Method
GET

### Endpoint
https://api.boltroute.ai/v1/verify/task/{task_id}/jobs

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the verification task.

### Response
#### Success Response (200)
- **jobs** (array[object]) - A list of job objects, each containing details for a single email verification.
  - **email** (string) - The verified email address.
  - **status** (string) - The verification status for this email.
  - **is_disposable** (boolean) - Indicates if the email is disposable.
  - **is_role_based** (boolean) - Indicates if the email is role-based.

#### Response Example
```json
{
  "jobs": [
    {
      "email": "test1@example.com",
      "status": "valid",
      "is_disposable": false,
      "is_role_based": false
    },
    {
      "email": "test2@example.com",
      "status": "invalid",
      "is_disposable": false,
      "is_role_based": false
    }
  ]
}
```
```

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

### POST /plants

Source: https://docs.boltroute.ai/api-reference/endpoint/create

Creates a new plant in the store. This endpoint allows for the addition of new plant entries with specified details.

```APIDOC
## POST /plants

### Description
Creates a new plant in the store. This endpoint allows for the addition of new plant entries with specified details.

### Method
POST

### Endpoint
/plants

### Parameters
#### Request Body
- **name** (string) - Required - The name of the plant
- **tag** (string) - Optional - Tag to specify the type
- **id** (integer) - Required - Identification number of the plant

### Request Example
```json
{
  "name": "string",
  "tag": "string",
  "id": 0
}
```

### Response
#### Success Response (200)
- **name** (string) - The name of the plant
- **tag** (string) - Tag to specify the type
- **id** (integer) - Identification number of the plant

#### Response Example
```json
{
  "name": "string",
  "tag": "string",
  "id": 0
}
```

#### Error Response (400)
- **error** (integer) - Description of the error code
- **message** (string) - Description of the error message

#### Response Example
```json
{
  "error": 0,
  "message": "string"
}
```
```

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

### Create Plant API - OpenAPI Specification

Source: https://docs.boltroute.ai/api-reference/endpoint/create

Defines the OpenAPI 3.1.0 specification for creating a new plant in the store. It details the request body, response schemas for success and errors, and security schemes.

```yaml
POST /plants
openapi: 3.1.0
info:
  title: OpenAPI Plant Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: http://sandbox.mintlify.com
security:
  - bearerAuth: []
paths:
  /plants:
    post:
      description: Creates a new plant in the store
      requestBody:
        description: Plant to add to the store
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPlant'
        required: true
      responses:
        '200':
          description: plant response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plant'
        '400':
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    NewPlant:
      allOf:
        - $ref: '#/components/schemas/Plant'
        - required:
            - id
          type: object
          properties:
            id:
              description: Identification number of the plant
              type: integer
              format: int64
    Plant:
      required:
        - name
      type: object
      properties:
        name:
          description: The name of the plant
          type: string
        tag:
          description: Tag to specify the type
          type: string
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

```

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

### Batch Verification - Create Task API

Source: https://docs.boltroute.ai/api-reference/introduction

Submit a list of email addresses for batch verification and retrieve results upon completion.

```APIDOC
## POST /api/v1/batch-verification/tasks

### Description
Creates a new batch verification task by submitting a list of email addresses. You will receive a task ID to poll for results.

### Method
POST

### Endpoint
`/api/v1/batch-verification/tasks`

### Request Body
- **emails** (array of strings) - Required - A list of email addresses to verify.

### Request Example
```json
{
  "emails": [
    "test1@example.com",
    "test2@example.com"
  ]
}
```

### Response
#### Success Response (201)
- **task_id** (string) - The unique identifier for the batch verification task.

#### Response Example
```json
{
  "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

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

### Example Webhook Payload for Email Verification

Source: https://docs.boltroute.ai/scenarios/webhook-automation

This JSON object represents an example payload received by a webhook URL when an email verification task is completed. It includes the event type, task ID, completion timestamp, and detailed data about the verification result for a specific email address, including its status.

```json
{
  "event_type": "email_verification_completed",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "completed_at": "2025-01-01T12:01:12Z",
  "data": {
    "job": {
      "email_address": "user@example.com",
      "email": { "status": "valid" }
    }
  }
}
```

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

### Upload File for Batch Verification using cURL

Source: https://docs.boltroute.ai/api-reference/endpoints/file-upload/upload-file

This snippet demonstrates how to upload a file containing email addresses for batch verification using a cURL command. It specifies the API endpoint, the file to upload, an optional webhook URL for notifications, and the column containing email addresses.

```bash
curl -X POST \
  'https://api.boltroute.ai/api/v1/tasks/batch/upload' \
  -F 'file=@emails.csv' \
  -F 'webhook_url=https://example.com/webhook' \
  -F 'email_column=email'
```

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

### Get API Key Usage Data (Bash)

Source: https://docs.boltroute.ai/api-reference/endpoints/api-keys/get-key-usage

This snippet demonstrates how to retrieve usage data for a specific API key using a cURL command. It includes optional query parameters for specifying a date range to obtain daily usage series. The response provides detailed usage statistics and a time series if requested.

```bash
curl -X GET \
  'https://api.boltroute.ai/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000/usage?from=2025-01-01T00:00:00Z&to=2025-01-07T00:00:00Z'
```

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

### Metrics Controller API

Source: https://docs.boltroute.ai/api-reference/introduction

Retrieve verification metrics and monitor API usage over time.

```APIDOC
## GET /api/v1/metrics

### Description
Fetches API usage metrics, such as the number of verifications performed within a specified time range.

### Method
GET

### Endpoint
`/api/v1/metrics`

### Query Parameters
- **start_date** (string) - Optional - The start date for the metrics range (YYYY-MM-DD).
- **end_date** (string) - Optional - The end date for the metrics range (YYYY-MM-DD).

### Response
#### Success Response (200)
- **total_verifications** (integer) - The total number of email verifications performed.
- **valid_emails** (integer) - The number of valid emails verified.
- **invalid_emails** (integer) - The number of invalid emails verified.
- **date_range** (object) - The date range for which the metrics are provided.
  - **start** (string) - The start date of the range.
  - **end** (string) - The end date of the range.

#### Response Example
```json
{
  "total_verifications": 1500,
  "valid_emails": 1200,
  "invalid_emails": 300,
  "date_range": {
    "start": "2023-01-01",
    "end": "2023-01-31"
  }
}
```
```

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

### Realtime Signup Verification API

Source: https://context7_llms

This API endpoint enables real-time verification of emails during the signup or lead capture process, enforcing clear accept, hold, or reject rules.

```APIDOC
## POST /scenarios/realtime-signup-verification

### Description
Verify emails at signup or lead capture using realtime checks and clear accept/hold/reject rules.

### Method
POST

### Endpoint
/scenarios/realtime-signup-verification

### Parameters
#### Request Body
- **email** (string) - Required - The email address to verify.
- **rules** (object) - Optional - Rules for accepting, holding, or rejecting the email.
  - **accept** (array) - List of conditions to accept.
  - **hold** (array) - List of conditions to hold.
  - **reject** (array) - List of conditions to reject.

### Request Example
```json
{
  "email": "test@example.com",
  "rules": {
    "accept": ["valid_format"],
    "hold": ["unknown_domain"],
    "reject": ["disposable_email"]
  }
}
```

### Response
#### Success Response (200)
- **email** (string) - The verified email address.
- **status** (string) - The verification status (e.g., 'accepted', 'held', 'rejected').
- **reason** (string) - The reason for the status.

#### Response Example
```json
{
  "email": "test@example.com",
  "status": "accepted",
  "reason": "Email format is valid."
}
```
```

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

### POST /api/v1/tasks/batch/upload

Source: https://docs.boltroute.ai/api-reference/endpoints/file-upload/upload-file

Upload a file of email addresses for batch verification. Processing runs asynchronously, and you can optionally provide a webhook for completion notifications.

```APIDOC
## POST /api/v1/tasks/batch/upload

### Description
Upload a file containing email addresses to start a batch verification task. Processing runs asynchronously, and you can optionally provide a webhook for completion notifications.

### Method
POST

### Endpoint
/api/v1/tasks/batch/upload

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file** (file) - Required - The email list file. Supported extensions: `.txt`, `.csv`, `.xlsx`. Maximum of 10,000 emails per file.
- **webhook_url** (string) - Optional - Webhook URL for completion notifications.
- **email_column** (string or integer) - Optional - Column header or 1-based index for CSV/XLSX files. Not supported for `.txt` files.
- **column** (string or integer) - Optional - Alias for `email_column`.

### Request Example
```bash
curl -X POST \
  'https://api.boltroute.ai/api/v1/tasks/batch/upload' \
  -F 'file=@emails.csv' \
  -F 'webhook_url=https://example.com/webhook' \
  -F 'email_column=email'
```

### Response
#### Success Response (202 Accepted)
- **upload_id** (string) - UUID for this upload.
- **task_id** (string) - Task created for processing.
- **filename** (string) - Original file name.
- **email_count** (integer) - Emails queued for processing.
- **status** (string) - Current status (`processing`, `completed`, `failed`).
- **message** (string) - Human-readable status message.
- **uploaded_at** (string) - Timestamp of the upload.

#### Response Example
```json
{
  "upload_id": "7d3df4c6-9a7d-4d16-9f2b-2a5ddf4f4f53",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "emails.csv",
  "email_count": 123,
  "status": "processing",
  "message": "File uploaded successfully and is being processed",
  "uploaded_at": "2025-01-01T12:00:00Z"
}
```

#### Error Responses
- **400** Bad Request: File missing, unsupported file format, invalid file, invalid webhook URL, invalid `email_column`, no valid emails, email limit exceeded, or validation failures.
- **401** Unauthorized: Authentication failed.
- **402** Payment Required: Insufficient credit balance.
- **500** Internal Server Error: An unexpected error occurred on the server.
```

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

### Batch Verification - Get Task Results API

Source: https://docs.boltroute.ai/api-reference/introduction

Retrieve the results of a previously created batch verification task using its task ID.

```APIDOC
## GET /api/v1/batch-verification/tasks/{task_id}

### Description
Retrieves the results for a specific batch verification task.

### Method
GET

### Endpoint
`/api/v1/batch-verification/tasks/{task_id}`

### Path Parameters
- **task_id** (string) - Required - The ID of the batch verification task.

### Response
#### Success Response (200)
- **task_id** (string) - The unique identifier for the batch verification task.
- **status** (string) - The status of the task (e.g., 'processing', 'completed', 'failed').
- **results** (array of objects) - A list of verification results for each email, if the task is completed.
  - **email** (string) - The verified email address.
  - **status** (string) - The verification status for this email.
  - **is_disposable** (boolean) - Indicates if the email address is from a disposable domain.
  - **is_role_based** (boolean) - Indicates if the email address is a role-based address.
  - **is_catchall** (boolean) - Indicates if the email address is a catch-all address.

#### Response Example (if completed)
```json
{
  "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "status": "completed",
  "results": [
    {
      "email": "test1@example.com",
      "status": "valid",
      "is_disposable": false,
      "is_role_based": false,
      "is_catchall": false
    },
    {
      "email": "test2@example.com",
      "status": "invalid",
      "is_disposable": false,
      "is_role_based": false,
      "is_catchall": false
    }
  ]
}
```
```

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

### List Batch Verification Jobs (API Request)

Source: https://docs.boltroute.ai/api-reference/endpoints/batch-verification/task-jobs

Fetches a paginated list of email jobs for a specific batch verification task. Includes nested verification results when available. Requires a task ID and supports limit and offset parameters for pagination.

```bash
curl -X GET \
  'https://api.boltroute.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000/jobs?limit=10&offset=0'
```

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

### GET /api/v1/tasks/{id}

Source: https://docs.boltroute.ai/api-reference/endpoints/batch-verification/get-task

Retrieve a single batch verification task with its current status and aggregated metrics.

```APIDOC
## GET /api/v1/tasks/{id}

### Description
Fetch a single batch verification task with its current status and aggregated metrics.

### Method
GET

### Endpoint
/api/v1/tasks/{id}

### Parameters
#### Path Parameters
- **id** (UUID) - Required - The unique identifier of the batch verification task.

### Request Example
```bash
curl -X GET \
  'https://api.boltroute.ai/api/v1/tasks/550e8400-e29b-41d4-a716-446655440000'
```

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier of the task.
- **user_id** (string) - The identifier of the user who created the task.
- **webhook_url** (string) - The URL to send webhook notifications to.
- **is_file_backed** (boolean) - Indicates if the task is backed by a file.
- **file** (object) - Details about the associated file (if any).
  - **upload_id** (string) - The upload identifier of the file.
  - **task_id** (string) - The task identifier associated with the file.
  - **filename** (string) - The name of the file.
  - **email_count** (integer) - The number of emails in the file.
  - **status** (string) - The status of the file processing.
  - **created_at** (string) - The timestamp when the file was created.
  - **updated_at** (string) - The timestamp when the file was last updated.
- **source** (string) - The source of the task (e.g., 'frontend').
- **created_at** (string) - The timestamp when the task was created.
- **updated_at** (string) - The timestamp when the task was last updated.
- **started_at** (string) - The timestamp when the task started processing (null if not started).
- **finished_at** (string) - The timestamp when the task finished processing (null if not finished).
- **metrics** (object) - Aggregated metrics for the verification task.
  - **total_email_addresses** (integer) - The total number of email addresses processed.
  - **job_status** (object) - The status breakdown of the job.
    - **pending** (integer) - Number of pending jobs.
    - **processing** (integer) - Number of jobs currently processing.
    - **completed** (integer) - Number of completed jobs.
    - **failed** (integer) - Number of failed jobs.
  - **progress** (number) - The overall progress of the task (0.0 to 1.0).
  - **progress_percent** (integer) - The overall progress of the task in percentage.
  - **verification_status** (object) - The breakdown of verification statuses.
    - **valid** (integer) - Number of valid email addresses.
    - **invalid** (integer) - Number of invalid email addresses.
    - **catchall** (integer) - Number of catch-all email addresses.
    - **invalid_syntax** (integer) - Number of email addresses with invalid syntax.
    - **disposable_domain** (integer) - Number of email addresses from disposable domains.
    - **unknown** (integer) - Number of email addresses with unknown status.
    - **role_based** (integer) - Number of role-based email addresses.
    - **disposable_domain_emails** (integer) - Number of emails from disposable domains.
  - **last_verification_requested_at** (string) - The timestamp of the last verification request.
  - **last_verification_completed_at** (string) - The timestamp of the last verification completion.

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "webhook_url": "https://example.com/webhook",
  "is_file_backed": true,
  "file": {
    "upload_id": "550e8400-e29b-41d4-a716-446655440111",
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "emails.csv",
    "email_count": 123,
    "status": "completed",
    "created_at": "2025-01-01T12:00:00Z",
    "updated_at": "2025-01-01T12:05:00Z"
  },
  "source": "frontend",
  "created_at": "2025-01-01T12:00:00Z",
  "updated_at": "2025-01-01T12:05:00Z",
  "started_at": null,
  "finished_at": null,
  "metrics": {
    "total_email_addresses": 2,
    "job_status": {
      "pending": 0,
      "processing": 0,
      "completed": 2,
      "failed": 0
    },
    "progress": 1,
    "progress_percent": 100,
    "verification_status": {
      "valid": 2,
      "invalid": 0,
      "catchall": 0,
      "invalid_syntax": 0,
      "disposable_domain": 0,
      "unknown": 0,
      "role_based": 0,
      "disposable_domain_emails": 0
    },
    "last_verification_requested_at": "2025-01-01T12:00:01Z",
    "last_verification_completed_at": "2025-01-01T12:04:59Z"
  }
}
```

### Errors
- **400** invalid ID.
- **401** unauthorized.
- **404** batch verification task not found.
- **429** rate limited.
- **500** internal error.
```