Requests, pagination & retries

The conventions every endpoint follows.

Requests and responses

• Base URL: https://v77trust.com/api/v1. HTTPS only.
• Send JSON with Content-Type: application/json (evidence uploads use multipart/form-data).
• Field names are camelCase. Times are ISO 8601 in UTC, e.g. 2026-11-08T09:30:00.000Z.
• Every object has an object field naming its type (ai_system, finding…) and an id.
• PATCH changes only the fields you send. Unknown fields are rejected, so typos don't pass silently.
• Every response has an X-Request-Id header. Quote it when you contact support.

Pagination

List endpoints return newest first, 25 per page by default (limit up to 100). When has_more is true, pass next_cursor as cursor to get the next page. Cursors stay correct while new records are added.

async function* allSystems() {
  let cursor = null;
  do {
    const url = new URL("https://v77trust.com/api/v1/systems");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.V77_API_KEY}` } });
    const page = await res.json();
    yield* page.data;
    cursor = page.next_cursor;
  } while (cursor);
}

Safe retries (Idempotency-Key)

Networks fail. To retry a POST without creating a duplicate, send an Idempotency-Key header with a unique value (a UUID). If V77 already handled that key, it returns the original response with Idempotent-Replayed: true instead of acting again. Keys are kept for 24 hours per workspace.

• Same key, different request body: 409 idempotency_key_reused.
• Same key while the first request is still running: 409 idempotency_in_progress. Wait and retry.
• If the first request failed with an error, nothing was stored and you can retry with the same key.

Rate limits

Each key can make 120 requests per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). Over the limit you get 429 rate_limited with a Retry-After header. Back off and retry; for bulk syncs, use limit=100 pages.

Which errors to retry

Versioning

The API is versioned in the path (/api/v1). Within v1 we only make additive changes: new endpoints, new optional fields, new enum values and new error codes. Write clients that ignore fields they don't know. Each response has a V77-Version header (currently 2026-11-01) naming the release you were served. Breaking changes would ship as /api/v2, announced well in advance in the changelog, with both versions running side by side during the move.