SLIDESHOT [docs] Markdown
For agents: read the markdown version of these docs →

Artifacts

Every run produces a set of artifacts: the polished demo, the raw recording, the plan the agent executed, and an event log. Artifacts are listed per run and downloaded over an authenticated URL.

What a run produces

Every run ships these artifacts:

  • demo.mp4: The polished demo video. This is the artifact you publish.
  • raw.mp4: The unedited screen recording before post-processing. Useful when you want to re-render with different visual options without re-running the workflow.
  • plan.json: The plan the agent executed: normalized goal, success criteria, per-iteration actions, and the action history. Good for understanding why a run produced the demo it did.
  • events.jsonl: Structured event stream emitted during the run. One JSON object per line. Useful for debugging or building dashboards.
  • trace.zip: Full browser trace bundle. Open it with Playwright’s trace viewer when you need to dig into a failed run.

Opt-in artifacts:

  • demo.gif: Rendered from the final demo.mp4 when the run was created with options.artifacts.gif=true.

Endpoints

  • GET /v1/agent/runs/:id/artifacts: List artifacts produced by a run.
  • GET /v1/downloads/:artifactId: Download a specific artifact.

List artifacts for a run

curl https://api.slideshot.ai/v1/agent/runs/$RUN_ID/artifacts \
  -H "x-api-key: $SLIDESHOT_API_KEY"
{
  "data": [
    {
      "id": "aaaa1111-bbbb-2222-cccc-333344445555",
      "name": "demo.mp4",
      "content_type": "video/mp4",
      "size_bytes": 5829412,
      "download_url": "https://api.slideshot.ai/v1/downloads/aaaa1111-bbbb-2222-cccc-333344445555",
      "created_at": "2026-05-11T12:03:21Z"
    },
    {
      "id": "bbbb2222-cccc-3333-dddd-444455556666",
      "name": "plan.json",
      "content_type": "application/json",
      "size_bytes": 41229,
      "download_url": "https://api.slideshot.ai/v1/downloads/bbbb2222-cccc-3333-dddd-444455556666",
      "created_at": "2026-05-11T12:03:21Z"
    }
  ]
}

Each entry includes the artifact name, a stable download URL, and content metadata. Names match the filenames listed above.

Download an artifact

curl -L -o demo.mp4 \
  "https://api.slideshot.ai/v1/downloads/$ARTIFACT_ID" \
  -H "x-api-key: $SLIDESHOT_API_KEY"

The endpoint authorizes the request with the same API key (or session) that owns the run, then either streams the bytes directly or redirects to a short-lived presigned URL. Use -L (or your client’s redirect-follow flag) so the download follows the redirect.

The CLI wraps the same flow:

slideshot runs download $RUN_ID --artifact demo.mp4 --dir ./artifacts

You can pass --artifact multiple times to download several files at once.

Authorization

Downloads require the same auth as the parent run:

  • The API key that created the run can download every artifact.
  • A user signed into the Slideshot dashboard can download every artifact for their own runs.

Cross-key access is rejected: an artifact ID by itself is not enough to download a file.

Naming and retention

  • Artifact names are stable: demo.mp4, raw.mp4, plan.json, events.jsonl, trace.zip, and demo.gif (when applicable).
  • Download URLs returned by the list endpoint are stable and continue to work as long as the run exists. Presigned redirects expire quickly (under five minutes), so refetch the list rather than caching the redirect target.
  • Runs: the lifecycle that produces these artifacts.
  • Customize video: options that change what ends up in demo.mp4 and demo.gif.
  • API overview: error model and authentication.