Documents

List a project's document metadata

Lists document **metadata** (never the binary) for one project, paginated. `projectId` is required; `kind` narrows to one library, omitted returns both (OHS first, then Project Information). `folderId` narrows to one folder, or to the documents loose at the library root. Omit it to list the whole library — folders are additive, so a caller that predates them is unaffected.

GET
/documents

Lists document metadata (never the binary) for one project, paginated. projectId is required; kind narrows to one library, omitted returns both (OHS first, then Project Information).

folderId narrows to one folder, or to the documents loose at the library root. Omit it to list the whole library — folders are additive, so a caller that predates them is unaffected.

Authorization

x-api-key<token>

The per-tenant API key, copied from Settings → API & integrations. Sent as the x-api-key request header. The key is tenant-scoped and acts with Admin-equivalent, tenant-wide access.

In: header

Query Parameters

limit?integer

Page size, 1–200. Defaults to 50.

cursor?string

Opaque cursor from a previous page's nextCursor. Omit for the first page.

projectId*string

The project whose documents to list.

kind?string

Narrow to one library.

folderId?string

Narrow to one folder (a folder id from GET /projects/{id}/folders), or the literal none for only the documents loose at the library root. Omitted returns the whole library.

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/documents?projectId=497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",      "title": "string",      "storagePath": "string",      "uploadedAt": "2019-08-24T14:15:22Z",      "uploadedByName": "string",      "audience": "all_crew",      "kind": "ohs",      "folderId": "5b6379a4-2a6c-4085-b184-45838a3b8e7e"    }  ],  "nextCursor": "string"}
{  "error": {    "code": "unauthorized",    "message": "Missing or invalid API key."  }}
{  "error": {    "code": "validation",    "message": "One or more inputs are invalid.",    "fields": {      "fieldName": "A message explaining what's wrong with this field."    }  }}

List a document library's folders GET

Lists the folders of **one** of a project's two document libraries, A→Z. A folder belongs to a project *and* a library, so `kind` is required — there is no folder that spans both. `documentCount` reflects only the documents the caller may see: the Project-Information audience rule is applied, and folders that are empty *for the caller* are omitted for anyone who cannot manage the project, so a reader never opens a folder to find nothing. Folders are one level deep and **organisational only** — a folder never affects who can see a document. Use a returned `id` as `folderId` when listing documents or registering a new one.

Register an uploaded document POST

**Step 2 of the two-step presigned document upload.** Call this *after* you have PUT the file bytes to the `uploadUrl` from `POST /projects/{id}/documents/upload-url`. Pass the `uploadRef` from step 1 (or the `storagePath` + `kind`) plus the `title` (and `audience` for `kind: info`). Verifies the object actually landed in storage (and re-checks its real size/type against the ≤25 MB, PDF/JPG/PNG cap), then creates the document record. The new document then appears in `GET /documents?projectId={id}`. Reading document metadata stays on the read-only `/documents` collection; this project-scoped route is the upload (write) side. Admin or the project's Site Manager; blocked on read-only/archived projects.