Docker Hub Secret API

Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.

GitHub OpenAPI

Operations 5

GET /secrets List secrets #
POST /secrets/create Create a secret #
GET /secrets/{id} Inspect a secret #
DELETE /secrets/{id} Delete a secret #
POST /secrets/{id}/update Update a Secret #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/docker-hub:docker-hub-secret-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

docker-hub-secret-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Docker Engine Secret API
  version: '1.33'
  x-logo:
    url: https://docs.docker.com/images/logo-docker-main.png
  description: 'The Engine API is an HTTP API served by Docker Engine. It is the API the Docker client uses to communicate with the Engine, so everything the Docker client can do can be done with the API.


    Most of the client''s commands map directly to API endpoints (e.g. `docker ps` is `GET /containers/json`). The notable exception is running containers, which consists of several API calls.


    # Errors


    The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:


    ```

    {

    "message": "page not found"

    }

    ```


    # Versioning


    The API is usually changed in each release of Docker, so API calls are versioned to ensure that clients don''t break.


    For Docker Engine 17.09, the API version is 1.32. To lock to this version, you prefix the URL with `/v1.32`. For example, calling `/info` is the same as calling `/v1.32/info`.


    Engine releases in the near future should support this version of the API, so your client will continue to work even if it is talking to a newer Engine.


    In previous versions of Docker, it was possible to access the API without providing a version. This behaviour is now deprecated will be removed in a future version of Docker.


    The API uses an open schema model, which means server may add extra properties to responses. Likewise, the server will ignore any extra query parameters and request body properties. When you write clients, you need to ignore additional properties in responses to ensure they do not break when talking to newer Docker daemons.


    This documentation is for version 1.33 of the API. Use this table to find documentation for previous versions of the API:


    Docker version | API version | Changes

    ----------------|-------------|---------

    17.09.x | 1.31 | API changes

    17.07.x | 1.31 | API changes

    17.06.x | 1.30 | API changes

    17.05.x | 1.29 | API changes

    17.04.x | 1.28 | API changes

    17.03.1 | 1.27 | API changes

    1.13.1 & 17.03.0 | 1.26 | API changes

    1.13.0 | 1.25 | API changes

    1.12.x | 1.24 | API changes

    1.11.x | 1.23 | API changes

    1.10.x | 1.22 | API changes

    1.9.x | 1.21 | API changes

    1.8.x | 1.20 | API changes

    1.7.x | 1.19 | API changes

    1.6.x | 1.18 | API changes


    # Authentication


    Authentication for registries is handled client side. The client has to send authentication details to various endpoints that need to communicate with registries, such as `POST /images/(name)/push`. These are sent as `X-Registry-Auth` header as a Base64 encoded (JSON) string with the following structure:


    ```

    {

    "username": "string",

    "password": "string",

    "email": "string",

    "serveraddress": "string"

    }

    ```


    The `serveraddress` is a domain/IP without a protocol. Throughout this structure, double quotes are required.


    If you have already got an identity token from the `/auth` endpoint, you can just pass this instead of credentials:


    ```

    {

    "identitytoken": "9cbaf023786cd7..."

    }

    ```'
servers:
- url: /v1.33
tags:
- name: Secret
  x-displayName: Secrets
  description: Secrets are sensitive data that can be used by services. Swarm mode must be enabled for these endpoints to work.
