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.

Network errors and timeouts are a normal part of distributed systems. When you fire off an async request to The Hog and the connection drops before you receive a response, you can’t be sure whether the job was created or not. Retrying blindly risks submitting the same job twice — consuming double the credits and producing duplicate results. Idempotency keys solve this by letting The Hog recognize a repeated request and return the existing job instead of creating a new one.

​
Supported endpoints

Idempotency keys are accepted on these async POST endpoints:
EndpointDescription
POST /api/people/enrichEmail and phone enrichment
POST /api/generateContext-aware content generation
POST /api/deep-researchLLM-powered deep research

​
How to use it

Include the Idempotency-Key header with a unique string value in your POST request. A UUID v4 is the recommended format. 
curl -X POST https://api.thehog.ai/api/deep-research \
  -H "Authorization: Bearer $THEHOG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -d '{
    "prompt": "What are the top strategic priorities for Acme Corp this quarter?",
    "schema": { "type": "object", "properties": { "priorities": { "type": "array", "items": { "type": "string" } } } }
  }'
If the request was already received with the same key, The Hog returns the existing operation — same operationId, same pollUrl — without creating a new job or charging additional credits. 
// Returned whether this is the first call or a retry — identical either way
{
  "operationId": "op_01HZ9K2QW3RV4M5N6P7Q8R9S0T",
  "status": "queued",
  "pollUrl": "https://api.thehog.ai/api/operations/op_01HZ9K2QW3RV4M5N6P7Q8R9S0T",
  "meta": {
    "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a",
    "estimatedCost": 40
  }
}

​
Key scope

Idempotency keys are scoped per organization. Two different organizations that happen to use the same key value are treated as completely independent requests — there is no cross-organization interference.

​
When to use idempotency keys

Network timeouts

If a request times out before you receive a response, retry with the same key. You’ll get back the existing job if it was received, or a new one if it wasn’t.

5xx retries

After a 500 or 503 error, retry with the same key. The Hog will not create a duplicate job if the first request was successfully enqueued before the error occurred.

Uncertain delivery

Any time you’re unsure whether a request arrived — load balancer resets, client crashes — include a key and retry freely.

At-least-once delivery

If your worker system guarantees at-least-once delivery, use a stable key derived from your internal job ID to make The Hog calls naturally idempotent.

​
Choosing a key

Generate a UUID v4 fresh for each logical request. Do not reuse a key across different requests that should produce different results. 
import { randomUUID } from 'crypto';

// Generate once per logical job, before the first attempt
const idempotencyKey = randomUUID();

// Use the same key for all retries of this specific job
const response = await fetch('https://api.thehog.ai/api/deep-research', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.THEHOG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({ prompt: '...', schema: { /* ... */ } }),
});
A key is only meaningful within your organization’s scope. Generate a new key for each distinct logical job — if you reuse the same key for genuinely different requests, the second request will return the result of the first one.