Core concepts

Idempotency

Retry a request that changes data without doing it twice. Send an Idempotency-Key, and Gemlead answers a repeat with the first result.

Send a key

Add the Idempotency-Key header to any POST, PATCH, PUT or DELETE. Use a value unique to the operation, up to 255 characters. A UUID v4 is a good choice.

If the connection drops before you get the answer, send the same request with the same key. Gemlead does the work once and gives you its result, so a webhook endpoint is never created twice.

Keys are kept 24 hours. GET requests never change data and need no key.

curl -X POST https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f1c4f5e-3b0a-4f7e-9d2c-6a8b1e2d4c7f" \
  -d '{
    "url": "https://example.com/webhooks/gemlead",
    "events": ["lead.hot"]
  }'

How Gemlead answers

Request	Answer
Same key, same method, path and body, within 24 hours	The first response again, same status and body, with the header `Idempotent-Replayed: true`.
Same key, another method, path or body	409 `idempotency_error` with the code `idempotency_key_reused`.
Same key while the first request still runs	409 with the code `idempotency_key_in_use`. Try again a second later.
A key longer than 255 characters	400 with the code `idempotency_key_invalid`.

When to retry

A network error or a timeout, retry with the same key.
A 500, retry with the same key after a short wait.
A 400, 401, 403 or 404, fix the request and send it with a new key.