Search or ask Docker

Get attestation statements for an image

GET /images/{name}/attestations — Docker Engine API 1.57.

View Markdown
GET/images/{name}/attestations

Return the in-toto attestation statements attached to the image for the given platform. The daemon locates the attestation manifest(s) that reference the matching platform image manifest, reads their statement layers, and returns the verbatim statement JSON together with layer metadata.

If the image has no attestations an empty array is returned.

Connection and access

API connection and authentication guidance

/v1.57

No HTTP authentication requirement is declared for this operation. Transport access controls can still apply.

Parameters

name path Required

Image name or id

Type: string

All schema constraints and annotations
{
  "type": "string"
}

platform query

JSON-encoded OCI platform to select the image variant whose attestations to return. If omitted, the daemon's default (host) platform is used.

Only one platform value is currently accepted; passing more than one returns an error. The parameter is declared as an array so the wire shape can accept multiple values in the future without an API version bump.

Example: {"os": "linux", "architecture": "amd64"}

Type: array

Array item

Type: string

All schema constraints and annotations
{
  "type": "string"
}
All schema constraints and annotations
{
  "items": {
    "type": "string"
  },
  "type": "array"
}

Serialization: form

type query

In-toto predicate type URI to filter returned statements. May be repeated to accept any of several predicate types. If omitted, all statements are returned.

Example: type=https://slsa.dev/provenance/v0.2&type=https://spdx.dev/Document

Type: array

Array item

Type: string

All schema constraints and annotations
{
  "type": "string"
}
All schema constraints and annotations
{
  "items": {
    "type": "string"
  },
  "type": "array"
}

Serialization: form

statement query

Include the verbatim in-toto statement body in each returned entry. Defaults to false; when omitted or false, only the descriptor and predicate type are returned and statement blobs are not read.

Type: boolean

All schema constraints and annotations
{
  "default": false,
  "type": "boolean"
}

Request and responses

Response 200

No error

application/json

Type: array

Array item

Schema: AttestationStatement

All schema constraints and annotations
{
  "items": {
    "$ref": "#/components/schemas/AttestationStatement"
  },
  "type": "array"
}

Response 400

Bad parameter (e.g. malformed platform value)

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 404

No such image, or no manifest found for the requested platform

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 500

Server error

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 501

The daemon's image backend does not support attestations. This is returned by the legacy (graphdriver) image store, which does not preserve OCI image indexes.

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Referenced schemas

#/components/schemas/AttestationStatement

#/components/schemas/ErrorResponse

Complete operation contract
{
  "description": "Return the in-toto attestation statements attached to the image for the\ngiven platform. The daemon locates the attestation manifest(s) that\nreference the matching platform image manifest, reads their statement\nlayers, and returns the verbatim statement JSON together with layer\nmetadata.\n\nIf the image has no attestations an empty array is returned.\n",
  "operationId": "ImageAttestations",
  "parameters": [
    {
      "description": "Image name or id",
      "in": "path",
      "name": "name",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "JSON-encoded OCI platform to select the image variant whose\nattestations to return.\nIf omitted, the daemon's default (host) platform is used.\n\nOnly one platform value is currently accepted; passing more than\none returns an error. The parameter is declared as an array so the\nwire shape can accept multiple values in the future without an\nAPI version bump.\n\nExample: `{\"os\": \"linux\", \"architecture\": \"amd64\"}`",
      "explode": true,
      "in": "query",
      "name": "platform",
      "required": false,
      "schema": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "style": "form"
    },
    {
      "description": "In-toto predicate type URI to filter returned statements. May be\nrepeated to accept any of several predicate types. If omitted, all\nstatements are returned.\n\nExample: `type=https://slsa.dev/provenance/v0.2\u0026type=https://spdx.dev/Document`",
      "explode": true,
      "in": "query",
      "name": "type",
      "required": false,
      "schema": {
        "items": {
          "type": "string"
        },
        "type": "array"
      },
      "style": "form"
    },
    {
      "description": "Include the verbatim in-toto statement body in each returned\nentry. Defaults to false; when omitted or false, only the\ndescriptor and predicate type are returned and statement blobs\nare not read.",
      "in": "query",
      "name": "statement",
      "required": false,
      "schema": {
        "default": false,
        "type": "boolean"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/AttestationStatement"
            },
            "type": "array"
          }
        }
      },
      "description": "No error"
    },
    "400": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Bad parameter (e.g. malformed `platform` value)"
    },
    "404": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "No such image, or no manifest found for the requested platform"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Server error"
    },
    "501": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "The daemon's image backend does not support attestations. This\nis returned by the legacy (graphdriver) image store, which does\nnot preserve OCI image indexes.\n"
    }
  },
  "summary": "Get attestation statements for an image",
  "tags": [
    "Image"
  ]
}