Conventions
The same rules apply to /v1 of every product. Whether an operation supports a rule, you see in the reference with that operation.
The envelope
Section titled “The envelope”Every JSON response has six fields:
| Field | Meaning |
|---|---|
data | The result |
context | The context of the call: organisation, filters, and on an error error |
completeness | How complete it is: total, returned, truncated |
notIncluded | What this result does not tell, and which call does |
provenance | Where it comes from |
next | Logical follow-up steps |
Exceptions are in the reference. In the LEO family /models and /chat/completions keep the OpenAI shape, and /openapi.json returns the document itself. ORDO returns the envelope when you send Accept: application/vnd.prudai.task+json; files keep their own format.
Pagination
Section titled “Pagination”completeness.total is the exact total, or null when unknown; never an estimate. The parameters are in the reference per operation: limit with after and next_cursor in the LEO family, limit with offset in IRMA and ORDO.
Idempotency
Section titled “Idempotency”A write that supports Idempotency-Key does not run the same key with the same body twice. The same key with a different body gives 422 idempotency_key_reused.
Dry run
Section titled “Dry run”With ?dryRun=true you see what a write would do. Nothing is stored and the approval is not touched. Not every operation has a dry run: that is in the reference.
Concurrent changes
Section titled “Concurrent changes”A change that supports If-Match is sent with the ETag you read. If the object changed in the meantime you get 412. If the header is missing you get 428.
Soft delete
Section titled “Soft delete”DELETE deletes softly: the object can be restored through restore. Permanent deletion is only possible in the app. In the LEO family a conversation stays restorable for 30 days.
Versioning
Section titled “Versioning”/v1 only changes by adding. Responses can gain new fields; ignore what you do not know. In the LEO family requests are strict: an unknown field gives 400.
Headers
Section titled “Headers”X-Request-Idis on every response in the LEO family. Quote it to support.RateLimit-Limit,RateLimit-RemainingandRateLimit-Resetgive the tightest limit that applies.- Times are RFC 3339 in UTC.