HEXAGON_API_URL to the control-plane origin without /v1, and provide the indicated resource IDs and trusted backend token. Preview routes are registered only when the preview service is configured.
List exported artifacts
GET /v1/runs/{run_id}/artifacts returns 200 with { "artifacts": [...] }. The path ID must be a UUID. Results are ordered by name; this endpoint has no pagination parameters. Each item contains:
404 run_not_found. Listing is not restricted to successful Runs: inspect Run state separately, and do not treat an empty array during execution as the final result. There is no public artifact-upload operation in this route family; the worker captures the Harness manifest.
Download one artifact
GET /v1/artifacts/{artifact_id}/content returns 200 and raw bytes, not JSON or Base64. The path ID must be a UUID. A missing/foreign artifact, or a historical row without retained content, returns 404 artifact_not_found.
--fail-with-body can still write the error body into that destination: require curl exit status 0 before using it. Compare file byte count and SHA-256 against the list metadata and response header. Do not execute downloaded model-generated code merely to inspect it. Neither the route nor its schema advertises a Range/conditional-download contract; do not assume resumable partial downloads.
Capture limits are 64 files per manifest, 4 MiB decoded bytes per file and 8 MiB total. Names are relative, at most 512 characters, and reject path traversal, backslashes and control characters. Canonical Base64 and digest integrity are checked during capture. Repeated capture of the same Run/name with identical content is tolerated; a different hash yields artifact_conflict. These are worker-capture constraints, not fields to POST to the public download route. See limits.
Closure preserves exported bytes and Run records independently of the Sandbox. A file that exists only in the workspace is not automatically an artifact. Verify downloads after closure for your journey; retention is not a substitute for your deployment’s backup policy.
Interpret download results
The configured control plane’s response hook emits
Cache-Control: no-store for these management responses. Do not infer the wire value solely from the download handler’s local header assignment. Current HTTP checks also observe a full 200 response for If-None-Match; there is no supported ETag-based conditional-download workflow here. Redownload into a fresh destination and validate the complete bytes.
The artifact HTTP review records 19 passing checks using real loopback HTTP and PostgreSQL in an isolated migrated schema: binary bytes and headers, empty and legacy content, owner/application access, tenant isolation, invalid IDs, Range/conditional behavior and retained downloads after a controlled Session state change. The schema was removed. These checks do not exercise worker capture, cloud deletion or the preview browser surface. Separate artifact retention examples cover the documented cloud journey.
Create a private preview grant
POST /v1/sessions/{session_id}/previews accepts a strict JSON object and returns 201. The Session ID must be a UUID.
id (grant UUID), session_id, integer port, ISO timestamp expires_at and url. The URL contains a secret ticket. Store it privately and deliver it only to an authorized user; do not paste it into shared logs. The default local shape is http://<grant-id>.localhost:8788/?ticket=<ticket>; hosted deployments use their configured scheme/domain/port.
Creation requires an open Session, a recorded Sandbox ID and no detected control-plane expiry. Missing/foreign Session returns 404 session_not_found; otherwise an unavailable Session returns 409 preview_session_unavailable. Invalid port/TTL or unknown body fields return 400 invalid_request.
Grant creation does not start a server, wake a sleeping Session, probe HTTP health or establish that the Provider can deliver preview traffic. Start the server within the cloud workspace and verify its port first. Provisioning and private transport can still fail when opening the URL. There is no idempotency key or public preview-list/read endpoint in this management family. If the creation response is lost, do not assume that no grant exists; avoid retry loops, inspect available private records and allow the requested grant lifetime to expire if its ID cannot be recovered.
Handle grant creation and response loss
Save the returned grant ID and expiry with the authorized application user and Session. Keep the ticket-bearing URL in private storage; the control plane persists its digest, so a database row is not a way to recover the original ticket. Treat the returned URL as a bearer credential.
A successful creation does not promise access for the entire TTL: Session availability, allocation expiry and explicit revocation are checked independently. Likewise, a successful revocation prevents subsequent authorized use; it cannot remove content already received by a browser.
The preview management HTTP review records 29 checks using real loopback HTTP and PostgreSQL fixtures. It covers default/boundary TTLs, input validation, owner/application access, tenant isolation, unavailable Session states, controlled allocation expiry, repeated creation with the same key, and repeated empty-body revocation. It also verifies that management calls do not invoke the Provider target or close the Session. Browser ticket exchange, cookie behavior and live preview traffic require separate verification; this record does not establish them.
Browser access is a separate HTTP surface
Openurl in the authorized browser; do not send a management owner token to the preview origin. The initial GET ticket is checked and exchanged for a host-only hexagon_preview HttpOnly, SameSite=Lax cookie; HTTPS adds Secure. The response redirects to the same path/query with the ticket removed. Cookie lifetime is bounded by grant expiry. Ticket-bearing non-GET requests are rejected.
Subsequent requests validate grant ID, token digest, expiry/revocation and Session availability. Closing or pausing the Session can invalidate current access. A same-origin check rejects a supplied foreign Origin header. The proxy uses the trusted Provider target; user paths do not choose a new upstream host. Provider credentials and upstream cookies are not forwarded to the browser.
Current transport forwards ordinary HTTP methods/bodies, subject to an 8 MiB request body limit and a 30-second upstream fetch timeout. It forwards only selected request/response headers. Same-upstream redirects are rewritten into preview-relative locations; external redirects are blocked. CSP restricts external resources and framing. WebSocket upgrades and upstream application-cookie flows are not supported. Upstream HTTP error statuses can be relayed, so not every 4xx/5xx is a Hexagon authorization failure.
The preview server has its own error handler; do not assume all its errors use the management server’s validation envelope/status policy. Observe the actual response code and context.
Revoke access
DELETE /v1/previews/{preview_id} returns 204 with no response body. Do not parse JSON on success.
404 preview_not_found. Repeating revocation of an existing grant also succeeds; the row is marked revoked rather than removed. Revocation does not stop the application’s server or close the Session. Refresh the browser to verify that new requests are denied; already delivered content cannot be recalled.
Sources: artifact storage and integrity, grant lifecycle, preview proxy, HTTP routes. Next: artifact workflow, preview troubleshooting, HTTP overview. This reference is source-reviewed; these requests have not been executed as a fresh cloud/browser acceptance run.