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.
The Hog uses two response patterns depending on how long an operation takes. Fast operations return data immediately in the response body with a 200 status. Operations that require more processing time — like enriching large contact lists or running deep research — return a 202 Accepted response with an operation ID you can poll until the work is done. Knowing which pattern to expect helps you design your integration correctly from the start.
Sync operations (200)
These calls complete quickly and return data directly in the response. You don’t need to do anything after the initial request.
| Endpoint | Description |
|---|
POST /api/companies/search | Firmographic and technographic company search |
POST /api/people/search | People search with ICP ranking |
POST /api/people/researches | Cross-platform identity resolution and research dossier |
POST /api/context | Assembled GTM context (messaging, personas, signals) |
POST /api/signals | Classified intent and event signals |
Async operations (202)
These calls kick off background work and return immediately with a poll URL. You retrieve the result by polling GET /api/operations/:id until the status reaches succeeded or failed.
| Endpoint | Async trigger |
|---|
POST /api/people/enrich | When asyncPreferred: true is set in the request body |
POST /api/generate | Long-form or complex content generation |
POST /api/deep-research | Always async — LLM-powered deep research |
Sync response (200)
Async accepted (202)
Polling response (200)
Data is available immediately in the data field.{
"data": [
{
"id": "comp_xyz789",
"name": "Acme Corp",
"industry": "Software",
"employee_count": 220,
"is_hiring": true
}
],
"meta": {
"requestId": "req_aabbccdd",
"projectId": "proj_abc123",
"cost": { "estimated": 2, "actual": 2 }
}
}
The response contains an operation ID and a URL to poll. No result data yet.{
"operationId": "op_99887766",
"status": "queued",
"pollUrl": "/api/operations/op_99887766",
"meta": {
"requestId": "req_11223344",
"estimatedCost": 5
}
}
Call GET /api/operations/:id to check progress. When status is succeeded, result contains the full output.{
"id": "op_99887766",
"status": "succeeded",
"progress": 100,
"result": {
"email": "jane.doe@acme.com",
"phone": "+1-555-0100",
"emailVerified": true
},
"error": null
}
How to poll
Once you have an operationId, call GET /api/operations/:id on a schedule until the status is terminal.
curl https://api.thehog.ai/api/operations/op_99887766 \
-H "Authorization: Bearer <your-api-key>"
Operation status values
| Status | Meaning |
|---|
queued | Work is waiting to start |
processing | Work is in progress — check progress for a 0–100 estimate |
succeeded | Work is complete — read the result field |
failed | Work failed — read the error field for details |
partial_success | Some results were returned; check both result and error |
cancelled | The operation was cancelled before completion |
Don’t poll more aggressively than once per second. The operations endpoint has a dedicated rate limit. If you exceed it, you’ll receive a 429 response.
Recommended polling strategy
# Simple polling loop — wait 2 seconds between checks
while true; do
RESPONSE=$(curl -s https://api.thehog.ai/api/operations/op_99887766 \
-H "Authorization: Bearer <your-api-key>")
STATUS=$(echo $RESPONSE | jq -r '.status')
echo "Status: $STATUS"
if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]; then
echo $RESPONSE | jq '.result // .error'
break
fi
sleep 2
done
Pre-flight estimates
Before running an expensive async operation, you can call the corresponding /estimate endpoint to see the projected cost and whether the call will run synchronously or asynchronously — without consuming any credits.
| Estimate endpoint | Estimates for |
|---|
POST /api/people/enrich/estimate | People enrichment |
POST /api/people/researches/estimate | Identity research |
POST /api/generate/estimate | Content generation |
{
"data": {
"estimatedCredits": 5,
"likelySyncOrAsync": "async",
"expectedLatencyRange": "10–30s",
"providersLikelyUsed": ["provider-a", "provider-b"],
"withinPlanLimits": true
},
"meta": {
"requestId": "req_estimate001",
"projectId": "proj_abc123"
}
}
Idempotency
For async POST requests, you can supply an Idempotency-Key header. If you retry the same request with the same key within the idempotency window, the API returns the original response rather than creating a duplicate operation.
curl -X POST https://api.thehog.ai/api/people/enrich \
-H "Authorization: Bearer <your-api-key>" \
-H "Idempotency-Key: enrich-jane-doe-20260506" \
-H "Content-Type: application/json" \
-d '{
"identities": [
{ "platform": "linkedin", "username": "jane-doe-example" }
],
"asyncPreferred": true
}'
Use a deterministic idempotency key — such as a hash of the request payload or a stable record ID — so that retries after a network failure are safe and don’t double-charge credits.