### Clone Example Repository

Source: https://docs.thehog.ai/guides/personalized-linkedin-outreach

Clone the example repository and navigate into its directory to follow along with the guide. This repository is self-contained and does not require additional package installations.

```bash
git clone https://github.com/the-hog/hog-linkedin-outreach
cd hog-linkedin-outreach
```

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

### Example Request for Company Search

Source: https://docs.thehog.ai/authentication

This example demonstrates how to authenticate and make a POST request to the /api/v1/companies/search endpoint using cURL, Python, and Node.js.

```APIDOC
## POST /api/v1/companies/search

### Description
Searches for companies based on a query and returns a limited set of results.

### Method
POST

### Endpoint
https://developer.thehog.ai/api/v1/companies/search

### Headers
- **X-Access-Key** (string) - Required - Your API access key.
- **X-Secret-Key** (string) - Required - Your API secret key.
- **Content-Type** (string) - Required - Must be `application/json`.

### Parameters
#### Request Body
- **query** (string) - Required - The search query for company names.
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```json
{
  "query": "Salesforce",
  "limit": 5
}
```

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
```json
{
  "example": "response body"
}
```

### Error Handling
- **401 Unauthorized**: Missing or invalid credentials. Verify your API key and API secret.
- **403 Forbidden**: Valid credentials but insufficient permissions. Check your plan and permissions.

Error Response Example:
```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or missing authentication credentials",
  "path": "/api/v1/companies/search",
  "requestId": "01HZXAMPLE000000000000000",
  "timestamp": "2025-06-01T12:00:00.000Z"
}
```
```

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

### Install Local MCP Server

Source: https://docs.thehog.ai/guides/local-mcp

Install The Hog's local stdio MCP server using npx. This command ensures you have the latest version of the MCP package.

```bash
npx -y @thehog/mcp@latest
```

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

### API Response Example

Source: https://docs.thehog.ai/guides/find-people

This is an example of the JSON response received after initiating a search operation. It includes an operation ID and a poll URL for status checking.

```json
{
  "id": "op_01hxyz",
  "operationId": "op_01hxyz",
  "status": "queued",
  "pollUrl": "/api/operations/op_01hxyz",
  "meta": {
    "requestId": "req_01hxyz"
  }
}
```

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

### Estimate Response Example

Source: https://docs.thehog.ai/concepts/sync-vs-async

This JSON object shows an example of an estimate response, which might include details like estimated credits, latency, and whether the operation is likely synchronous or asynchronous.

```json
{
  "data": {
    "estimatedCredits": 5,
    "likelySyncOrAsync": "async",
    "expectedLatencyRange": "10–30s",
    "expectedLookupDepth": 2,
    "withinPlanLimits": true
  },
  "meta": {
    "requestId": "req_estimate001"
  }
}
```

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

### Example LinkedIn Outreach Hooks Output

Source: https://docs.thehog.ai/guides/linkedin-outreach-hooks

This JSON structure shows an example of the output you might receive when generating LinkedIn outreach hooks. It includes profile information and a list of potential hooks based on user activity.

```json
{
  "profile": "https://www.linkedin.com/in/paulonasc",
  "hooks": [
    {
      "postUrl": "https://www.linkedin.com/feed/update/urn:li:activity:123",
      "signal": "commented on someone in their network's post",
      "hook": "They commented: \"Great breakdown.\" Reference the discussion around \"a recent LinkedIn post\"."
    },
    {
      "postUrl": "https://www.linkedin.com/feed/update/urn:li:activity:456",
      "signal": "reacted to someone in their network's post",
      "hook": "They reacted to a post about \"AI agents for sales workflows\". Use that topic as a light opener."
    }
  ]
}
```

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

### Scoped Search with Title and Location Filters

Source: https://docs.thehog.ai/guides/find-people

This example demonstrates how to narrow down search results by specifying titles, locations, and company domains.

```bash
curl -X POST https://developer.thehog.ai/api/v1/people/search \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "revenue leader",
      "filters": {
        "titles": ["VP Sales", "Chief Revenue Officer", "Head of Sales"],
        "locations": ["United States", "Canada"],
        "company": { "domains": ["salesforce.com"] }
      },
      "limit": 10
    }'
```

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

### Start Deep Research Job with Seed URLs and Model Override

