Object collaboration API

Use the Object collaboration API when an integration must keep discussion and documents in the governed context of a Moltaro resource. The public Runtime API supports bounded history, direct anchors, flat quotes, deferred file upload, and one idempotent publication operation.

See File API workflows to distinguish catalogue, File fields and attachments, and to handle authorized file results, restricted mutation receipts and download responses with a generated client.

Use the workspace API base URL

Resolve every /api/workspace/... route against the target installation’s API base URL. moltaro.com hosts public documentation and is not a customer workspace API origin. Use Authorization: Bearer <token> and prefer the installation-local OpenAPI document for the installed release.

Read a bounded timeline

Post an ActivityFeedRequest to POST /api/workspace/activity-feed with the resource identity, permitted scope, desired content kinds, and a ContentHistoryRequest.

History requests use opaque cursors and accept a page size from 1 through 100; the default is 50. Use Before or After to move through history. To open a direct link, provide AnchorId and AnchorKind and let the server return a limited window around that item. Search filters the permitted context but does not change the context-wide counts.

Treat cursors as navigation tokens, never as authorization. Moltaro authorizes the resource, sources, messages, files, and quote targets before applying the result limit. A client must handle a previously visible quote or file link becoming unavailable.

Publish text and files together

The publication flow is:

1. For a small direct upload, use POST /api/workspace/collaboration/files/prepare. For a resumable managed upload, create the FileSystem session with PublicationMode set to DeferredUntilSend, transfer its parts, and complete verification. A prepared file remains hidden from normal collaboration reads.
2. For direct Entity uploads, batch up to 20 prepared identifiers through POST /api/workspace/collaboration/files/preparations/status. For Board item uploads, use POST /api/workspace/boards/{boardIdOrKey}/items/{boardItemId}/collaboration/files/preparations/status. Poll small-file preparations using the response’s recommended interval until every item is Ready, Rejected, or Expired, while retaining its prepared FileReference identifier. For managed deferred sessions, poll GET /api/workspace/files/uploads/{uploadSessionId} until Status=12 (ReadyForPublication); retain that session identifier for Send.
3. Generate one stable OperationKey for the user’s Send action.
4. Post one CollaborationSendRequest to POST /api/workspace/collaboration/send with the owner resource, optional text, optional quote, mentions, relations, and all prepared, deferred, or existing file identifiers. Pass ready managed sessions in DeferredUploadSessionIds.
5. Persist the returned comment and file identifiers. If Replayed is true, the server returned the result of the already completed operation.

Reuse the exact OperationKey and the exact payload only when retrying the same Send after an uncertain response. Generate a new key when the user changes the draft or starts another Send. Publication commits the message, placements, file relationships, mention notifications, and collaboration events together. A file-only publication does not create an empty comment.

Cancel an abandoned small prepared FileReference with POST /api/workspace/collaboration/files/cancel. A managed resumable upload is still an upload session, so abort it with POST /api/workspace/files/uploads/{uploadSessionId}/abort and the session’s current RowVersion. Prepared uploads expire and are cleaned up; they are never published by the worker without an explicit Send. Do not treat a successful upload transfer as proof that collaboration publication completed.

Each preparation status contains the FileReference identifier, State, ExpiresAtUtc, RetryAfterMilliseconds, and an optional localizable failure code. Preparing cannot be sent. Rejected and Expired are terminal and must be removed or replaced before Send. Status lookup verifies the actor, owner context, unpublished state, and deletion state; an identifier prepared by another actor or for another owner is reported as not found.

Quotes and file relationships

Set at most one QuotedCommentId. The result is a normal, flat message with a server-captured quote snapshot; it does not create a nested reply tree. Access revocation or deletion hides the quote from later reads.

One comment can reference several FileReferences. ExistingFileReferenceIds creates relationships to already managed files without copying or republishing the file. The Files projection can return the permitted linked comments so a client can navigate in both directions.

Boards

Boards expose equivalent bounded history and composite Send operations under the board-item runtime route. Preserve the selected board-item or target-record source and its origin data. Board policy and target-resource policy are evaluated independently; do not infer one permission from the other.

Contract source

Use the generated Runtime API reference for exact PascalCase request and response schemas. For retry and recovery rules, also read Reliable API automation. The public API describes integration contracts; internal package-authoring mechanisms are not part of this workflow.