> ## 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.

# Idempotency

# Idempotent Requests with The Hog API

> Pass the Idempotency-Key header on async POST requests to safely retry without creating duplicate jobs. The key is scoped to your organization.

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:

| Endpoint                        | Description               |
| ------------------------------- | ------------------------- |
| `POST /api/enrichments`         | Contact enrichment        |
| `POST /api/deep-research`       | LLM-powered deep research |
| `POST /api/v1/search`           | Multi-platform search     |
| `POST /api/v1/companies/search` | Company discovery         |
| `POST /api/v1/people/search`    | People discovery          |

## 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.

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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" \
  -H "Idempotency-Key: example-idempotency-key" \
  -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.

```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Returned whether this is the first call or a retry — identical either way
{
  "operationId": "op_01HZ9K2QW3RV4M5N6P7Q8R9S0T",
  "status": "queued",
  "pollUrl": "https://developer.thehog.ai/api/operations/op_01HZ9K2QW3RV4M5N6P7Q8R9S0T",
  "meta": {
    "requestId": "3f7a1c2e-88b4-4d0e-a1f5-0c9e2b3d7f4a"
  }
}
```

## 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

<CardGroup cols={2}>
  <Card title="Network timeouts" icon="wifi">
    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.
  </Card>

  <Card title="5xx retries" icon="server">
    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.
  </Card>

  <Card title="Uncertain delivery" icon="circle-question">
    Any time you're unsure whether a request arrived — load balancer resets, client crashes — include a key and retry freely.
  </Card>

  <Card title="At-least-once delivery" icon="arrows-rotate">
    If your worker system guarantees at-least-once delivery, use a stable key derived from your own job ID to make The Hog calls naturally idempotent.
  </Card>
</CardGroup>

## 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.

```javascript theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
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://developer.thehog.ai/api/deep-research', {
  method: 'POST',
  headers: {
    'X-Access-Key': process.env.THEHOG_ACCESS_KEY,
    'X-Secret-Key': process.env.THEHOG_SECRET_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({ prompt: '...', schema: { /* ... */ } }),
});
```

<Note>
  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.
</Note>