Document

Upload a document

POST /{instanceName}/api/v1/{locale}/document

Multipart create: writes the uploaded blob and relates it to the resolved owning entity (entityType/entityId). 201 with a Location header. There is no content-free create.

onConflict is applied when a folderId is supplied and that folder already holds a document of the same name: skip leaves the existing document untouched and returns it, creating nothing; replace (the default) overwrites the existing document's content in place, preserving its id and its placements; keepAll creates a second document under a name de-duplicated against the names already in that folder. With no folderId, or no same-name document, all three behave alike. Concurrent creates of the same name in one folder are not serialised — a rare duplicate is possible.

created (ISO-8601) and createdBy (a masked person id) set the creation attribution of a restored document; omitting either defaults it to now / the calling credential's person. Both apply ONLY when a document is actually created: the skip and replace conflict branches create no document and ignore both values. A backdated created also backdates the document's position on GET /document/timeline, so it can land behind a watermark a consumer has already passed and never be seen there. The supplied created is likewise carried as the change timestamp of the recorded creation event on GET /document/changes, so that event is backdated too; only the feed's ordering is unaffected, because that ordering is the insertion sequence and never the timestamp, which is why the feed's cursor is on insertion order and its reported changed timestamp is never a resumption watermark.

Request body

multipart/form-data → DocumentCreateForm

Multipart form: the file part is the uploaded blob; the remaining parts are the non-file create fields.

Responses

Example

curl -X POST "https://api.visena.example/acme/api/v1/en/document" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@contract.pdf" \
  -F "entityType=Company" \
  -F "entityId=bQ4wR8"

Get a document

GET /{instanceName}/api/v1/{locale}/document/{documentId}

Returns the full entity. 404 if unknown; 400 if the id cannot be unmasked.

Parameters

Responses

Example

curl "https://api.visena.example/acme/api/v1/en/document/dN3pT7" \
  -H "Authorization: Bearer $TOKEN"

Download a document's content

GET /{instanceName}/api/v1/{locale}/document/{documentId}/content

Streams the stored blob as an attachment. Content-Type is the document's stored MIME type, falling back to application/octet-stream when it was never recorded or is unparseable; the file name is carried in Content-Disposition (RFC 5987-encoded), not in the path. Same authorization boundary as getDocument — a caller who cannot read the metadata cannot read the bytes.

Parameters

Responses

Example

curl "https://api.visena.example/acme/api/v1/en/document/dN3pT7/content" \
  -H "Authorization: Bearer $TOKEN"

List documents (offset-paginated)

GET /{instanceName}/api/v1/{locale}/document

Offset/limit paging with a real total. entityType+entityId are REQUIRED (documents are always listed scoped to one owning entity — no org-wide enumeration); optional query (full-text search); and a name/created/modified/modifiedOrCreated sort. RFC 8288 navigation links are in the body.

Parameters

Responses

Example

curl "https://api.visena.example/acme/api/v1/en/document?entityType=Company&entityId=bQ4wR8" \
  -H "Authorization: Bearer $TOKEN"

List documents (cursor-paginated, insert-stable)

GET /{instanceName}/api/v1/{locale}/document/cursor

Keyset paging over the monotonic entity id (insertion order). Pass the opaque cursor from a previous page's nextCursor/prevCursor; omit it for the first page. No total — keyset skips the count. entityType+entityId are REQUIRED (documents are always listed scoped to one owning entity); optional query.

Parameters

Responses

Example

curl "https://api.visena.example/acme/api/v1/en/document/cursor?entityType=Company&entityId=bQ4wR8&limit=100" \
  -H "Authorization: Bearer $TOKEN"

List documents (time-windowed, cursor-paginated)

GET /{instanceName}/api/v1/{locale}/document/timeline

Keyset paging from an optional since lower bound on the single timeline key coalesce(modified, created) — Document has no client-selectable key, unlike Company/Project. entityType+entityId are REQUIRED (documents are always listed scoped to one owning entity). RFC 9557 Z timestamps. A cursor minted by the plain cursor endpoint is rejected with 400.

