### API Key Format Example

Source: https://docs.maverickintelligence.co/authentication

API keys follow a specific format: 'mk_live_' followed by 40 random hexadecimal characters. This is an example of a valid key format.

```text
mk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
```

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

### Get Recent Visitors

Source: https://docs.maverickintelligence.co/examples/javascript

Fetches people records created since yesterday. This example shows how to use date-based filtering.

```javascript
const yesterday = new Date(Date.now() - 86400000).toISOString();

const { data: recent } = await apiRequest("/v1/people", {
  since: yesterday,
});

console.log(`People seen since yesterday: ${recent.length}`);
```

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

### Example API Request with API Key

Source: https://docs.maverickintelligence.co/authentication

Demonstrates how to include your API key in the `X-API-Key` header for authentication.

```APIDOC
## Example API Request with API Key

### Description
Demonstrates how to include your API key in the `X-API-Key` header for authentication.

### Method
GET

### Endpoint
https://api-v1.maverickintelligence.co/v1/people

### Parameters
#### Headers
- **X-API-Key** (string) - Required - Your API key for authentication.

### Request Example
```bash
curl -H "X-API-Key: mk_live_a1b2c3d4e5f6..." \
  https://api-v1.maverickintelligence.co/v1/people
```

### Response
#### Success Response (200)
(Response details not provided in source)

#### Error Response Examples
| Status | Code           | Description                           |
| ------ | -------------- | ------------------------------------- |
| 401    | `unauthorized` | Missing API key (header not provided) |
| 403    | `forbidden`    | Invalid or revoked API key            |
```

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

### Debugging API Requests

Source: https://docs.maverickintelligence.co/errors

Example of how to make a curl request and identify the X-Request-Id header for debugging purposes.

```bash
curl -v -H "X-API-Key: mk_live-..." https://api-v1.maverickintelligence.co/v1/people

# Response headers:
# X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
```

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

### Get Statistics

Source: https://docs.maverickintelligence.co/examples/curl

Retrieve general statistics from the API. An API key is required.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/stats"
```

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

### Paginate Through Results

Source: https://docs.maverickintelligence.co/

Continue fetching results by using the `nextCursor` provided in the previous response. This example shows how to append the cursor to the request.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=10&cursor=eyJQSy..."

```

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

### Get statistics

Source: https://docs.maverickintelligence.co/examples/curl

Retrieves general statistics about the system or data.

```APIDOC
## Get statistics

### Description
Retrieves general statistics.

### Method
GET

### Endpoint
/v1/stats

### Request Example
```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/stats"
```
```

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

### Setup Maverick Intelligence API Client

Source: https://docs.maverickintelligence.co/examples/python

Import necessary libraries and configure API credentials and base URL. Replace 'mk_live_your_key_here' with your actual API key.

```python
import requests

API_KEY = "mk_live_your_key_here"
BASE_URL = "https://api-v1.maverickintelligence.co"
HEADERS = {"X-API-Key": API_KEY}
```

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

### List People - cURL Example

Source: https://docs.maverickintelligence.co/api-reference/list-people

Use this cURL command to make a request to the List People endpoint. Ensure you replace 'mk_live_your_key_here' with your actual API key.

```bash
curl -H "X-API-Key: mk_live_your_key_here"
    https://api-v1.maverickintelligence.co/v1/people
```

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

### Authenticate API Request with cURL

Source: https://docs.maverickintelligence.co/authentication

Include your API key in the 'X-API-Key' header for every request to authenticate with the API. This example shows how to do this using cURL.

```bash
curl -H "X-API-Key: mk_live_a1b2c3d4e5f6..." \
  https://api-v1.maverickintelligence.co/v1/people
```

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

### OpenAPI Specification for GET /v1/people/{id}

Source: https://docs.maverickintelligence.co/api-reference/get-person

This OpenAPI 3.0.3 specification defines the GET /v1/people/{id} endpoint for retrieving person details. It includes authentication, rate limiting, and pagination information.