paths:
  /secrets:
    get:
      summary: List secrets
      operationId: SecretList
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Secret'
                example:
                - ID: blt1owaxmitz71s9v5zh81zun
                  Version:
                    Index: 85
                  CreatedAt: '2017-07-20T13:55:28.678958722Z'
                  UpdatedAt: '2017-07-20T13:55:28.678958722Z'
                  Spec:
                    Name: mysql-passwd
                    Labels:
                      some.label: some.value
                    Driver:
                      Name: secret-bucket
                      Options:
                        OptionA: value for driver option A
                        OptionB: value for driver option B
                - ID: ktnbjxoalbkvbvedmg1urrz8h
                  Version:
                    Index: 11
                  CreatedAt: '2016-11-05T01:20:17.327670065Z'
                  UpdatedAt: '2016-11-05T01:20:17.327670065Z'
                  Spec:
                    Name: app-dev.crt
                    Labels:
                      foo: bar
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: filters
        in: query
        description: 'A JSON encoded value of the filters (a `map[string][]string`) to process on the secrets list. Available filters:


          - `id=<secret id>`

          - `label=<key> or label=<key>=value`

          - `name=<secret name>`

          - `names=<secret name>`

          '
        schema:
          type: string
      tags:
      - Secret
  /secrets/create:
    post:
      summary: Create a secret
      operationId: SecretCreate
      responses:
        201:
          description: no error
          content:
            application/json:
              schema:
                type: object
                properties:
                  ID:
                    description: The ID of the created secret.
                    type: string
                example:
                  ID: ktnbjxoalbkvbvedmg1urrz8h
        409:
          description: name conflicts with an existing object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Secret
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SecretSpec'
              - type: object
                example:
                  Name: app-key.crt
                  Labels:
                    foo: bar
                  Data: VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==
                  Driver:
                    Name: secret-bucket
                    Options:
                      OptionA: value for driver option A
                      OptionB: value for driver option B
  /secrets/{id}:
    get:
      summary: Inspect a secret
      operationId: SecretInspect
      responses:
        200:
          description: no error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
              example:
                ID: ktnbjxoalbkvbvedmg1urrz8h
                Version:
                  Index: 11
                CreatedAt: '2016-11-05T01:20:17.327670065Z'
                UpdatedAt: '2016-11-05T01:20:17.327670065Z'
                Spec:
                  Name: app-dev.crt
                  Labels:
                    foo: bar
                  Driver:
                    Name: secret-bucket
                    Options:
                      OptionA: value for driver option A
                      OptionB: value for driver option B
        404:
          description: secret not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the secret
        schema:
          type: string
      tags:
      - Secret
    delete:
      summary: Delete a secret
      operationId: SecretDelete
      responses:
        204:
          description: no error
        404:
          description: secret not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        required: true
        description: ID of the secret
        schema:
          type: string
      tags:
      - Secret
  /secrets/{id}/update:
    post:
      summary: Update a Secret
      operationId: SecretUpdate
      responses:
        200:
          description: no error
        400:
          description: bad parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        404:
          description: no such secret
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        500:
          description: server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        503:
          description: node is not part of a swarm
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        description: The ID or name of the secret
        required: true
        schema:
          type: string
      - name: version
        in: query
        description: The version number of the secret object being updated. This is required to avoid conflicting writes.
        required: true
        schema:
          type: integer
          format: int64
      tags:
      - Secret
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretSpec'
          text/plain:
            schema:
              $ref: '#/components/schemas/SecretSpec'
        description: The spec of the secret to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [SecretInspect endpoint](#operation/SecretInspect) response values.
components:
  schemas:
    Secret:
      type: object
      properties:
        ID:
          type: string
          example: blt1owaxmitz71s9v5zh81zun
        Version:
          $ref: '#/components/schemas/ObjectVersion'
        CreatedAt:
          type: string
          format: dateTime
          example: '2017-07-20T13:55:28.678958722Z'
        UpdatedAt:
          type: string
          format: dateTime
          example: '2017-07-20T13:55:28.678958722Z'
        Spec:
          $ref: '#/components/schemas/SecretSpec'
    ObjectVersion:
      description: 'The version number of the object such as node, service, etc. This is needed to avoid conflicting writes.

        The client must send the version number along with the modified specification when updating these objects.

        This approach ensures safe concurrency and determinism in that the change on the object

        may not be applied if the version number has changed from the last read. In other words,

        if two update requests specify the same base version, only one of the requests can succeed.

        As a result, two separate update requests that happen at the same time will not

        unintentionally overwrite each other.

        '
      type: object
      properties:
        Index:
          type: integer
          format: uint64
          example: 373531
    SecretSpec:
      type: object
      properties:
        Name:
          description: User-defined name of the secret.
          type: string
        Labels:
          description: User-defined key/value metadata.
          type: object
          additionalProperties:
            type: string
          example:
            com.example.some-label: some-value
            com.example.some-other-label: some-other-value
        Data:
          description: 'Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-3.2))

            data to store as secret.


            This field is only used to _create_ a secret, and is not returned by

            other endpoints.

            '
          type: string
          example: ''
        Driver:
          description: Name of the secrets driver used to fetch the secret's value from an external secret store
          $ref: '#/components/schemas/Driver'
    ErrorResponse:
      description: Represents an error.
      type: object
      required:
      - message
      properties:
        message:
          description: The error message.
          type: string
      example:
        message: Something went wrong.
    Driver:
      description: Driver represents a driver (network, logging, secrets).
      type: object
      required:
      - Name
      properties:
        Name:
          description: Name of the driver.
          type: string
          example: some-driver
        Options:
          description: Key/value map of driver-specific options.
          type: object
          additionalProperties:
            type: string
          example:
            OptionA: value for driver-specific option A
            OptionB: value for driver-specific option B