Requests, pagination and limits

JSON envelopes

Successful single-resource responses use:

{ "data": {}, "request_id": "req_example" }

Lists add pagination fields:

{
  "data": [],
  "has_more": true,
  "next_cursor": "opaque-cursor",
  "request_id": "req_example"
}

Unknown JSON body properties are rejected with unknown_field. This catches a typo in a write instead of silently discarding it.

Query parameters behave differently: unrecognised ones are ignored, not rejected. Analytics tools and proxies routinely append their own (utm_*, cf_*), and failing an otherwise valid request because of one would be hostile.

Defaults

Defaults are chosen for safe interactive use. For example, usage defaults to the last 30 days and translations default to 25 recent, non-archived records. A requested list limit above 100 is clamped to 100.

Dates and timestamps use ISO 8601. JSON field names are snake_case. Fields that are not yet applicable are usually null so resource shapes stay stable across a translation lifecycle.

Cursor pagination

Pass next_cursor from one response into the next request unchanged. Stop when it is null or has_more is false.

let cursor;
do {
  const url = new URL('https://api.ai-glot.com/v1/batches');
  url.searchParams.set('limit', '100');
  if (cursor) url.searchParams.set('cursor', cursor);

  const page = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.AIGLOT_API_KEY}` },
  }).then(response => response.json());

  for (const translation of page.data) console.log(translation.id);
  cursor = page.next_cursor;
} while (cursor);

Do not construct or modify cursors. Cursor pagination prevents a newly created translation from shifting rows between pages.

Rate limits

Each credential has a sustained limit of 240 requests per minute and a burst ceiling of 40 requests per 10 seconds. A 429 response includes Retry-After; wait for it before retrying.

Every response carries a RateLimit-Policy header describing both windows:

RateLimit-Policy: 240;w=60, 40;w=10

It states the policy only. No remaining-request count is published, so pace requests against the documented limits and treat 429 plus Retry-After as the signal to back off.

Request IDs and retries

Every response carries a request ID in both the payload (request_id) and the X-Request-Id header. Include it when asking for support.

Retry 429, 500, 502, 503 and 504 with exponential backoff and jitter. Do not retry validation, authentication, permission or not-found errors without changing the request.

Trailing slashes are tolerated. The REST API intentionally sends no browser CORS permission because workspace credentials belong in trusted server-side code.