Skip to main content
Use the completed-run cursor API to copy workflow outputs into an external system without missing slow runs or downloading history from before activation.

​
Prerequisites

Create a dedicated API token with the minimum abilities:
  • workspaces-read
  • workflows-read
  • workflow-runs-output-read
  • documents-read only when at least one followed workflow exposes a persisted documentRef
In the API token modal, the Raydocs Windows sync client preset includes documents-read so it supports both output types and scopes the token to the current workspace by default. The token owner must be an administrator of every workflow workspace the integration follows. Do not grant workflow-agent and do not send workflow-agent headers. The public output must expose the documents array described in Get Workflow Run Output. Each item may be a persisted documentRef or a temporary workflow-run fileRef with its SHA-256. Use a fileRef when external delivery happens promptly (for example, the standard CDJ Connect ZIP); use files.persistWorkspace only when a durable workspace document is also needed.

​
Select workflows in Raydocs

Open a workflow’s edit dialog and enable Distribute files through Raydocs Sync. The workspace administrator controls this setting. New and duplicated workflows start with synchronization disabled. The existing workflow update endpoint accepts sync_enabled: true or sync_enabled: false. Raydocs stores only sync_enabled_at: an ISO 8601 UTC timestamp when enabled, or null when disabled. Repeating an enable request preserves the timestamp. Disabling and re-enabling starts a new collection period. Clients cannot supply an activation timestamp. Both GET /workspaces/{workspaceId}/workflows and the workflow detail response include sync_enabled_at. Sync discovers the workspaces accessible to its token and reads each complete workflow list at the start of its existing five-minute cycle. The Windows Refresh button and RaydocsSync workflow refresh use the same reconciliation, without downloading files or adding another timer. If a synchronization is running, refresh reports that it is busy. There is no local workflow selection. Every installation authorized for a workspace follows that workspace’s enabled workflows. The API token and local or SMB destination remain configured on the Windows server.

​
Reconcile a workflow feed

For a newly enabled workflow, use the remote activation timestamp, not the time the client first discovers it. Preserve the original timestamp as the local activation identity and keep its cursor while that identity is unchanged. Run creation timestamps have second precision. Sync uses sync_enabled_at - 1 second as the cursor API’s fixed created_after boundary, which the API normalizes to seconds. This includes the activation second and can include runs created just before activation in that same second. Do not move this boundary forward on later polls. On a new activation timestamp, clear the discovery cursor and start a new period. Keep download history and deduplication keys. Pending downloads from a previous period do not automatically resume. A null activation or a workflow missing from a successfully read complete catalog suspends discovery and queued downloads. A started download can finish; the selection takes effect when the client next refreshes it. An inaccessible or invalid workspace catalog defers that workspace’s processing until the next successful refresh while preserving its cursor and history. A failed workspace list aborts the cycle. A missing sync_enabled_at field is an incompatible API, not an explicit disabled setting.

​
Process one discovery page

For each returned run:
  1. Request the run’s public output.
  2. Validate that documents is an array and every entry has a supported type, filename, non-negative size, and a 64-character hexadecimal sha256.
  3. For a documentRef, validate documentId and matching workspaceId; for a fileRef, validate id.
  4. Build the idempotency key workflow_id:run_id:type:source_id.
  5. Store one download event per output file.
  6. Commit the events and meta.next_cursor together.
  7. Request the next page when meta.has_more=true.
Raydocs Sync quarantines a malformed run and commits that quarantine with the page cursor, allowing later runs to proceed. A document download failure does not invalidate discovery; keep the event and retry the download independently. Follow pages while meta.has_more=true. After the last page, keep polling with its returned cursor; runs that complete later appear after the stored (completed_at, id) checkpoint.

​
Download an output file

Request a fresh signed URL with the document’s documentId, then stream the response to a temporary local file.
For a temporary fileRef, request the workflow-run file URL instead:
Before exposing the final file, verify size and sha256, flush the file to disk, and rename it atomically on the same volume. Request a new signed URL after expiration; never store a signed URL as durable state.

​
Reliability rules

  • Keep the activation identity and discovery boundary immutable within a collection period.
  • Treat the cursor as opaque.
  • Store the page cursor only after its events are durable.
  • Use the workflow_id:run_id:type:source_id idempotency key to absorb client or network retries safely.
  • Record malformed runs in quarantine atomically with the page cursor; never silently discard them.
  • Request the correct route for the output type: document URL for a documentRef; run-file URL for a fileRef.
  • A run fileRef is temporary. Download it promptly and do not use it as a durable workspace document identifier.