```yaml
GET /v1/people/{id}
openapi: 3.0.3
info:
  title: Maverick Intelligence API
  description: >
    Programmatic access to your Maverick Intelligence data — identified website
    visitors,

    companies,

    events, and analytics.


    ## Authentication

    All endpoints (except `/v1/health`) require an API key passed in the
    `X-API-Key` header.


    ```bash

    curl -H "X-API-Key: mk_live_your_key_here"
    https://api-v1.maverickintelligence.co/v1/people

    ```


    ## Rate Limiting

    - **1,000 requests per hour** per customer (shared across all API keys)

    - Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining`
    headers

    - When exceeded, you'll receive a `429` response with a `Retry-After` header


    ## Pagination

    List endpoints use cursor-based pagination. Pass the `nextCursor` from the
    response

    as the `cursor` query parameter to fetch the next page.


    ## Sorting

    Results are sorted by most recently seen first (`lastSeen` descending).

```

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

### Get Person Details

Source: https://docs.maverickintelligence.co/

Looks up a specific visitor by their unique ID.

```APIDOC
## GET /v1/people/{personId}

### Description
Looks up a specific visitor by their unique ID.

### Method
GET

### Endpoint
/v1/people/{personId}

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

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the person.
- **email** (string) - The person's email address.
- **businessEmail** (string) - The person's business email address.
- **personalEmail** (string) - The person's personal email address.
- **firstName** (string) - The person's first name.
- **lastName** (string) - The person's last name.
- **title** (string) - The person's job title.
- **company** (string) - The name of the company the person is associated with.
- **phone** (string) - The person's phone number.
- **profileImageUrl** (string) - The URL of the person's profile image.
- **trafficType** (string) - The type of traffic that led to the identification.
- **isHotLead** (boolean) - Indicates if the person is a hot lead.
- **visitCount** (integer) - The number of visits by this person.

### Response Example
```json
{
  "id": "abc123",
  "email": "jane@acme.com",
  "businessEmail": "jane@acme.com",
  "personalEmail": "jane.doe@gmail.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "title": "VP Engineering",
  "company": "Acme Corp",
  "phone": "+1 (555) 012-3456",
  "profileImageUrl": "https://...",
  "trafficType": "organic",
  "isHotLead": true,
  "visitCount": 7
}
```
```

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

### Setup API Request Function

Source: https://docs.maverickintelligence.co/examples/javascript

Defines a reusable asynchronous function for making authenticated requests to the Maverick Intelligence API. Ensure your API key is correctly set.

```javascript
const API_KEY = "mk_live_your_key_here";
const BASE_URL = "https://api-v1.maverickintelligence.co";

async function apiRequest(path, params = {}) {
  const url = new URL(`${BASE_URL}${path}`);
  Object.entries(params).forEach(([key, value]) => {
    if (value !== undefined) url.searchParams.set(key, value);
  });

  const response = await fetch(url, {
    headers: { "X-API-Key": API_KEY },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || `HTTP ${response.status}`);
  }

  return response.json();
}
```

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

### Get a Single Company

Source: https://docs.maverickintelligence.co/examples/curl

Retrieve details for a specific company using its unique identifier. An API key is required.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/companies/xyz789"
```

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

### OpenAPI Specification for Get Company

Source: https://docs.maverickintelligence.co/api-reference/get-company

This OpenAPI 3.0.3 specification defines the GET /v1/companies/{id} endpoint. It details the request parameters, including the company ID, and the structure of the successful 200 OK response, which includes company data. It also specifies the 404 Not Found error response.

```yaml
GET /v1/companies/{id}
openapi: 3.0.3
info:
  title: Maverick Intelligence API
  description: >
    Programmatic access to your Maverick Intelligence data — identified website
    visitors,

    companies, events, and analytics.


  ## Authentication

  All endpoints (except `/v1/health`) require an API key passed in the
  `X-API-Key` header.


  ```bash

  curl -H "X-API-Key: mk_live_your_key_here"
  https://api-v1.maverickintelligence.co/v1/people

  ```


  ## Rate Limiting

  - **1,000 requests per hour** per customer (shared across all API keys)

  - Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining`
    headers

  - When exceeded, you'll receive a `429` response with a `Retry-After` header


  ## Pagination

  List endpoints use cursor-based pagination. Pass the `nextCursor` from the
  response
  as the `cursor` query parameter to fetch the next page.


  ## Sorting

  Results are sorted by most recently seen first (`lastSeen` descending).

  Custom sorting options will be available in a future version.
  version: 1.0.0
  contact:
    name: Maverick Intelligence Support
    email: nick@maverickintelligence.co
    url: https://maverickintelligence.co
