Requests, responses, pagination, and retries

JSON and multipart

Use Content-Type: application/json for JSON bodies. For uploads, use multipart and let the HTTP client generate the boundary. With curl, -F 'file=@document.pdf' is appropriate; do not combine it with a manually set JSON content type. Skill bundles use files (plural), while KB uploads use file (singular).

Encode path segments and query values; never concatenate raw user input into a URL. Repeated array query parameters are sent as repeated keys where the endpoint says so. UUID fields must contain actual UUIDs; a project ID or provider slug is not interchangeable with a run, resource, or connection ID.

Read the envelope for the endpoint you called

Most v2 single-resource responses put the object in data. Cursor responses put items in data with next_cursor and potentially other cursor fields. Offset responses include their own pagination metadata. Empty success metadata can be omitted. A 204 has no response body: do not call .json() on it.

Legacy inference, v1 knowledge bases, and legacy analytics do not all share the v2 envelope. Do not add a universal response.data accessor to a client covering every version. Use the exact response schema under each endpoint. v1 KB listing returns an array; v2 KB listing returns an envelope.

Pagination is not one global convention

Family	Pagination	Typical default/maximum
v2 runs	cursor, page_size	50 / 1000
KB collections	cursor, page_size, direction	50 / 1000
KB resources	cursor, page_size, direction	50 / 100
Providers, connections, skills, most eval lists, subscriptions	offset, limit	0 and 50 / 100
Eval run scores and sampled runs	Cursor pagination	Read the endpoint's limits
Legacy analytics	Zero-based page, page_size	0 and 25
SCIM	One-based startIndex, count	Protocol-specific

Treat cursors as opaque. Keep filters fixed during traversal, URL-encode the cursor, and stop when no next cursor is returned. For offset lists, advance by the items returned and use response totals/has-more information where available. Concurrent changes can affect offset traversals; deduplicate by stable ID if you need a complete export. v1 KB list accepts pagination parameters but returns a bare list without a next-cursor envelope; prefer v2 for new paginated clients rather than inventing a cursor.

Retry reads; reconcile writes

Use connection/read timeouts, a total deadline, exponential backoff with jitter, and bounded attempts. Retry transient read failures and 429/503 responses when appropriate, honoring Retry-After when present. Stop and fix credentials or permissions for 401/403; fix payloads for 400/422.

Do not automatically retry a run start, action invocation, upload, score creation, or other write after an ambiguous timeout or 500. The operation may already have taken effect, incurred usage, or changed an external system. No general idempotency-key contract is defined here. Persist returned resource IDs, inspect status, and reconcile before deciding to send another write.

For asynchronous operations, preserve Location and any status_url. Resolve relative URLs against the API origin. Only attach credentials to your trusted API origin; a signed file-download URL is a different request and does not need your StackAI authorization header.