Source: https://docs.thehog.ai/guides/deep-research

Initiates a deep research job using specified seed URLs and overriding the default model. This is useful for targeted research questions where you want to guide the AI's model choice.

```bash
curl -X POST https://developer.thehog.ai/api/deep-research \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "What are the top 5 CRM tools used by mid-market B2B SaaS companies in 2026? For each, note market share, pricing model, and key differentiator.",
      "schema": {
        "type": "object",
        "properties": {
          "tools": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "marketShare": { "type": "string" },
                "pricingModel": { "type": "string" },
                "keyDifferentiator": { "type": "string" }
              },
              "required": ["name"]
            }
          }
        },
        "required": ["tools"]
      },
      "model": "openai:gpt-4.1"
    }'
```

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

### Create Competitor Monitor

Source: https://docs.thehog.ai/guides/social-listening-x

Set up a monitor to track competitor pricing and customer complaints on X. This requires specifying competitor names and relevant keywords in the query.

```bash
curl -X POST https://developer.thehog.ai/api/v1/monitors \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "X: competitor pricing and complaints",
      "type": "x_keyword",
      "config": {
        "query": "(\"Competitor A\" OR \"Competitor B\") (pricing OR expensive OR outage OR alternative)"
      },
      "cadence_minutes": 60,
      "max_results": 25
    }'
```

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

### Example LinkedIn Profile URL

Source: https://docs.thehog.ai/guides/linkedin-outreach-hooks

This is an example of a LinkedIn profile URL that can be used with the API.

```text
https://www.linkedin.com/in/paulonasc
```

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

### Example API Request using Python (httpx)

Source: https://docs.thehog.ai/authentication

Shows how to perform a company search request using the httpx library in Python. Includes setting authentication headers and sending a JSON body.

```python
import httpx

response = httpx.post(
    "https://developer.thehog.ai/api/v1/companies/search",
    headers={
        "X-Access-Key": "ak_xxxxxxxxxxxxxxxx",
        "X-Secret-Key": "sk_xxxxxxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
    json={"query": "Salesforce", "limit": 5},
)
print(response.json())
```

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

### Example API Request using cURL

Source: https://docs.thehog.ai/authentication

Demonstrates how to make a POST request to the company search endpoint using cURL, including the necessary authentication headers and JSON payload.

```bash
curl -X POST https://developer.thehog.ai/api/v1/companies/search \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"query": "Salesforce", "limit": 5}'
```

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

### Example API Request using Node.js (fetch)

Source: https://docs.thehog.ai/authentication

Illustrates how to make a company search request in Node.js using the fetch API. Authentication headers and the JSON payload are included.

```javascript
const response = await fetch("https://developer.thehog.ai/api/v1/companies/search", {
  method: "POST",
  headers: {
    "X-Access-Key": "ak_xxxxxxxxxxxxxxxx",
    "X-Secret-Key": "sk_xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "Salesforce", limit: 5 }),
});
const data = await response.json();
```

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

### OpenAPI Specification for Get Monitor

Source: https://docs.thehog.ai/api/monitors/get

This OpenAPI specification defines the GET /api/v1/monitors/{id} endpoint, including request parameters, response schemas, and error handling.

```yaml
openapi: 3.0.0
info:
  title: The Hog API
  description: Public API reference for The Hog.
  version: '1.0'
  contact: {}
servers:
  - url: https://developer.thehog.ai
security: []
tags: []
paths:
  /api/v1/monitors/{id}:
    get:
      tags:
        - Monitors
      summary: Get monitor
      description: Retrieve a monitor by ID.
      operationId: getMonitor
      parameters:
        - name: id
          required: true
          in: path
          description: Monitor ID.
          schema:
            type: string
      responses:
        '200':
          description: Monitor details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonitorResponseDto'
        '401':
          description: Authentication is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 401
                error: Unauthorized
                message: Authentication is required.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 404
                error: Not Found
                message: Resource not found.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        '500':
          description: An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 500
                error: Internal Server Error
                message: An unexpected error occurred.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
      security:
        - AccessKey: []
          SecretKey: []
components:
  schemas:
    MonitorResponseDto:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum:
            - linkedin_keyword
            - linkedin_profile
            - linkedin_company
            - linkedin_post
            - instagram_profile
            - instagram_post
            - x_profile
            - x_keyword
            - reddit_keyword
            - reddit_subreddit
            - tiktok_keyword
            - tiktok_hashtag
            - web_search
            - site_search
        status:
          type: string
          enum:
            - active
            - paused
            - disabled
        config:
          type: object
          additionalProperties: true
        cadence_minutes:
          type: number
        last_run_at:
          type: string
          nullable: true
        next_run_at:
          type: string
          nullable: true
        consecutive_failures:
          type: number
        created_at:
          type: string
        updated_at:
          type: string
      required:
        - id
        - name
        - type
        - status
        - config
        - cadence_minutes
        - last_run_at
        - next_run_at
        - consecutive_failures
        - created_at
        - updated_at
    PublicErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 400
        error:
          type: string
          example: Bad Request
        message:
          type: string
          example: Validation failed
        path:
          type: string
          example: /api/v1/search
        requestId:
          type: string
          example: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        timestamp:
          type: string
          example: '2026-05-21T09:08:10.000Z'
        errors:
          type: array
          items:

```

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