servers:
  - url: https://api-v1.maverickintelligence.co
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: System
    description: API health and status
  - name: People
    description: Identified website visitors
  - name: Events
    description: Behavioral events (page views, clicks, scrolls)
  - name: Companies
    description: Companies identified from visitors
  - name: Statistics
    description: Aggregate analytics
paths:
  /v1/companies/{id}:
    get:
      tags:
        - Companies
      summary: Get a company
      description: Returns details for a single identified company.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Company ID
      responses:
        '200':
          description: Company details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Company'
        '404':
          description: Company not found
components:
  schemas:
    Company:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          nullable: true
        domain:
          type: string
          nullable: true
        standardizedIndustry:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        linkedinUrl:
          type: string
          nullable: true
          description: Company LinkedIn profile URL
        employeeCount:
          type: integer
          nullable: true
        visitCount:
          type: integer
        firstSeen:
          type: string
          format: date-time
        lastSeen:
          type: string
          format: date-time
        isHotCompany:
          type: boolean
        trafficType:
          type: string
          nullable: true
          description: How visitors from this company arrived
        adPlatform:
          type: string
          nullable: true
          description: Ad platform if traffic type is paid
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key in format: mk_live_{40 hex chars}'

```

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

### OpenAPI Specification for GET /v1/stats

Source: https://docs.maverickintelligence.co/api-reference/stats

This OpenAPI 3.0.3 specification defines the GET /v1/stats endpoint, which returns aggregate dashboard statistics. It includes details on authentication, rate limiting, and pagination.

```yaml
openapi: 3.0.3
info:
  title: Maverick Intelligence API
  description: >
    Programmatic access to your Maverick Intelligence data — identified website
    visitors,

    companies, events, and analytics.


  ## Authentication

  All endpoints (except `/v1/health`) require an API key passed in the
  `X-API-Key` header.


  ```bash

  curl -H "X-API-Key: mk_live_your_key_here"
  https://api-v1.maverickintelligence.co/v1/people

  ```


  ## Rate Limiting

  - **1,000 requests per hour** per customer (shared across all API keys)

  - Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining`
    headers

  - When exceeded, you'll receive a `429` response with a `Retry-After` header


  ## Pagination

  List endpoints use cursor-based pagination. Pass the `nextCursor` from the
  response

  as the `cursor` query parameter to fetch the next page.


  ## Sorting

  Results are sorted by most recently seen first (`lastSeen` descending).

  Custom sorting options will be available in a future version.
  version: 1.0.0
  contact:
    name: Maverick Intelligence Support
    email: nick@maverickintelligence.co
    url: https://maverickintelligence.co
servers:
  - url: https://api-v1.maverickintelligence.co
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: System
    description: API health and status
  - name: People
    description: Identified website visitors
  - name: Events
    description: Behavioral events (page views, clicks, scrolls)
  - name: Companies
    description: Companies identified from visitors
  - name: Statistics
    description: Aggregate analytics
paths:
  /v1/stats:
    get:
      tags:
        - Statistics
      summary: Get statistics
      description: >
        Returns aggregate dashboard statistics including total people,
        companies,

        recent events, and daily averages.


        Note: This endpoint may have higher latency than list endpoints because

        it aggregates data across all records.
      responses:
        '200': 
          description: Dashboard statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Stats'
components:
  schemas:
    Stats:
      type: object
      properties:
        totalPeople:
          type: integer
        totalCompanies:
          type: integer
        recentEvents:
          type: integer
          description: Pixel events in the last 30 days
        periodDays:
          type: integer
        dailyAverage:
          type: number
        generatedAt:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key in format: mk_live_{40 hex chars}'

```

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

### Get Person Details

Source: https://docs.maverickintelligence.co/introduction

Retrieve detailed information for a specific visitor by their unique ID.

```APIDOC
## GET /v1/people/{personId}

### Description
Retrieves detailed information for a specific visitor identified by their unique ID.

### Method
GET

### Endpoint
/v1/people/{personId}

### Parameters
#### Path Parameters
- **personId** (string) - Required - The unique identifier of the person to retrieve.
```

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

