POST

api

deep-research

Start deep research

curl --request POST \
  --url https://developer.thehog.ai/api/deep-research \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: <api-key>' \
  --header 'X-Secret-Key: <api-key>' \
  --data '
{
  "prompt": "Research AI CRM competitors",
  "schema": {
    "type": "object",
    "properties": {
      "competitors": {
        "type": "array"
      }
    }
  },
  "model": "<string>",
  "urls": [
    "<string>"
  ],
  "inputAnchors": [
    {
      "input_anchor": {
        "candidate_index": 1
      }
    }
  ],
  "maxCredits": 123,
  "budget": {
    "maxCredits": 123
  },
  "enrich": true,
  "confirm": true
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Access-Key': '<api-key>',
    'X-Secret-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'Research AI CRM competitors',
    schema: {type: 'object', properties: {competitors: {type: 'array'}}},
    model: '<string>',
    urls: ['<string>'],
    inputAnchors: [{input_anchor: {candidate_index: 1}}],
    maxCredits: 123,
    budget: {maxCredits: 123},
    enrich: true,
    confirm: true
  })
};

fetch('https://developer.thehog.ai/api/deep-research', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://developer.thehog.ai/api/deep-research"

payload = {
    "prompt": "Research AI CRM competitors",
    "schema": {
        "type": "object",
        "properties": { "competitors": { "type": "array" } }
    },
    "model": "<string>",
    "urls": ["<string>"],
    "inputAnchors": [{ "input_anchor": { "candidate_index": 1 } }],
    "maxCredits": 123,
    "budget": { "maxCredits": 123 },
    "enrich": True,
    "confirm": True
}
headers = {
    "X-Access-Key": "<api-key>",
    "X-Secret-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "operationId": "<string>",
  "status": "queued",
  "pollUrl": "<string>",
  "meta": {
    "schemaContract": {}
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "path": "/api/v1/search",
  "timestamp": "2026-05-21T09:08:10.000Z",
  "requestId": "506af9b3-01a9-43be-9eb4-8458fe3e4f5b",
  "errors": [
    {
      "property": "body.query",
      "message": "query must be a string",
      "constraints": {
        "isString": "query must be a string"
      }
    }
  ]
}

{
  "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"
}

{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Insufficient credits.",
  "path": "/api/v1/search",
  "timestamp": "2026-05-21T09:08:10.000Z",
  "requestId": "506af9b3-01a9-43be-9eb4-8458fe3e4f5b"
}

{
  "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"
}

POST /api/deep-research

Start an async LLM research job with a prompt and JSON Schema.

Kicks off an LLM-powered research job that browses the web and returns structured data conforming to your JSON Schema. Always async — returns 202 Accepted with an operation ID.

Example

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"}}}}'

Authorizations

X-Access-Key

string

header

required

The public API key from the Credentials page.

X-Secret-Key

string

header

required

The API secret shown when the credential is created.

Headers

Idempotency-Key

string

Prevents duplicate work if you retry the same request with the same key.

Body

application/json

prompt

string

required

Research instructions.

Example:

"Research AI CRM competitors"

schema

object

required

JSON Schema that defines the dynamic shape of result.data returned after the operation completes.

Example:

{
  "type": "object",
  "properties": { "competitors": { "type": "array" } }
}

model

string

Optional model override.

urls

string[]

Optional seed URLs to prioritize during research.

inputAnchors

object

object[]
object

maxCredits

integer<int32>

Maximum credits to spend. Must match budget.maxCredits when both are provided.

budget

object

Show child attributes

enrich

boolean

Set false to disable server-side schema enrichment and fill exactly the supplied schema. Closed schemas (additionalProperties:false) are never enriched.

confirm

boolean

Set true to continue after a confirmation_required estimate warning.

Response

Research job accepted. Poll the returned URL for status and results.

string

required

operationId

string

required

status

enum<string>

required

Available options:

queued

pollUrl

string

required

meta

object

Show child attributes

⌘I

Start deep research

curl --request POST \
  --url https://developer.thehog.ai/api/deep-research \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Key: <api-key>' \
  --header 'X-Secret-Key: <api-key>' \
  --data '
{
  "prompt": "Research AI CRM competitors",
  "schema": {
    "type": "object",
    "properties": {
      "competitors": {
        "type": "array"
      }
    }
  },
  "model": "<string>",
  "urls": [
    "<string>"
  ],
  "inputAnchors": [
    {
      "input_anchor": {
        "candidate_index": 1
      }
    }
  ],
  "maxCredits": 123,
  "budget": {
    "maxCredits": 123
  },
  "enrich": true,
  "confirm": true
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Access-Key': '<api-key>',
    'X-Secret-Key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: 'Research AI CRM competitors',
    schema: {type: 'object', properties: {competitors: {type: 'array'}}},
    model: '<string>',
    urls: ['<string>'],
    inputAnchors: [{input_anchor: {candidate_index: 1}}],
    maxCredits: 123,
    budget: {maxCredits: 123},
    enrich: true,
    confirm: true
  })
};

fetch('https://developer.thehog.ai/api/deep-research', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://developer.thehog.ai/api/deep-research"

payload = {
    "prompt": "Research AI CRM competitors",
    "schema": {
        "type": "object",
        "properties": { "competitors": { "type": "array" } }
    },
    "model": "<string>",
    "urls": ["<string>"],
    "inputAnchors": [{ "input_anchor": { "candidate_index": 1 } }],
    "maxCredits": 123,
    "budget": { "maxCredits": 123 },
    "enrich": True,
    "confirm": True
}
headers = {
    "X-Access-Key": "<api-key>",
    "X-Secret-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "<string>",
  "operationId": "<string>",
  "status": "queued",
  "pollUrl": "<string>",
  "meta": {
    "schemaContract": {}
  }
}

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "path": "/api/v1/search",
  "timestamp": "2026-05-21T09:08:10.000Z",
  "requestId": "506af9b3-01a9-43be-9eb4-8458fe3e4f5b",
  "errors": [
    {
      "property": "body.query",
      "message": "query must be a string",
      "constraints": {
        "isString": "query must be a string"
      }
    }
  ]
}

{
  "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"
}

{
  "statusCode": 402,
  "error": "Payment Required",
  "message": "Insufficient credits.",
  "path": "/api/v1/search",
  "timestamp": "2026-05-21T09:08:10.000Z",
  "requestId": "506af9b3-01a9-43be-9eb4-8458fe3e4f5b"
}

{
  "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"
}

Overview

Companies

People

Research

Enrichments

Monitors

Search

LinkedIn

X

Instagram

TikTok

Facebook

YouTube

Web

SEO

Image

Operations

Start deep research

POST /api/deep-research

Example

Authorizations

Headers

Body

Response

​POST /api/deep-research

​Example

Authorizations

Headers

Body

Response

POST /api/deep-research

Example