### Making a Search Request and Identifying Request ID

Source: https://docs.thehog.ai/reference/error-handling

This example demonstrates how to make a POST request to the companies search endpoint using cURL. It shows how to include necessary headers and a JSON payload. The output highlights where to find the `X-Request-Id` header, which is crucial for support.

```bash
# The requestId is in the error body AND the X-Request-Id response header
curl -i -X POST https://developer.thehog.ai/api/v1/companies/search \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "acme"}'

# Look for:  X-Request-Id: 3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a
```

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

### OpenAPI Definition for Get Search Result

Source: https://docs.thehog.ai/api/search/get-result

This OpenAPI 3.0 definition outlines the GET /api/v1/search/{id} endpoint, including parameters, responses, and schema definitions for search results and errors.

```yaml
openapi: 3.0.0
info:
  title: The Hog API
  description: Public API reference for The Hog.
  version: '1.0'
  contact: {}
servers:
  - url: https://developer.thehog.ai
security: []
tags: []
paths:
  /api/v1/search/{id}:
    get:
      tags:
        - Search
      summary: Get search result
      description: Check the status of a search and retrieve the result once it completes.
      operationId: getSearchResult
      parameters:
        - name: id
          required: true
          in: path
          description: Search ID.
          schema:
            type: string
      responses:
        '200':
          description: Current search status, progress, result, or error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResultDto'
        '401':
          description: Authentication is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 401
                error: Unauthorized
                message: Authentication is required.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 404
                error: Not Found
                message: Resource not found.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        '429':
          description: Too many requests. Slow down before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 429
                error: Too Many Requests
                message: Too many requests.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        '500':
          description: An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 500
                error: Internal Server Error
                message: An unexpected error occurred.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
      security:
        - AccessKey: []
          SecretKey: []
components:
  schemas:
    SearchResultDto:
      type: object
      properties:
        id:
          type: string
          description: Unique search result ID
        status:
          type: string
          description: Current status
          enum:
            - queued
            - processing
            - succeeded
            - failed
        type:
          type: string
          description: Search type
          enum:
            - web_search
            - site_search
            - linkedin_keyword
            - x_keyword
            - reddit_search
            - tiktok_keyword
            - tiktok_hashtag
        query:
          type: string
          description: Original query
        poll_url:
          type: string
          description: URL to poll for result
        results:
          description: Search results array
          nullable: true
          type: array
          items:
            $ref: '#/components/schemas/SearchResultItemDto'
        total_results:
          type: number
          description: Total results found
          nullable: true
        error:
          description: Error details when failed
          nullable: true
          type: object
          allOf:
            - $ref: '#/components/schemas/SearchErrorDto'
        created_at:
          type: string

```

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

### Create Executive Profile Monitor

Source: https://docs.thehog.ai/guides/social-listening-x

Create a monitor to track posts from a specific executive's profile on X. You need to provide the executive's username in the configuration.

```bash
curl -X POST https://developer.thehog.ai/api/v1/monitors \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "X: CEO posts",
      "type": "x_profile",
      "config": {
        "username": "example_ceo"
      },
      "cadence_minutes": 60,
      "max_results": 10
    }'
```

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

### Idempotent POST Request with Idempotency-Key

