Share links

Share links let you expose selected results without giving the recipient an API key or access to the rest of a workspace. Use them for customer result pages, external review, handoffs between teams, or a short-lived link in a report.

A share link:

• Belongs to one workspace.
• Can include predictions, pipeline runs, or both.
• Is read-only and does not change the underlying resources.
• Requires a future expiration time.
• Stops working when it expires or is archived.
• Uses its ID as a bearer credential, even when access is also restricted by email.

You can include up to 100 prediction IDs and 100 pipeline IDs in one link. Every referenced resource must belong to the resolved workspace and match the caller’s live or test mode.

Choose an access mode

Access mode	Viewer authentication	Recommended use
public	No API key or OAuth token; possession of the link is sufficient	Low-friction sharing where anyone who receives the secret URL may view
email	Boltz OAuth sign-in with a verified email in allowed_emails	Named collaborators or customer users who should authenticate before viewing

If access_parameters is omitted, the link defaults to public.

Email matching is case-insensitive. An email-restricted link accepts between 1 and 100 allowed addresses. A signed-in member who already has read access to the link’s workspace can also open the link.

Create a public link

Create and manage share links with an API key or supported OAuth bearer token that can read every referenced resource. Admin API keys and OAuth callers can select an authorized workspace with workspace_id; a workspace key is confined to its assigned workspace.

curl https://api.boltz.bio/compute/v1/share-links \
  -X POST \
  -H "x-api-key: $BOLTZ_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "workspace_id": "ws_customer_a",
    "prediction_ids": ["pred_123"],
    "pipeline_ids": ["pipe_456"],
    "expires_at": "2030-12-31T23:59:59Z",
    "access_parameters": {
      "access_mode": "public"
    }
  }'

The response includes the link id and, when configured for the deployment, a visitable url:

{
  "id": "shr_qoEFr2BlPTBLuM5BinaC8x7iVPP_AwppEOmlxQjJ-eo",
  "url": "https://lab.boltz.bio/share/shr_qoEFr2BlPTBLuM5BinaC8x7iVPP_AwppEOmlxQjJ-eo",
  "workspace_id": "ws_customer_a",
  "prediction_ids": ["pred_123"],
  "pipeline_ids": ["pipe_456"],
  "expires_at": "2030-12-31T23:59:59.000Z",
  "created_at": "2026-07-28T12:00:00.000Z",
  "archived_at": null,
  "access_parameters": {
    "access_mode": "public"
  }
}

Store the returned ID if you will need to retrieve metadata or revoke the link later. There is no list-share-links endpoint.

Create an email-restricted link

Set access_mode to email and provide the allowlist:

curl https://api.boltz.bio/compute/v1/share-links \
  -X POST \
  -H "x-api-key: $BOLTZ_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "prediction_ids": ["pred_123"],
    "expires_at": "2030-12-31T23:59:59Z",
    "access_parameters": {
      "access_mode": "email",
      "allowed_emails": [
        "reviewer@example.com",
        "customer@example.com"
      ]
    }
  }'

The Boltz Lab share page prompts an unauthenticated visitor to sign in. Direct HTTP clients must send a supported OAuth access token along with the share-link ID:

curl "https://api.boltz.bio/compute/v1/share/$SHARE_LINK_ID" \
  -H "Authorization: Bearer $BOLTZ_ACCESS_TOKEN"

An email-restricted read returns 401 with share_link_authentication_required when the viewer has not signed in, or 403 with share_link_email_not_allowed when the verified email is not allowed.

Read shared data

For a public link, the share-link ID is the only credential:

curl "https://api.boltz.bio/compute/v1/share/$SHARE_LINK_ID"

The response contains the selected prediction objects and pipeline-run objects. Pipeline results are paginated separately:

curl "https://api.boltz.bio/compute/v1/share/$SHARE_LINK_ID/pipelines/$PIPELINE_ID/results?limit=100"

The results response uses the same shape and cursor fields as the corresponding authenticated pipeline-results endpoint.

Unknown, expired, and archived links all return the same 404 response. A pipeline ID not covered by the link also returns 404. Resources whose retained data has already been deleted are not restored by a share link.

Retrieve metadata or revoke access

The authenticated management endpoint returns metadata even after the link expires or is archived:

curl "https://api.boltz.bio/compute/v1/share-links/$SHARE_LINK_ID" \
  -H "x-api-key: $BOLTZ_API_KEY"

Archive a link to revoke viewer access immediately:

curl "https://api.boltz.bio/compute/v1/share-links/$SHARE_LINK_ID/archive" \
  -X POST \
  -H "x-api-key: $BOLTZ_API_KEY"

Archiving is idempotent: repeated calls keep the original archived_at timestamp. It does not archive or delete the underlying predictions and pipelines.

Handle share-link URLs safely

• Treat both the id and visitable url as secrets.
• Do not log them or put them in analytics events, support tickets, or public pages.
• Avoid adding unrelated query parameters that could be copied or forwarded.
• Use the shortest practical expiration and archive links that are no longer needed.
• Prefer email mode when the recipient should prove control of a named Boltz account.

See Authentication for API-key and OAuth behavior, and Data retention for the lifetime of shared result data.