API Conventions
Definition
The resource prefix is /v1/organizations/{organizationKey}/projects/{projectId}. Benchmark operations continue beneath the selected Benchmark and immutable Version. Paths and IDs are scoped; a readable title is not a join key.
Envelopes and pagination
Case lists return message and data: {columns, rows}; detail returns message and result. Fieldloop and benchmark operations use their documented data payloads. Parse the called operation's envelope.
Case reads use limit/offset pagination, defaulting to 10 rows and accepting a positive limit through 1,000. Other readers have their own pagination. Preserve returned continuation information instead of assuming a cursor shape universally.
Case reads emit ETag and support If-None-Match. Concurrency and mutation preconditions belong to the particular operation.
Writes and retries
Use an Idempotency-Key where the operation requires it. Preserve exact request content and logical identity, but follow that operation's recovery contract. Changed content is a different command.
External results append only to the issued Trial. Completion freezes accepted responses and admits evaluation separately. A failed admission retry does not replace those responses.
IDs and errors
Use database/API-issued opaque IDs. Example placeholders are not usable IDs. Keep the original HTTP status, structured code and actionable reason; no global error envelope is promised across legacy and forwarded families.
HTTP outcomes
| Outcome | Next step |
|---|---|
200 or 201 | Inspect the resource or per-item outcomes |
202 | Retain the issued identity and inspect processing state |
304 | Use the representation associated with the matching ETag |
400 or 422 | Correct the request using its code and reason |
401 or 403 | Correct credentials or scope |
409 or 412 | Inspect immutable state, idempotency or preconditions |
429 | Honor Retry-After when supplied |
502, 503 or 504 | Preserve command identity before recovering an uncertain write |
Not every endpoint emits every status. The OpenAPI lists operation-specific responses; one rate-limit response does not define a universal quota.
Recover without duplicating work
Fieldloop and benchmark submission workflows support their documented exact-content recovery. Preserve original bytes/key and inspect the returned receipt. A client timeout does not undo admitted work.
Case imports and batch Case reference writes use duplicate-key rejection: repeating a key returns 409, not a replay of the original response. Retain the issued import identity when available and read its status. If a response is lost before its identity is known, reconcile through your administrator or support before submitting with a new key; a fresh key can create another operation. Do not assume duplicate rejection proves whether the first handler completed.
See SDK Delivery and Recovery for the Fieldloop client path.