Source: https://docs.thehog.ai/concepts/sync-vs-async

This example demonstrates how to make an asynchronous POST request using the Idempotency-Key header. Use a deterministic key to ensure safe retries after network failures.

```bash
curl -X POST https://developer.thehog.ai/api/enrichments \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: enrich-jane-doe-20260506" \
  -H "Content-Type: application/json" \
  -d '{ \
    "identifiers": [ \
      { "linkedin_url": "https://www.linkedin.com/in/jane-doe-example" }, \
      { "email": "jane@example.com" } \
    ], \
    "fields": ["contact.email", "contact.phone"] \
  }'
```

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

### OpenAPI Specification for Get Operation

Source: https://docs.thehog.ai/api/operations/get-operation

This OpenAPI specification defines the GET /api/operations/{id} endpoint, including request parameters, possible responses, and schema definitions for operation status and errors.

```yaml
openapi: 3.0.0
info:
  title: The Hog API
  description: Public API reference for The Hog.
  version: '1.0'
  contact: {}
servers:
  - url: https://developer.thehog.ai
security: []
tags: []
paths:
  /api/operations/{id}:
    get:
      tags:
        - Operations
      summary: Get operation
      description: >-
        Check the status of a background operation and retrieve its result once
        it completes.
      operationId: getOperation
      parameters:
        - name: id
          required: true
          in: path
          description: Operation ID.
          schema:
            type: string
      responses:
        '200':
          description: Current operation status, progress, result, or error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponseDto'
        '401':
          description: Authentication is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 401
                error: Unauthorized
                message: Authentication is required.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 404
                error: Not Found
                message: Resource not found.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        '429':
          description: Too many requests. Slow down before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 429
                error: Too Many Requests
                message: Too many requests.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        '500':
          description: An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 500
                error: Internal Server Error
                message: An unexpected error occurred.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
      security:
        - AccessKey: []
          SecretKey: []
components:
  schemas:
    OperationResponseDto:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - queued
            - processing
            - succeeded
            - failed
            - partial_success
            - cancelled
        progress:
          type: number
          nullable: true
        result:
          type: object
          nullable: true
          additionalProperties: true
        error:
          type: object
          nullable: true
          additionalProperties: true
      required:
        - id
        - status
    PublicErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 400
        error:
          type: string
          example: Bad Request
        message:
          type: string
          example: Validation failed
        path:
          type: string
          example: /api/v1/search
        requestId:
          type: string
          example: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        timestamp:
          type: string
          example: '2026-05-21T09:08:10.000Z'
        errors:
          type: array
          items:

```

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

### Create Hot Topic Monitor

Source: https://docs.thehog.ai/guides/social-listening-x

Use this snippet to create a monitor for tracking hot topics related to customer data platforms on X. Ensure you have the correct access and secret keys.

```bash
curl -X POST https://developer.thehog.ai/api/v1/monitors \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "X: customer data platform conversations",
      "type": "x_keyword",
      "config": {
        "query": "\"customer data platform\" OR \"CDP\""
      },
      "cadence_minutes": 60,
      "max_results": 25
    }'
```

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

### Create Monitor

Source: https://docs.thehog.ai/api-reference

Set up recurring monitors and poll detected events.

```APIDOC
## Create Monitor

### Description
Set up recurring monitors and poll detected events.

### Endpoint
/api/monitors/create
```

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

### Start Deep Research Job

Source: https://docs.thehog.ai/api/deep-research

Use this cURL command to start a deep research job. Replace placeholders with your actual access and secret keys. The request body includes the research prompt and the desired JSON schema for the output.

```bash
curl -X POST https://developer.thehog.ai/api/deep-research \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Research AI CRM competitors", "schema": {"type": "object", "properties": {"competitors": {"type": "array"}}}}'
```

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

### OpenAPI Specification for Get Enrichment

Source: https://docs.thehog.ai/api/enrichments/get-enrichment

This OpenAPI specification defines the GET /api/enrichments/{id} endpoint. It details the request parameters, authentication methods, and possible responses, including success (200) and various error codes (401, 404, 429, 500).

