Skip to main content
Retrieve the final public output for one workflow run. The endpoint can return any JSON value defined by the workflow. The synchronization contract below requires an object containing a documents array.

​
Authentication and scope

Requires workflow-runs-output-read. The token owner must be an administrator of the workflow workspace. A discovery-based synchronization token also needs workspaces-read and workflows-read for discovery. Add documents-read when the workflow exposes persisted documentRef outputs. For an ERP integration with a known workflow and run ID, use only workflows-execute (webhook configured with raydocs_api_token) and workflow-runs-output-read (status, output and output file URLs). No file permission or workflows-read is needed. This token cannot list runs or read their internal details, inputs, steps, diagnostics or artifacts. Access is workspace-based: the token owner must be a workspace administrator, and any workspace restriction on the token must match. Output access is not limited to runs created by the same token or to one workflow. A known run ID from another workflow in that authorized workspace remains readable through its matching workflow route. For completed runs, accessible temporary file references in the result automatically receive download_url and download_url_expires_at. No query parameter or new token permission is required. The JSON keeps its original shape; only referenced files are enriched, not other input or intermediate files.
Authorization matches the file endpoint: workflow-runs-output-read permits both complete public fileRef values and compact ERP objects containing file_id. Only IDs explicitly exposed in the final output of a completed run can be resolved, and the run must own the file or hold a validated access alias. Compact objects receive only the two URL fields; resolution never adds storageKey or internal metadata to the business JSON. References that cannot be resolved or authorized, including malformed file metadata, remain unchanged without blocking valid neighboring files. If an object already defines either download_url or download_url_expires_at (even as null), its existing fields are preserved and no generated URL fields are added to that object. Persisted documentRef values use the document API and its permissions instead. Links expire ten minutes after the response is generated. Download them without an API token and follow redirects; the storage redirect keeps the same expiry. Read /output again, or call /file for one file, to renew links without running the workflow again. Links are generated for the HTTP response only and are not saved in workflow results. Responses use Cache-Control: private, no-store. Signing does not check storage availability. A deleted file still returns 404 when downloaded; renewing its URL does not restore it or extend file retention. Already issued links remain usable until expiry even if the issuing API token is revoked. Keep stable file IDs for retries, not signed URLs.

​
Synchronizable output

Expose a final documents array. Each entry can be a persisted documentRef or a temporary workflow fileRef augmented with a SHA-256 checksum.
Use documentId with the workspace document URL endpoint. Do not use the workflow run file endpoint for these persisted documents; that route serves temporary runtime fileRef values. For a temporary fileRef, expose its normal file-ref fields plus sha256:
Use id with GET /workspaces/{workspaceId}/workflows/{workflowId}/runs/{runId}/file?file_id={id}. A fileRef is temporary, so it is suitable only for prompt synchronization. The consumer must verify size and sha256 before publishing the file.

​
Download output files with an API token

The workflow-runs-output-read permission also allows downloading temporary files referenced in the final output of a completed run. You do not need workflows-read or documents-read for these files, and you do not need to persist them as workspace documents. References can appear anywhere in the output, including nested objects and arrays; a documents envelope is only required by the synchronization contract above. Call the workflow run file endpoint with a compact object’s file_id or a complete fileRef’s id. It returns a signed URL valid for ten minutes. Fetch that URL to download the file, following redirects. If the link expires, request a new one while the file remains available; do not start another workflow run. Output-only access returns 404 when the run is not completed or the file is absent from its final output. Input and intermediate files remain inaccessible unless the workflow explicitly includes them in its final output. Tokens with workflows-read retain their existing access to runtime files. Workspace scope and file ownership checks apply to both paths. The canonical envelope uses a documents array. Raydocs Sync also normalizes a single reference or an object of named references under documents. Missing documents, unsupported reference types, or missing identifiers, filenames, sizes or checksums are malformed outputs. Sync records them in quarantine atomically with the page cursor so later runs can continue.