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/json with 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 are YYYY-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.

StatusWhen
400The request is invalid. The code says which field.
401invalid_api_key: missing, unknown or revoked key.
402The organization's billing blocks the action (payment_overdue).
403insufficient_scope: the key lacks the scope.
404not_found: no such resource in this workspace.
409The resource is in a state that does not allow this, or an idempotent request is still running.
413body_too_large: the body is over 1 MiB.
422idempotency_key_mismatch: an idempotency key was reused with a different request.
429rate_limited: too many requests.
5xxA 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:
            return
func 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

ResponseRetry?
Network error or timeoutYes, with the same idempotency key.
429Yes, after Retry-After.
5xxYes, with backoff and the same idempotency key.
409 idempotency_in_progressYes, after a short wait.
Other 4xxNo. Fix the request.

On this page