Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thehog.ai/llms.txt

Use this file to discover all available pages before exploring further.

Send a POST request to /api/deep-research to kick off an AI research job. You supply a natural-language research prompt and a JSON Schema that describes the shape of the data you want back. The Hog browses the web — including any seed URLs you provide — synthesizes findings using an LLM, and returns a structured result that conforms exactly to your schema. Because deep research jobs can take tens of seconds to minutes depending on complexity, this endpoint always returns 202 Accepted immediately. You then poll GET /api/operations/:id until the job completes.

​
Request

POST https://api.thehog.ai/api/deep-research

​
Headers

​
Idempotency-Key
string
Optional. If you send the same Idempotency-Key value from the same organization more than once, The Hog returns the existing queued operation instead of starting a new one. Use this to safely retry a request after a network failure without duplicating work.

​
Body

​
prompt
string
required
The research question or instruction. Be specific — the more context you provide, the more targeted the result. For example: “Find the current head of sales at Momentum AI, their LinkedIn URL, and the company’s most recent funding round details.”
​
schema
object
required
A valid JSON Schema object. The research result in the completed operation will conform to this schema. Use it to enforce structure — objects, arrays, string enums, and required fields are all supported.
​
model
string
Override the default research model. Contact support for available model identifiers.
​
urls
string[]
Seed URLs to include as starting points for the research crawl (e.g. a company’s LinkedIn profile or press page). The Hog will browse these in addition to conducting its own web search.
​
projectId
string
Attach this research job to a project for context and billing grouping.

​
Response

The endpoint always returns 202 Accepted. The body contains the operation ID and a poll URL.
​
id
string
required
The operation ID. Identical to operationId.
​
operationId
string
required
The operation ID to use when polling GET /api/operations/:id.
​
status
string
required
Always "queued" on the initial 202 response.
​
pollUrl
string
required
Convenience URL for polling. Equivalent to /api/operations/{operationId}.
​
meta
object
Optional metadata about the research job, such as schema contract validation details.

​
Polling for results

After receiving the 202, poll GET https://api.thehog.ai/api/operations/:id at 10–30 second intervals until status is "succeeded" or "failed". The result field on the completed operation will contain your structured data conforming to the schema you provided.
Deep research jobs are resource-intensive. Polling more frequently than every 10 seconds for these jobs will not speed up completion and may trigger rate limiting on the operations endpoint.

​
Examples

curl --request POST \
  --url https://api.thehog.ai/api/deep-research \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: research-momentum-ai-2026-05-06' \
  --data '{
    "prompt": "Research Momentum AI. Find: the company description, total funding raised, the name and LinkedIn URL of their current Head of Sales, and their top 3 competitors.",
    "schema": {
      "type": "object",
      "required": ["companyDescription", "totalFundingUsd", "headOfSales", "topCompetitors"],
      "properties": {
        "companyDescription": { "type": "string" },
        "totalFundingUsd": { "type": "number" },
        "headOfSales": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "linkedinUrl": { "type": "string" }
          }
        },
        "topCompetitors": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "urls": ["https://www.linkedin.com/company/momentum-ai"],
    "projectId": "proj_01HXYZ"
  }'