```yaml
openapi: 3.0.0
info:
  title: The Hog API
  description: Public API reference for The Hog.
  version: '1.0'
  contact: {}
servers:
  - url: https://developer.thehog.ai
security: []
tags: []
paths:
  /api/enrichments/{id}:
    get:
      tags:
        - Enrichments
      summary: Get enrichment
      description: >-
        Check the status of an enrichment request and retrieve the result once
        it completes.
      operationId: getEnrichment
      parameters:
        - name: id
          required: true
          in: path
          description: Enrichment operation ID.
          schema:
            type: string
      responses:
        '200':
          description: Current enrichment status, progress, result, or error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationResponseDto'
        '401':
          description: Authentication is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 401
                error: Unauthorized
                message: Authentication is required.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 404
                error: Not Found
                message: Resource not found.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        '429':
          description: Too many requests. Slow down before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 429
                error: Too Many Requests
                message: Too many requests.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        '500':
          description: An unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorResponseDto'
              example:
                statusCode: 500
                error: Internal Server Error
                message: An unexpected error occurred.
                path: /api/v1/search
                timestamp: '2026-05-21T09:08:10.000Z'
                requestId: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
      security:
        - AccessKey: []
          SecretKey: []
components:
  schemas:
    OperationResponseDto:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - queued
            - processing
            - succeeded
            - failed
            - partial_success
            - cancelled
        progress:
          type: number
          nullable: true
        result:
          type: object
          nullable: true
          additionalProperties: true
        error:
          type: object
          nullable: true
          additionalProperties: true
      required:
        - id
        - status
    PublicErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 400
        error:
          type: string
          example: Bad Request
        message:
          type: string
          example: Validation failed
        path:
          type: string
          example: /api/v1/search
        requestId:
          type: string
          example: 506af9b3-01a9-43be-9eb4-8458fe3e4f5b
        timestamp:
          type: string
          example: '2026-05-21T09:08:10.000Z'
        errors:
          type: array
          items:

```

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

### GET /api/v1/search/:id

Source: https://docs.thehog.ai/llms.txt

Poll for the results of a search operation using its unique identifier.

```APIDOC
## GET /api/v1/search/:id

### Description
Poll for search results.

### Method
GET

### Endpoint
/api/v1/search/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the search operation.

### Response
(No specific response details in the source, refer to linked documentation for schema)
```

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

### Local stdio MCP Package and Source

Source: https://docs.thehog.ai/guides/use-mcp

Information on the npm package and GitHub repository for the local stdio MCP, used when your client runs MCP servers on your machine.

```text
npm: [@thehog/mcp](https://www.npmjs.com/package/@thehog/mcp)
GitHub: [The-Hog/the-hog-mcp](https://github.com/The-Hog/the-hog-mcp)
```

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

### Set Environment Variables and Run Script

Source: https://docs.thehog.ai/guides/social-listening-x

This bash command sets the necessary API access and secret keys as environment variables and then executes the social listening script with a monitor ID and an optional since timestamp. Ensure the script is executable and the keys are valid.

```bash
export HOG_API_ACCESS_KEY="ak_xxxxxxxxxxxxxxxx"
export HOG_API_SECRET_KEY="sk_xxxxxxxxxxxxxxxx"

node x-social-listening.mjs mon_01hxyz 2024-01-01T00:00:00.000Z
```

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

### GET /api/operations/:id

Source: https://docs.thehog.ai/llms.txt

Poll the status of any asynchronous operation using its unique identifier.

```APIDOC
## GET /api/operations/:id

### Description
Poll the status of any asynchronous operation.

### Method
GET

### Endpoint
/api/operations/:id

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

### Response
(No specific response details in the source, refer to linked documentation for schema)
```

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

### GET /api/v1/monitors

Source: https://docs.thehog.ai/api/monitors/list

Lists all monitors for your organization, supporting optional status filtering and pagination.

