Collaboration API contracts

Since 2026.10.1 these contracts are served by the gateway from the managed store. The native gRPC methods that carried them are retired and answer UNIMPLEMENTED naming the route; the replaced read/ and native/ routes keep answering until the gateway-alias sunset (31 March 2027) with a Link to their successor. Requests and responses keep the protobuf JSON shapes of proto/arraybridge.proto; a revision may be given as its number or as its exact revision digest. All routes require the caller’s identity and project authorization.

Route (/api/v1/projects/{project}/…)	Replaces	Contract
catalog/history	ListAssetRevisions	Read-authorized descending history, up to 100 entries; use the returned before-revision cursor for older pages. Bulk scientific values are fetched separately.
imports/original-chunk	PutOriginalChunk	Member-authorized project/publisher upload keyed by SHA256 and total length. A zero-length chunk queries progress. Maximum 16 MiB, 256 KiB chunks; exact retries resume. Completion verifies SHA256.
catalog/original	GetOriginalChunk	Read by an exact published asset revision and offset, with current access checks. Staged unattached bytes are not exposed.
imports/source, imports/snapshot	RegisterExternalSource, PublishExternalSnapshot	Register the retained external source, then publish a snapshot with its source version, expected revision and command ID; the identical request replays its answer, a stale head is refused.
reviews/scene-save	SaveReviewScene	Member-authorized save of 1–16 distinct exact same-project asset revisions. Uses expected revision and command ID; a stale expected revision fails.
reviews/scene-list / reviews/scene-get	ListReviewScenes / GetReviewScene	Current scene catalogue or exact saved scene revision; read-authorized. Maximum 128 scene identities per project.
reviews/comment-add	AddReviewComment	A project reader, including a viewer, appends a comment to an exact asset revision with an idempotent command ID. Body maximum 4,000 UTF-8 bytes.
reviews/comment-list	ListReviewComments	Latest 100 comments for an exact revision, with has_older; not a full-history export API.

Publication sequence

host GUI: choose a saved file, unit and contribution binding
    |
background capture: validate grid/meaning, hash and snapshot
    |
persist pending command + exact expected head locally
    |
register an explicitly retained external source
    |
[optional LAS original: upload/resume chunks and verify completion]
    |
publish snapshot with stable source identity + next source version
    |
platform commits immutable revision -> notification hint
    |
persist binding receipt; clear pending command

After a lost reply, retry the saved command rather than inventing a new version. A retained original’s original_sha256 must refer to a completed upload by that publisher before the snapshot can become available. The QGIS publisher currently retains the numerical snapshot, not the original GeoTIFF.

An event is a hint to fetch an exact authorized revision; it is not the scientific payload or the source of truth. Reconcile current state on reconnection. A follower may coalesce intermediate hints; a pinned reader keeps its exact revision.

QGIS-derived parent metadata is declared by the user. Do not present it as instrumented execution lineage. Platform-run calculations separately record exact inputs, calculation version, parameters and run provenance. These distinctions must survive exports and connector transformations.

Sharing and inbox

Public HTTP operations under /api/v1/projects/{project}/… (session or delegated automation credentials; see the route inventory in the Platform repository). All refusals use the ordinary error body {error, code}.

Operation	Contract
las-uploads/members	Editing members and administrators: project members by identity with display names; viewers and non-members refused. No capability flags for non-administrators.
las-uploads/upload, las-uploads/inspect	Editing project membership only; administration and compute are not required.
las-uploads/share, applications/share	Replace read and reuse recipients. Send expected_generation (the grants_generation you read from las-uploads/info or applications/result-preview) and a command_id (≤64 characters). A stale generation, or the latest command reused for different recipients, is refused with HTTP 409 recipients-changed; repeating the latest command unchanged returns the current result without another change. expected_generation is required: a request without it is refused with HTTP 428 condition-required and changes nothing (the announced transition release has passed). Responses include sharing_contract: conditional.
las-uploads/policy	Uploader only. Body audience, reason (1–500 characters) and required expected_generation (from info.policy.generation). Narrowing removes the dropped people’s grants on the original and every result built on it, except each result author’s own; widening creates no grant. Response report lists only results the caller can read.
inbox/list	The caller’s own signals newest first (shared-with-you, reuse-granted, access-removed, built-on-your-data) and unread_count. Signals about items the caller can no longer read are omitted; removals carry no item or person. Optional hide_kinds (at most 9 kinds, or null) leaves those kinds out of the items and the count; the stored signals do not change. The Workspace hides source-update-available, which its Updates list owns.
inbox/mark-read	ids (1–200) of the caller’s own signals in this project; any other id refuses the whole request with 404. Takes the same optional hide_kinds.

| stages/get, stages/board | Stage (draft, review, approved, withdrawn), generation, history and endorsements of exact revisions the caller may read; captured revisions and packages are reported read-only with their package state. | | stages/transition | action (request-review, approve, return, withdraw), expected_generation, optional command_id, and purpose (approve) or reason (return, withdraw). Stale generation or reused command with different content: 409 stage-changed. Approving, returning and renaming need project administration. | | stages/names, stages/names-save | The project’s display names for the four stages; saving needs administration and expected_generation. | | publications/version-contributors, publications/version-contributors-save | The members this project lets add versions to each other’s derived results: {generation, members, can_change} with display names, and for administrators eligible (the editing members). Saving needs administration, members (each a current editing member, once, at most 100) and expected_generation; a stale generation is refused with 409 settings-changed. A version is accepted from a member other than the author only when both are named and the member can read the result; both are checked again when the version is written. While nobody is named, refusals are word for word as before; once people are named, “Only the author can” reads “Only the author, or a member the project lets add versions to each other’s results, can”. The author stays the author: can_share and sharing stay theirs, and they receive revision-added. publications/info and applications/result-preview answer can_add_version. |

A withdrawn revision refuses new payload reads, exports and reuse, including for results rooted in it and at publication time; its stage record stays readable. Grant generations are per item and start at 0 for items shared before this contract. Revocation governs new requests only; earlier downloads cannot be recalled.