### Get a Single Person

Source: https://docs.maverickintelligence.co/examples/curl

Retrieve details for a specific person using their unique identifier. An API key is required.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people/abc123"
```

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

### Paginate Through People

Source: https://docs.maverickintelligence.co/examples/curl

Fetch people data in pages using the 'limit' and 'cursor' parameters. Use the 'nextCursor' from the previous response to get the next set of results.

```bash
# First page
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=50"

# Next page (use nextCursor from previous response)
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=50&cursor=eyJQSy..."
```

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

### Get Hot Leads Only

Source: https://docs.maverickintelligence.co/examples/python

Retrieves a list of people identified as hot leads. Limits the results to 50 records.

```python
response = requests.get(
    f"{BASE_URL}/v1/people",
    headers=HEADERS,
    params={\"hot_leads_only\": \"true\", \"limit\": 50},
)
hot_leads = response.json()["data"]

for lead in hot_leads:
    print(f"{lead['firstName']} {lead['lastName']} - {lead['company']}")
```

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

### Get Person

Source: https://docs.maverickintelligence.co/llms.txt

Returns details for a single identified person. This endpoint provides specific information about an individual.

```APIDOC
## GET /person/{id}

### Description
Returns details for a single identified person.

### Method
GET

### Endpoint
/person/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the person.
```

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

### Get Person by ID

Source: https://docs.maverickintelligence.co/api-reference/get-person

Fetches the details of a single person identified by their unique ID.

```APIDOC
## GET /v1/people/{id}

### Description
Returns details for a single identified person.

### Method
GET

### Endpoint
/v1/people/{id}

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

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the person.
- **name** (string) - The name of the person.
- **email** (string) - The email address of the person.
- **company** (string) - The company the person is associated with.
- **lastSeen** (string) - The timestamp when the person was last seen.

#### Response Example
{
  "id": "person_123",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "company": "Example Corp",
  "lastSeen": "2023-10-27T10:00:00Z"
}
```

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

### Get Dashboard Statistics

Source: https://docs.maverickintelligence.co/examples/python

Fetches key statistics from the dashboard, including total people, total companies, and recent events.

```python
response = requests.get(f"{BASE_URL}/v1/stats", headers=HEADERS)
stats = response.json()["data"]

print(f"Total people: {stats['totalPeople']}")
print(f"Total companies: {stats['totalCompanies']}")
print(f"Events (30d): {stats['recentEvents']}")
```

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

### Get Person Events

Source: https://docs.maverickintelligence.co/examples/curl

Retrieve events associated with a specific person, including a summary object. An API key is required.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people/abc123/events?limit=100"
```

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

### Get Person Events with Context

Source: https://docs.maverickintelligence.co/examples/python

Retrieves events for a specific person, including their summary details in the same response. This avoids a second API call to fetch person information.

```python
person_id = "abc123"
response = requests.get(
    f"{BASE_URL}/v1/people/{person_id}/events",
    headers=HEADERS,
    params={"limit": 100},
)
result = response.json()

# Person summary included — no second API call needed
person = result["person"]
print(f"Events for {person['firstName']} {person['lastName']} ({person['company']})")

for event in result["data"]:
    print(f"  {event['timestamp']} - {event['eventType']} - {event['url']}")
```

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

### Get person events

Source: https://docs.maverickintelligence.co/examples/curl

Retrieves events associated with a specific person, including a summary of the person's details.

```APIDOC
## Get person events (includes person summary)

### Description
Retrieves events associated with a specific person. The response includes a `person` object with their name, email, and company.

### Method
GET

### Endpoint
/v1/people/{person_id}/events

### Parameters
#### Path Parameters
- **person_id** (string) - Required - The unique identifier of the person whose events are to be retrieved.

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

### Request Example
```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people/abc123/events?limit=100"
```
```

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

### List People OpenAPI Specification

Source: https://docs.maverickintelligence.co/api-reference/list-people

This OpenAPI 3.0.3 specification defines the GET /v1/people endpoint, including parameters, responses, and schemas for people data.

```yaml
GET /v1/people
openapi: 3.0.3
info:
  title: Maverick Intelligence API
  description: >
    Programmatic access to your Maverick Intelligence data — identified website
    visitors,

    companies, events, and analytics.


  ## Authentication

  All endpoints (except `/v1/health`) require an API key passed in the
  `X-API-Key` header.


  ```bash

  curl -H "X-API-Key: mk_live_your_key_here"
  https://api-v1.maverickintelligence.co/v1/people

  ```


  ## Rate Limiting

  - **1,000 requests per hour** per customer (shared across all API keys)

  - Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining`
    headers

  - When exceeded, you'll receive a `429` response with a `Retry-After` header


  ## Pagination

  List endpoints use cursor-based pagination. Pass the `nextCursor` from the
  response

  as the `cursor` query parameter to fetch the next page.


  ## Sorting

  Results are sorted by most recently seen first (`lastSeen` descending).

  Custom sorting options will be available in a future version.
  version: 1.0.0
  contact:
    name: Maverick Intelligence Support
    email: nick@maverickintelligence.co
    url: https://maverickintelligence.co
servers:
  - url: https://api-v1.maverickintelligence.co
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: System
    description: API health and status
  - name: People
    description: Identified website visitors
  - name: Events
    description: Behavioral events (page views, clicks, scrolls)
  - name: Companies
    description: Companies identified from visitors
  - name: Statistics
    description: Aggregate analytics
paths:
  /v1/people:
    get:
      tags:
        - People
      summary: List people
      description: |
        Returns a paginated list of identified website visitors.
        Results are sorted by most recently seen first.
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/since'
        - name: hot_leads_only
          in: query
          schema:
            type: boolean
          description: Filter to only ICP-matched hot leads
      responses:
        '200':
          description: List of people
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Person'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          description: Bad request (invalid parameters)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (missing or invalid API key)
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 100
      description: Number of records per page
    cursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Pagination cursor from the previous response's `nextCursor`
    since:
      name: since
      in: query
      schema:
        type: string
        format: date-time
      description: Only return records with `lastSeen` after this ISO 8601 date
  headers:
    X-Request-Id:
      schema:
        type: string
        format: uuid
      description: Unique request identifier for debugging
    X-RateLimit-Limit:
      schema:
        type: integer
      description: Maximum requests per hour
    X-RateLimit-Remaining:
      schema:
        type: integer
      description: Remaining requests this hour
    Retry-After:
      schema:
        type: integer
      description: Seconds until rate limit resets (only on 429 responses)
  schemas:
    Person:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          nullable: true

```

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

### Get Company

Source: https://docs.maverickintelligence.co/llms.txt

Returns details for a single identified company. This endpoint allows retrieval of specific company information based on an identifier.

```APIDOC
## GET /company/{id}

### Description
Returns details for a single identified company.

### Method
GET

### Endpoint
/company/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the company.
```

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

### Get Hot Leads

Source: https://docs.maverickintelligence.co/examples/javascript

Retrieves a list of hot leads, limited to 50 results. This snippet demonstrates filtering for specific lead types.

```javascript
const { data: hotLeads } = await apiRequest("/v1/people", {
  hot_leads_only: "true",
  limit: 50,
});

hotLeads.forEach((lead) => {
  console.log(`${lead.firstName} ${lead.lastName} - ${lead.company}`);
});
```

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

### Get a Person's Events

Source: https://docs.maverickintelligence.co/examples/python

Retrieves all events associated with a specific person ID. Includes person summary and event data.

```python
person_id = "abc123"
response = requests.get(
    f"{BASE_URL}/v1/people/{person_id}/events",
    headers=HEADERS,
    params={"limit": 100},
)
result = response.json()

# Person summary is included at the top level
person = result["person"]
print(f"Events for {person['firstName']} {person['lastName']}")

for event in result["data"]:
    print(f"  {event['timestamp']} - {event['eventType']} - {event['url']}")
```

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

### List Companies OpenAPI Specification

Source: https://docs.maverickintelligence.co/api-reference/list-companies

The OpenAPI 3.0.3 specification for the GET /v1/companies endpoint. This details the request parameters, response structure, and data schemas.

```yaml
GET /v1/companies
openapi: 3.0.3
info:
  title: Maverick Intelligence API
  description: >
    Programmatic access to your Maverick Intelligence data — identified website
    visitors,

    companies, events, and analytics.


    ## Authentication

    All endpoints (except `/v1/health`) require an API key passed in the
    `X-API-Key` header.


    ```bash

    curl -H "X-API-Key: mk_live_your_key_here"
    https://api-v1.maverickintelligence.co/v1/people

    ```


    ## Rate Limiting

    - **1,000 requests per hour** per customer (shared across all API keys)

    - Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining`
    headers

    - When exceeded, you'll receive a `429` response with a `Retry-After` header


    ## Pagination

    List endpoints use cursor-based pagination. Pass the `nextCursor` from the
    response
    as the `cursor` query parameter to fetch the next page.


    ## Sorting

    Results are sorted by most recently seen first (`lastSeen` descending).

    Custom sorting options will be available in a future version.
  version: 1.0.0
  contact:
    name: Maverick Intelligence Support
    email: nick@maverickintelligence.co
    url: https://maverickintelligence.co
servers:
  - url: https://api-v1.maverickintelligence.co
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: System
    description: API health and status
  - name: People
    description: Identified website visitors
  - name: Events
    description: Behavioral events (page views, clicks, scrolls)
  - name: Companies
    description: Companies identified from visitors
  - name: Statistics
    description: Aggregate analytics
paths:
  /v1/companies:
    get:
      tags:
        - Companies
      summary: List companies
      description: |
        Returns a paginated list of companies identified from website visitors.
        Results are sorted by most recently seen first.
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/since'
      responses:
        '200':
          description: List of companies
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Company'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
components:
  parameters:
    limit:
      name: limit
      in: query
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 100
      description: Number of records per page
    cursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Pagination cursor from the previous response's `nextCursor`
    since:
      name: since
      in: query
      schema:
        type: string
        format: date-time
      description: Only return records with `lastSeen` after this ISO 8601 date
  schemas:
    Company:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          nullable: true
        domain:
          type: string
          nullable: true
        standardizedIndustry:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        region:
          type: string
          nullable: true
        linkedinUrl:
          type: string
          nullable: true
          description: Company LinkedIn profile URL
        employeeCount:
          type: integer
          nullable: true
        visitCount:
          type: integer
        firstSeen:
          type: string
          format: date-time
        lastSeen:
          type: string
          format: date-time
        isHotCompany:
          type: boolean
        trafficType:
          type: string
          nullable: true
          description: How visitors from this company arrived
        adPlatform:
          type: string
          nullable: true
          description: Ad platform if traffic type is paid
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          description: Requested page size
        count:
          type: integer
          description: Number of items in this page
        nextCursor:
          type: string
          nullable: true
          description: Pass this as `cursor` to get the next page. Null when no more pages.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key in format: mk_live_{40 hex chars}'

```

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

### Get Dashboard Stats

Source: https://docs.maverickintelligence.co/examples/javascript

Fetches key statistics from the dashboard, such as total people, companies, and recent events. This provides a high-level overview of your data.

```javascript
const { data: stats } = await apiRequest("/v1/stats");

console.log(`Total people: ${stats.totalPeople}`);
console.log(`Total companies: ${stats.totalCompanies}`);
console.log(`Events (30d): ${stats.recentEvents}`);
```

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

### Get a Person by ID

Source: https://docs.maverickintelligence.co/api-reference/get-person

Fetches detailed information about a single identified person using their unique identifier. This is useful for understanding individual visitor behavior and characteristics.

```APIDOC
## GET /v1/people/{id}

### Description
Returns details for a single identified person.

### Method
GET

### Endpoint
/v1/people/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Person ID

### Response
#### Success Response (200)
- **data** (object) - Person details

#### Error Response (404)
- **error** (object) - Error details if the person is not found.

```

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

### Get Company by ID

Source: https://docs.maverickintelligence.co/api-reference/get-company

Fetches detailed information for a single company using its unique identifier. This includes company name, domain, industry, location, LinkedIn URL, employee count, and visit statistics.

```APIDOC
## GET /v1/companies/{id}

### Description
Returns details for a single identified company.

### Method
GET

### Endpoint
/v1/companies/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Company ID

### Response
#### Success Response (200)
- **data** (Company) - Company details

#### Response Example
```json
{
  "data": {
    "id": "string",
    "name": "string | null",
    "domain": "string | null",
    "standardizedIndustry": "string | null",
    "location": "string | null",
    "region": "string | null",
    "linkedinUrl": "string | null",
    "employeeCount": "integer | null",
    "visitCount": "integer",
    "firstSeen": "string (date-time)",
    "lastSeen": "string (date-time)",
    "isHotCompany": "boolean",
    "trafficType": "string | null",
    "adPlatform": "string | null"
  }
}
```

#### Error Response (404)
Company not found
```

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

### List Person Events OpenAPI Specification

Source: https://docs.maverickintelligence.co/api-reference/list-person-events

This OpenAPI specification defines the GET /v1/people/{id}/events endpoint for retrieving event data for a specific person. It includes details on request parameters and response structure.

```yaml
GET /v1/people/{id}/events
openapi: 3.0.3
info:
  title: Maverick Intelligence API
  description: >
    Programmatic access to your Maverick Intelligence data — identified website
    visitors,

    companies,
    events,
    and analytics.


    ## Authentication

    All endpoints (except `/v1/health`) require an API key passed in the
    `X-API-Key` header.


    ```bash

    curl -H "X-API-Key: mk_live_your_key_here"
    https://api-v1.maverickintelligence.co/v1/people

    ```


    ## Rate Limiting

    - **1,000 requests per hour** per customer (shared across all API keys)

    - Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining`
    headers

    - When exceeded, you'll receive a `429` response with a `Retry-After` header


    ## Pagination

    List endpoints use cursor-based pagination. Pass the `nextCursor` from the
    response

    as the `cursor` query parameter to fetch the next page.


    ## Sorting

    Results are sorted by most recently seen first (`lastSeen` descending).

```

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

### Get Statistics

Source: https://docs.maverickintelligence.co/

Pulls dashboard-level analytics data.

```APIDOC
## GET /v1/statistics

### Description
Pulls dashboard-level analytics data.

### Method
GET

### Endpoint
/v1/statistics

### Query Parameters
- **startDate** (string) - Optional - The start date for the statistics period (YYYY-MM-DD).
- **endDate** (string) - Optional - The end date for the statistics period (YYYY-MM-DD).

### Response
#### Success Response (200)
- **totalVisits** (integer) - The total number of visits.
- **uniqueVisitors** (integer) - The number of unique visitors.
- **newVisitors** (integer) - The number of new visitors.
- **returningVisitors** (integer) - The number of returning visitors.
- **averageVisitDuration** (integer) - The average duration of a visit in seconds.

### Response Example
```json
{
  "totalVisits": 1500,
  "uniqueVisitors": 750,
  "newVisitors": 400,
  "returningVisitors": 350,
  "averageVisitDuration": 120
}
```
```

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

### Fetch Identified Visitors

Source: https://docs.maverickintelligence.co/introduction

Make your first API request to list identified people. Ensure you replace 'mk_live_your_key_here' with your actual API key.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  https://api-v1.maverickintelligence.co/v1/people?limit=10
```

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

### GET /v1/health

Source: https://docs.maverickintelligence.co/api-reference/health

Checks if the API is operational. This endpoint does not require any authentication.

```APIDOC
## GET /v1/health

### Description
Returns API status. No authentication required.

### Method
GET

### Endpoint
/v1/health

### Parameters

### Request Example

### Response
#### Success Response (200)
- **status** (string) - Example: ok
- **version** (string) - Example: v1

#### Response Example
```json
{
  "status": "ok",
  "version": "v1"
}
```
```

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

### Check Rate Limit Headers

Source: https://docs.maverickintelligence.co/examples/curl

Make a request and filter the verbose output to inspect rate limit headers, retry-after information, and request IDs. An API key is required.

```bash
curl -v -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=1" 2>&1 | grep -i "x-ratelimit\|retry-after\|x-request-id"
```

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

### Get a single company

Source: https://docs.maverickintelligence.co/examples/curl

Retrieves details for a specific company using its unique identifier.

```APIDOC
## Get a single company

### Description
Retrieves the details of a specific company using its unique ID.

### Method
GET

### Endpoint
/v1/companies/{company_id}

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

### Request Example
```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/companies/xyz789"
```
```

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

### Check rate limit headers

Source: https://docs.maverickintelligence.co/examples/curl

Demonstrates how to check rate limit headers by making a request and filtering the output for relevant headers.

```APIDOC
## Check rate limit headers

### Description
Demonstrates how to check rate limit headers by making a request and filtering the output for relevant headers like `X-RateLimit`, `Retry-After`, and `X-Request-ID`.

### Method
GET

### Endpoint
/v1/people

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

### Request Example
```bash
curl -v -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=1" 2>&1 | grep -i "x-ratelimit\|retry-after\|x-request-id"
```
```

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

### Paginate Through Results

Source: https://docs.maverickintelligence.co/introduction

Continue fetching results by using the `nextCursor` provided in the previous response. This allows for retrieving subsequent pages of data.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=10&cursor=eyJQSy..."
```

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

### List People with API Key

Source: https://docs.maverickintelligence.co/examples/curl

Retrieve a list of people, applying a limit to the number of results. An API key is required for authentication.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?limit=10"
```

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

### Get Statistics

Source: https://docs.maverickintelligence.co/llms.txt

Returns aggregate dashboard analytics. This endpoint provides summary statistics for the platform.

```APIDOC
## GET /stats

### Description
Returns aggregate dashboard analytics.

### Method
GET

### Endpoint
/stats
```

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

### List People Endpoint

Source: https://docs.maverickintelligence.co/

Fetch a list of identified visitors with a limit of 10. Requires an API key for authentication.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  https://api-v1.maverickintelligence.co/v1/people?limit=10

```

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

### List People with Hot Leads Filter

Source: https://docs.maverickintelligence.co/examples/curl

Retrieve a list of people, filtering specifically for hot leads. An API key is required.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?hot_leads_only=true"
```

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

### Base URL for API

Source: https://docs.maverickintelligence.co/

The base URL for all API requests. All endpoints are prefixed with `/v1/`.

```bash
https://api-v1.maverickintelligence.co

```

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

### Perform a Health Check

Source: https://docs.maverickintelligence.co/examples/curl

Use this endpoint to verify the API is running. No authentication is required.

```bash
curl https://api-v1.maverickintelligence.co/v1/health
```

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

### List All People with Pagination

Source: https://docs.maverickintelligence.co/examples/python

Fetches all people records by paginating through the API results. Handles 'nextCursor' for subsequent requests.

```python
def get_all_people():
    """Fetch all people by paginating through all pages."""
    people = []
    cursor = None

    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor

        response = requests.get(
            f"{BASE_URL}/v1/people",
            headers=HEADERS,
            params=params,
        )
        response.raise_for_status()
        data = response.json()

        people.extend(data["data"])

        cursor = data["pagination"].get("nextCursor")
        if not cursor:
            break

    return people

people = get_all_people()
print(f"Total people: {len(people)}")
```

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

### Handling Rate Limits in Python

Source: https://docs.maverickintelligence.co/rate-limits

This Python function demonstrates how to make API requests and handle rate limiting by implementing exponential backoff. It retries requests after waiting for the duration specified in the `Retry-After` header when a 429 status code is received.

```python
import time
import requests

def api_request(url, api_key, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers={"X-API-Key": api_key})

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue

        return response.json()

    raise Exception("Max retries exceeded")
```

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

### List Companies

Source: https://docs.maverickintelligence.co/examples/curl

Retrieve a list of companies, applying a limit to the number of results. An API key is required.

```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/companies?limit=50"
```

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

### Get hot leads only

Source: https://docs.maverickintelligence.co/examples/curl

Filters the list of people to retrieve only hot leads. This is a specific filtering option for the people endpoint.

```APIDOC
## Get hot leads only

### Description
Filters the list of people to retrieve only those marked as hot leads.

### Method
GET

### Endpoint
/v1/people

### Query Parameters
- **hot_leads_only** (boolean) - Optional - If true, only hot leads are returned.

### Request Example
```bash
curl -H "X-API-Key: mk_live_your_key_here" \
  "https://api-v1.maverickintelligence.co/v1/people?hot_leads_only=true"
```
```