Sync contract: this feed is upsert-only and at-least-once, ordered on coalesce(modified, created), so creation, archival and renaming are the only writes it reports — renaming is the sole partner-reachable write the platform stamps modified on. Folder moves, content replacement, description-only PATCHes and folder renames/reparents are unreported: they leave the row in place. Deletions never appear here at all and are observable only via GET /document/changes.

Consumer contract: since is inclusive, and cursor timestamps are millisecond-truncated relative to the stored precision, so a boundary row is re-served rather than skipped — overlap the window and de-duplicate by document id. A cross-owner relocation is never a move: it shows only its gaining side here (as a creation in the gaining owner's timeline), while the losing side is visible only as a deletion on GET /document/changes. Full synchronisation therefore needs three sources — this timeline for upserts, GET /document/changes for deletions, and a periodic per-owner snapshot diff for placement, content and description changes. That snapshot diff is the consumer's obligation, not a feature of this API.

Parameters

Responses

Example

curl "https://api.visena.example/acme/api/v1/en/document/timeline?entityType=Company&entityId=bQ4wR8&since=2026-08-20T02:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

Replace a document's metadata

PUT /{instanceName}/api/v1/{locale}/document/{documentId}

Full replace (PUT) of name/description: an omitted description clears the stored value.

Parameters

Request body

application/json → DocumentUpdateDto

Responses

Example

curl -X PUT "https://api.visena.example/acme/api/v1/en/document/dN3pT7" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "contract-signed.pdf",
    "description": "Signed version"
  }'

Partially update a document (RFC 7396 JSON Merge Patch)

PATCH /{instanceName}/api/v1/{locale}/document/{documentId}

Absent fields are unchanged, JSON null clears (name cannot be cleared), a value sets. An empty body {} is a no-op. Wrong content type → 415.

Parameters

Request body

application/merge-patch+json → object

Responses

Example

curl -X PATCH "https://api.visena.example/acme/api/v1/en/document/dN3pT7" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "description": "Signed version"
  }'

Replace a document's content

PUT /{instanceName}/api/v1/{locale}/document/{documentId}/content

Multipart PUT: rewrites the stored blob in place, preserving the document id and its relations.

Parameters

Request body

multipart/form-data → DocumentContentReplaceForm

Multipart form: the file part is the replacement blob.

Responses

Example

curl -X PUT "https://api.visena.example/acme/api/v1/en/document/dN3pT7/content" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@contract-v2.pdf"

Move a document to another folder

PUT /{instanceName}/api/v1/{locale}/document/{documentId}/folder

Changes this document's folder placement within its owning entity. A null folderId places it at top level. The destination must belong to the same owning entity — moving a document to another entity is not a move; archive a copy or a shortcut instead. Both the document and the destination folder are resolved only within the declared entity, so either one belonging to another entity is reported as 404 rather than confirming that the id exists elsewhere. A destination that already holds a placement of the same document is rejected with 409. Moving does not count as a modification: modified/modifiedBy are left exactly as the platform recorded them.

Parameters

Request body

application/json → DocumentPlacementDto

Responses

Example

curl -X PUT "https://api.visena.example/acme/api/v1/en/document/dN3pT7/folder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "folderId": "fR5sK1"
  }'

Delete a document (relation-aware)

DELETE /{instanceName}/api/v1/{locale}/document/{documentId}

Hard delete: no soft-delete/isActive column. When entityType+entityId are supplied, only that relation is removed; otherwise every relation is removed. The document itself is deleted once it is left orphaned (no remaining relations). 204 on success.

A delete that would cascade — no entityType/entityId, on a document holding shortcut placements on other entities — is refused with 409 until acknowledged, and deletes NOTHING when refused. The 409 states how many master documents and shortcut placements would go; re-send with acknowledgeCascade=true to proceed. The targeted (entityType+entityId) form removes exactly one placement, cannot cascade, and is never gated.

Parameters

Responses

Example

curl -X DELETE "https://api.visena.example/acme/api/v1/en/document/dN3pT7" \
  -H "Authorization: Bearer $TOKEN"