Application records

​

How it works

1. A Nexio-hosted application’s server holds the organization’s live key. It sends the signed-in person as X-Nexio-Acting-Principal on every call. A call without it answers 401 unauthorized.
2. The application is one of a fixed list of six Nexio-hosted applications, set in code; no organization adds one. An unknown application answers 404 not_found.
3. Inside an application, records live in named collections. A collection needs no setup: its name must match ^[a-z0-9][a-z0-9_-]{0,62}$.
4. Every write is owned by the acting principal. A read returns the caller’s own record, or a shared record with the same id. A person never reads another person’s owned records.
5. Files are not stored inside records. They go through a separate blob flow with short-lived upload and download grants.

​

Records

• id: the caller’s identifier, 1 to 200 bytes, no / and no control characters.
• subjectKeys: up to 16 promoted string fields the application filters on, for example {"account": "acct-4471"}. Key pattern ^[a-z][a-z0-9_]{0,63}$, each value 1 to 500 bytes.
• payload: any JSON value except null, up to 256 KiB. A payload that embeds file bytes (a data: URL, or a key such as base64 or contentBase64) is refused. Files use blobs.
• version: a counter the server owns. Create with version: 0. Each change, including a delete, increments it.
• ownerPrincipal: the owner, or null for a shared record. Shared records are created only by Nexio’s import path.

{
  "id": "review-checklist-acct-4471",
  "ownerPrincipal": "user_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
  "subjectKeys": { "account": "acct-4471" },
  "payload": { "items": [{ "label": "Request security questionnaire", "done": true }] },
  "version": 3,
  "createdAt": "2026-09-20T15:04:05Z",
  "updatedAt": "2026-09-23T09:12:44Z",
  "deletedAt": null
}

• Optimistic concurrency. A write names the version it expects. A stale version answers 409 version_conflict. Retrying the same write with the same content returns the stored record without incrementing, so a retry after a timeout is safe.
• Batch writes. One request writes 1 to 100 records in a single transaction. All succeed or none do.
• Soft delete. A delete names the expected version and marks the record deleted. recreate: true with version: 0 revives a deleted id.
• Paging. Lists sort newest first by updatedAt. The cursor is signed, carries a read pin, and expires after one hour. Filters are subject.<key>=<value> (at most 100 values in total), updated_since (RFC 3339) and limit.

​

Files (blobs)

1. Reserve. The application sends id, name, contentType and sizeBytes. The store answers 201 with an upload URL valid for 15 minutes.
2. Upload. The application uploads the bytes directly to that URL, without the Nexio key.
3. Finalize. The store checks the uploaded object. A size mismatch answers 409 upload_mismatch. A file over 10 MiB answers 413 object_too_large. A type that does not match its declared media type answers 415 unsupported_media. On success the blob is ready.
4. Read. Metadata is served for ready blobs only. The content route returns a download URL valid for 5 minutes. PNG and JPEG open inline; every other type downloads as an attachment.
5. Delete. Soft-deletes the metadata.

​

Limits

​

Errors

​

Next