```APIDOC
## GET /api/v1/monitors

### Description
List all monitors for your organization with pagination and optional status filtering.

### Method
GET

### Endpoint
/api/v1/monitors

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter monitors by status (e.g., 'active', 'paused', 'disabled').
- **limit** (number) - Optional - The maximum number of monitors to return per page.
- **cursor** (string) - Optional - A cursor for fetching the next page of results.

### Request Example
```bash
curl https://developer.thehog.ai/api/v1/monitors?status=active \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"
```

### Response
#### Success Response (200)
- **data** (array) - An array of Monitor objects.
  - **id** (string) - The unique identifier of the monitor.
  - **name** (string) - The name of the monitor.
  - **type** (string) - The type of monitor (e.g., 'linkedin_keyword', 'web_search').
  - **status** (string) - The current status of the monitor ('active', 'paused', 'disabled').
  - **config** (object) - Configuration details for the monitor.
- **next_cursor** (string) - A cursor to retrieve the next page of results. Null if there are no more pages.

#### Error Response (401)
- **statusCode** (number) - HTTP status code (401).
- **error** (string) - Error type ('Unauthorized').
- **message** (string) - Error message.
- **path** (string) - Request path.
- **timestamp** (string) - Timestamp of the error.
- **requestId** (string) - Unique identifier for the request.

#### Error Response (404)
- **statusCode** (number) - HTTP status code (404).
- **error** (string) - Error type ('Not Found').
- **message** (string) - Error message.
- **path** (string) - Request path.
- **timestamp** (string) - Timestamp of the error.
- **requestId** (string) - Unique identifier for the request.

#### Error Response (500)
- **statusCode** (number) - HTTP status code (500).
- **error** (string) - Error type ('Internal Server Error').
- **message** (string) - Error message.
- **path** (string) - Request path.
- **timestamp** (string) - Timestamp of the error.
- **requestId** (string) - Unique identifier for the request.
```

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

### List MCP Servers with Claude

Source: https://docs.thehog.ai/guides/local-mcp

Verify that the server is connected by listing all registered MCP servers using the Claude CLI.

```bash
claude mcp list
```

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

### GET /api/v1/monitors/:id/events

Source: https://docs.thehog.ai/llms.txt

Retrieve a list of events that have been detected by a specific monitor, identified by its ID.

```APIDOC
## GET /api/v1/monitors/:id/events

### Description
List events detected by a specific monitor.

### Method
GET

### Endpoint
/api/v1/monitors/:id/events

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

### Response
(No specific response details in the source, refer to linked documentation for schema)
```

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

### GET /api/v1/search

Source: https://docs.thehog.ai/api/search/list

Lists all search operations performed by your organization. Supports filtering by type and pagination.

```APIDOC
## GET /api/v1/search

### Description
List previous searches for your organization.

### Method
GET

### Endpoint
/api/v1/search

### Parameters
#### Query Parameters
- **type** (string) - Optional - Filter by search type
- **limit** (number) - Optional - Page size (max 200)
- **cursor** (string) - Optional - Pagination cursor (created_at ISO)

### Request Example
```bash
curl https://developer.thehog.ai/api/v1/search?limit=5 \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx"
```

### Response
#### Success Response (200)
- **data** (array) - Array of search results.
- **next_cursor** (string) - A cursor for fetching the next page of results.

#### Response Example
```json
{
  "data": [
    {
      "id": "string",
      "status": "string",
      "type": "string",
      "query": "string",
      "poll_url": "string",
      "results": [],
      "total_results": 0,
      "error": null
    }
  ],
  "next_cursor": "string"
}
```

#### Error Response (401)
- **statusCode** (number) - The HTTP status code.
- **error** (string) - The error type.
- **message** (string) - A description of the error.
- **path** (string) - The request path.
- **timestamp** (string) - The time the error occurred.
- **requestId** (string) - A unique identifier for the request.

#### Error Response (500)
- **statusCode** (number) - The HTTP status code.
- **error** (string) - The error type.
- **message** (string) - A description of the error.
- **path** (string) - The request path.
- **timestamp** (string) - The time the error occurred.
- **requestId** (string) - A unique identifier for the request.
```

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

### Create Monitor

Source: https://docs.thehog.ai/api/monitors/create

Creates a new monitor of a specified type with configurable parameters. Supports various sources like LinkedIn, Instagram, X, Reddit, TikTok, and web searches.

