Download a record of a submission

Read · GET /v1/tenants/{tenant}/submissions/{submission}/{artifact} · MCP tool fetch

Returns one record of a submission, chosen with artifact: the spec as stored, the list of build outputs, the software bill of materials (SBOM), the provenance statement, the build tools left in the image, a download link for the image, or the result of your last installation on a server. If a record does not exist yet, the refusal says why.

Roles that can call it: viewer, builder, deployer.

Parameters

Name	In	Required	Description
`tenant`	path	yes	Your tenant ID
`submission`	path	yes	The submission ID that `submit` returned
`artifact`	path	yes	Which record to get. `image` gives a signed download link that expires; `provisioning` gives the result of your last installation, also when it failed. One of `spec`, `artifacts`, `sbom`, `provenance`, `retained-tooling`, `image`, `provisioning`

Returns

A JSON object with these keys: submission, tenant, artifact, content, guarantee, caller_authenticated.

Example request

curl https://api.tarsana.io/v1/tenants/acme/submissions/sha256:cdff062988d4722b2ff052c97ebefb8b571858c493ce47b159df73b1c88809b1/artifacts \
  -H "X-Tarsana-Access-Token: $ACCESS_TOKEN" \
  -H 'X-Tarsana-Tenant: acme'

Example response

{
  "submission": "sha256:cdff062988d4722b2ff052c97ebefb8b571858c493ce47b159df73b1c88809b1",
  "tenant": "acme",
  "artifact": "artifacts",
  "content": {
    "schema": "tarsana.submission-artifacts/v1",
    "job": "j-bbdde9adc372c296",
    "published_at": "2026-10-05T03:01:12Z",
    "image": {
      "format": "raw-verity",
      "digest": "sha256:0f1e2d3c...",
      "size_bytes": 734003200,
      "verity_roothash": "9c4b..."
    },
    "sbom": {
      "format": "CycloneDX",
      "digest": "sha256:fb917071...",
      "bytes": 48213
    },
    "provenance": {
      "format": "in-toto-dsse",
      "digest": "sha256:eeee...",
      "bytes": 1161
    },
    "release": {
      "version": "20261005-030112",
      "plain_sha256": "9487214a...",
      "plain_size": 2147483648
    }
  },
  "guarantee": "namespaces are separated, callers are not authenticated",
  "caller_authenticated": false
}

Errors

Code	HTTP	What it means
`invalid_parameter`	400	A value in your request does not have the expected format, for example a submission ID that is not a spec hash. Check the value against the field's description and try again.
`no_acting_tenant`	400	Your request does not say which tenant you are acting for. Send your tenant ID in the `X-Tarsana-Tenant` header, or with `--as` on the command line.
`isolation_refused`	403	This address belongs to a tenant ID you do not have access to. Check the tenant ID in the address and in your request header.
`no_such_submission`	404	You have no submission with this ID. Check the ID that `submit` returned.
`no_such_artifact`	404	This submission does not have that record yet. The response says what state the build is in and what will produce the record.
`image_endpoint_not_configured`	503	Image downloads are not available on this Tarsana deployment. Contact Tarsana support if you need them.
`unauthenticated`	401	Your request has no credential, or one that Tarsana does not recognise. Sign in with `login`, or send a valid access token.
`forbidden`	403	Your role does not allow this operation. The response names the roles that do; ask for a credential with one of them.
`rate_limited`	429	You sent too many requests in a short time. Wait for the number of seconds in `retry_after_seconds`, then try again.
`surface_fault`	500	Something went wrong on our side. Try again later, and contact Tarsana support if it keeps happening.

View this page as Markdown