Conventions
Request and response format, errors, cursor pagination, idempotency keys and rate limits for the GraphKit API.
Format
- JSON in and out. Send
Content-Type: application/jsonwith a body. Request bodies are limited to 1 MiB (413 body_too_large). - Ids are UUIDs. Timestamps are RFC 3339 in UTC, for example
2026-11-15T10:04:05Z. Dates areYYYY-MM-DD. - Field names are camelCase. Unknown fields in a request body are rejected, so typos do not pass silently.
- A field that has no value is
null, not missing.
Errors
Every error has the same shape and a matching HTTP status:
{
"error": {
"code": "invalid_identities",
"message": "Send at least one identity."
}
}code is stable and safe to branch on; message is a sentence for people and may change. Some errors add a details object with counts.
| Status | When |
|---|---|
| 400 | The request is invalid. The code says which field. |
| 401 | invalid_api_key: missing, unknown or revoked key. |
| 402 | The organization's billing blocks the action (payment_overdue). |
| 403 | insufficient_scope: the key lacks the scope. |
| 404 | not_found: no such resource in this workspace. |
| 409 | The resource is in a state that does not allow this, or an idempotent request is still running. |
| 413 | body_too_large: the body is over 1 MiB. |
| 422 | idempotency_key_mismatch: an idempotency key was reused with a different request. |
| 429 | rate_limited: too many requests. |
| 5xx | A server error. Safe to retry with the same idempotency key. |
Pagination
List endpoints return results newest first, with a cursor:
{
"data": [{ "id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99" }],
"nextCursor": "eyJpZCI6IjAxOTNhNWIyIn0"
}Pass limit (1 to 100, default 50) and, for the next page, cursor set to the previous nextCursor. nextCursor is null on the last page. Cursors are opaque: do not build or change them.
async function* allLeads(key) {
let cursor = null;
do {
const url = new URL('https://app.graphkit.com/api/v1/leads');
url.searchParams.set('limit', '100');
if (cursor) url.searchParams.set('cursor', cursor);
const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
if (!res.ok) throw new Error((await res.json()).error.code);
const page = await res.json();
yield* page.data;
cursor = page.nextCursor;
} while (cursor);
}import requests
def all_leads(key):
cursor = None
while True:
params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
res = requests.get(
"https://app.graphkit.com/api/v1/leads",
headers={"Authorization": f"Bearer {key}"},
params=params,
timeout=30,
)
res.raise_for_status()
page = res.json()
yield from page["data"]
cursor = page["nextCursor"]
if not cursor:
returnfunc allLeads(ctx context.Context, key string, each func(json.RawMessage) error) error {
cursor := ""
for {
q := url.Values{"limit": {"100"}}
if cursor != "" {
q.Set("cursor", cursor)
}
req, err := http.NewRequestWithContext(ctx, http.MethodGet,
"https://app.graphkit.com/api/v1/leads?"+q.Encode(), nil)
if err != nil {
return err
}
req.Header.Set("Authorization", "Bearer "+key)
res, err := http.DefaultClient.Do(req)
if err != nil {
return err
}
var page struct {
Data []json.RawMessage `json:"data"`
NextCursor *string `json:"nextCursor"`
}
err = json.NewDecoder(res.Body).Decode(&page)
res.Body.Close()
if err != nil {
return err
}
for _, lead := range page.Data {
if err := each(lead); err != nil {
return err
}
}
if page.NextCursor == nil {
return nil
}
cursor = *page.NextCursor
}
}Idempotency
Every POST accepts an Idempotency-Key header: any string up to 255 characters that identifies the operation, such as your CRM's record id or a UUID you generate once per attempt.
- The first response with a key (status and body) is stored for 24 hours. A retry with the same key gets the same response, with the header
Idempotent-Replayed: true, and nothing happens twice. - Reusing a key with a different method, path or body returns
422 idempotency_key_mismatch. - Retrying while the first request is still running returns
409 idempotency_in_progress. Wait and retry. - Responses with a 5xx status are not stored, so a retry runs again.
- Keys are scoped to the API key: two keys cannot collide.
Send a key on every POST, and reuse it when you retry after a timeout or a connection error.
Rate limits
Each API key can make 300 requests per minute, with bursts of up to 300. Every response carries X-RateLimit-Limit: 300. Over the limit, the response is 429 rate_limited with a Retry-After header in seconds; wait that long before retrying.
For bulk work, prefer the batch endpoints: add up to 1,000 leads to a list or a campaign in one request, or enroll a whole list by listId.
Retries
| Response | Retry? |
|---|---|
| Network error or timeout | Yes, with the same idempotency key. |
| 429 | Yes, after Retry-After. |
| 5xx | Yes, with backoff and the same idempotency key. |
409 idempotency_in_progress | Yes, after a short wait. |
| Other 4xx | No. Fix the request. |