```APIDOC
## POST /monitors

### Description
Creates a new monitor. The type of monitor and its configuration depend on the `type` field.

### Method
POST

### Endpoint
/monitors

### Request Body
- **name** (string) - Required - The name of the monitor.
- **type** (string) - Required - The type of monitor to create. Supported types include: `linkedin_keyword`, `linkedin_profile`, `linkedin_company`, `linkedin_post`, `instagram_profile`, `instagram_post`, `x_profile`, `x_keyword`, `reddit_keyword`, `reddit_subreddit`, `tiktok_keyword`, `tiktok_hashtag`, `web_search`, `site_search`.
- **config** (object) - Required - Configuration specific to the monitor type.
  - **query** (string) - Required for certain types - The search query.
  - **max_results** (number) - Optional - Max results per run (1-100). Defaults to 10.
  - **cadence_minutes** (number) - Optional - Cadence in minutes. Minimum 60 for scraper-based types, minimum 15 for web types. Defaults to 60.
  - **force_fresh** (boolean) - Optional - Force fresh scrape bypassing cache. Defaults to false.
  - **cache_ttl_days** (number) - Optional - Cache TTL in days for profile/company monitors (1-90). Defaults to 14.
  - **post_url** (string) - Required for `linkedin_post` type - The LinkedIn post URL.

### Request Example
```json
{
  "name": "hiring engineers",
  "type": "linkedin_profile",
  "config": {
    "query": "hiring engineers",
    "max_results": 20,
    "cadence_minutes": 60
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the monitor.
- **name** (string) - The name of the monitor.
- **type** (string) - The type of the monitor.
- **status** (string) - The current status of the monitor (`active`, `paused`, `disabled`).
- **config** (object) - The configuration of the monitor.
- **cadence_minutes** (number) - The cadence in minutes.
- **last_run_at** (string, nullable) - Timestamp of the last run.
- **next_run_at** (string, nullable) - Timestamp of the next scheduled run.
- **consecutive_failures** (number) - Number of consecutive failures.
- **created_at** (string) - Timestamp when the monitor was created.
- **updated_at** (string) - Timestamp when the monitor was last updated.

#### Response Example
```json
{
  "id": "monitor-12345",
  "name": "hiring engineers",
  "type": "linkedin_profile",
  "status": "active",
  "config": {
    "query": "hiring engineers",
    "max_results": 20,
    "cadence_minutes": 60
  },
  "cadence_minutes": 60,
  "last_run_at": "2023-10-27T10:00:00Z",
  "next_run_at": "2023-10-27T11:00:00Z",
  "consecutive_failures": 0,
  "created_at": "2023-10-27T09:00:00Z",
  "updated_at": "2023-10-27T09:00:00Z"
}
```

### Error Handling
- **400 Bad Request**: Returned if the request body is invalid or missing required fields.
- **401 Unauthorized**: Returned if the API key is invalid or missing.
- **404 Not Found**: Returned if the specified resource does not exist.
- **500 Internal Server Error**: Returned if an unexpected error occurs on the server.
```

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

### POST /api/v1/platform/scrapers/instagram/followers

Source: https://docs.thehog.ai/api/scrapers/instagram-followers

Get followers for an Instagram account. Retrieve followers of a public Instagram account.

```APIDOC
## POST /api/v1/platform/scrapers/instagram/followers

### Description
Fetch followers for an Instagram username. Retrieve followers of a public Instagram account.

### Method
POST

### Endpoint
/api/v1/platform/scrapers/instagram/followers

### Parameters
#### Request Body
- **username** (string) - Required - The Instagram username to fetch followers for.
- **maxFollowers** (integer) - Optional - The maximum number of followers to retrieve.

### Request Example
```json
{
  "username": "instagram",
  "maxFollowers": 100
}
```

### Response
#### Success Response (200)
- **data** (object) - The list of followers.
- **meta** (object) - Metadata about the response.

#### Response Example
```json
{
  "data": {},
  "meta": {}
}
```

#### Error Response
- **400**: Bad Request - The request body or parameters are invalid.
- **401**: Unauthorized - Authentication is required.
- **402**: Payment Required - The organization does not have enough credits for this request.
- **500**: Internal Server Error - An unexpected error occurred.
- **502**: Bad Gateway - The upstream service could not complete the request.
```

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

### Web Search API Request Example

Source: https://docs.thehog.ai/api/scrapers/web-search

Use this cURL command to perform a web search and retrieve results. Ensure you replace placeholder keys with your actual access and secret keys. The request body specifies the search query and the maximum number of results.

```bash
curl -X POST https://developer.thehog.ai/api/v1/platform/scrapers/web/search \
  -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
  -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "AI CRM tools", "maxResults": 10}'
```