Portainer templates API

openapi: 3.2.0
info:
  contact:
    email: info@portainer.io
  description: 'Portainer API is an HTTP API served by Portainer. It is used by the Portainer UI and everything you can do with the UI can be done using the HTTP API.

    Examples are available at https://documentation.portainer.io/api/api-examples/

    You can find out more about Portainer at [http://portainer.io](http://portainer.io) and get some support on [Slack](http://portainer.io/slack/).


    # Authentication


    Most of the API environments(endpoints) require to be authenticated as well as some level of authorization to be used.

    Portainer API uses JSON Web Token to manage authentication and thus requires you to provide a token in the **Authorization** header of each request

    with the **Bearer** authentication mechanism.


    Example:


    ```

    Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE

    ```


    # Security


    Each API environment(endpoint) has an associated access policy, it is documented in the description of each environment(endpoint).


    Different access policies are available:


    - Public access

    - Authenticated access

    - Restricted access

    - Administrator access


    ### Public access


    No authentication is required to access the environments(endpoints) with this access policy.


    ### Authenticated access


    Authentication is required to access the environments(endpoints) with this access policy.


    ### Restricted access


    Authentication is required to access the environments(endpoints) with this access policy.

    Extra-checks might be added to ensure access to the resource is granted. Returned data might also be filtered.


    ### Administrator access


    Authentication as well as an administrator role are required to access the environments(endpoints) with this access policy.


    # Execute Docker requests


    Portainer **DO NOT** expose specific environments(endpoints) to manage your Docker resources (create a container, remove a volume, etc...).


    Instead, it acts as a reverse-proxy to the Docker HTTP API. This means that you can execute Docker requests **via** the Portainer HTTP API.


    To do so, you can use the `/endpoints/{id}/docker` Portainer API environment(endpoint) (which is not documented below due to Swagger limitations). This environment(endpoint) has a restricted access policy so you still need to be authenticated to be able to query this environment(endpoint). Any query on this environment(endpoint) will be proxied to the Docker API of the associated environment(endpoint) (requests and responses objects are the same as documented in the Docker API).


    # Private Registry


    Using private registry, you will need to pass a based64 encoded JSON string ‘{"registryId":\<registryID value\>}’ inside the Request Header. The parameter name is "X-Registry-Auth".

    \<registryID value\> - The registry ID where the repository was created.


    Example:


    ```

    eyJyZWdpc3RyeUlkIjoxfQ==

    ```


    **NOTE**: You can find more information on how to query the Docker API in the [Docker official documentation](https://docs.docker.com/engine/api/v1.30/) as well as in [this Portainer example](https://documentation.portainer.io/api/api-examples/).

    '
  license:
    name: zlib
    url: https://github.com/portainer/portainer/blob/develop/LICENSE
  title: PortainerCE auth Templates API
  version: 2.39.1
servers:
- url: /api
tags:
- description: Manage App Templates
  name: templates
paths:
  /templates:
    get:
      description: 'List available templates.

        **Access policy**: authenticated'
      operationId: TemplateList
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/templates.listResponse'
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: List available templates
      tags:
      - templates
  /templates/{id}/file:
    post:
      description: 'Get a template''s file

        **Access policy**: authenticated'
      operationId: TemplateFile
      parameters:
      - description: Template identifier
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/templates.fileResponse'
        '400':
          description: Invalid request
        '500':
          description: Server error
      security:
      - ApiKeyAuth: []
      - jwt: []
      summary: Get a template's file
      tags:
      - templates
components:
  schemas:
    portainer.Pair:
      properties:
        name:
          example: name
          type: string
        value:
          example: value
          type: string
      type: object
    portainer.TemplateVolume:
      properties:
        bind:
          description: Path on the host
          example: /tmp
          type: string
        container:
          description: Path inside the container
          example: /data
          type: string
        readonly:
          description: Whether the volume used should be readonly
          example: true
          type: boolean
      type: object
    templates.fileResponse:
      properties:
        FileContent:
          description: The requested file content
          example: version:2
          type: string
      type: object
    portainer.TemplateRepository:
      properties:
        stackfile:
          description: Path to the stack file inside the git repository
          example: ./subfolder/docker-compose.yml
          type: string
        url:
          description: URL of a git repository used to deploy a stack template. Mandatory for a Swarm/Compose stack template
          example: https://github.com/portainer/portainer-compose
          type: string
      type: object
    templates.listResponse:
      properties:
        templates:
          items:
            $ref: '#/components/schemas/portainer.Template'
          type: array
        version:
          type: string
      type: object
    portainer.TemplateType:
      enum:
      - 0
      - 1
      - 2
      - 3
      type: integer
      x-enum-varnames:
      - _
      - ContainerTemplate
      - SwarmStackTemplate
      - ComposeStackTemplate
    portainer.TemplateEnv:
      properties:
        default:
          description: Default value that will be set for the variable
          example: default_value
          type: string
        description:
          description: Content of the tooltip that will be generated in the UI
          example: MySQL root account password
          type: string
        label:
          description: Text for the label that will be generated in the UI
          example: Root password
          type: string
        name:
          description: name of the environment(endpoint) variable
          example: MYSQL_ROOT_PASSWORD
          type: string
        preset:
          description: If set to true, will not generate any input for this variable in the UI
          example: false
          type: boolean
        select:
          description: A list of name/value that will be used to generate a dropdown in the UI
          items:
            $ref: '#/components/schemas/portainer.TemplateEnvSelect'
          type: array
      type: object
    portainer.TemplateEnvSelect:
      properties:
        default:
          description: Will set this choice as the default choice
          example: false
          type: boolean
        text:
          description: Some text that will displayed as a choice
          example: text value
          type: string
        value:
          description: A value that will be associated to the choice
          example: value
          type: string
      type: object
    portainer.Template:
      properties:
        administrator_only:
          description: Whether the template should be available to administrators only
          example: true
          type: boolean
        categories:
          description: A list of categories associated to the template
          example:
          - database
          items:
            type: string
          type: array
        command:
          description: The command that will be executed in a container template
          example: ls -lah
          type: string
        description:
          description: Description of the template
          example: High performance web server
          type: string
        env:
          description: A list of environment(endpoint) variables used during the template deployment
          items:
            $ref: '#/components/schemas/portainer.TemplateEnv'
          type: array
        hostname:
          description: Container hostname
          example: mycontainer
          type: string
        id:
          description: 'Mandatory container/stack fields

            Template Identifier'
          example: 1
          type: integer
        image:
          description: 'Mandatory container fields

            Image associated to a container template. Mandatory for a container template'
          example: nginx:latest
          type: string
        interactive:
          description: 'Whether the container should be started in

            interactive mode (-i -t equivalent on the CLI)'
          example: true
          type: boolean
        labels:
          description: Container labels
          items:
            $ref: '#/components/schemas/portainer.Pair'
          type: array
        logo:
          description: URL of the template's logo
          example: https://portainer.io/img/logo.svg
          type: string
        name:
          description: 'Optional stack/container fields

            Default name for the stack/container to be used on deployment'
          example: mystackname
          type: string
        network:
          description: Name of a network that will be used on container deployment if it exists inside the environment(endpoint)
          example: mynet
          type: string
        note:
          description: A note that will be displayed in the UI. Supports HTML content
          example: This is my <b>custom</b> template
          type: string
        platform:
          description: 'Platform associated to the template.

            Valid values are: ''linux'', ''windows'' or leave empty for multi-platform'
          example: linux
          type: string
        ports:
          description: A list of ports exposed by the container
          example:
          - 8080:80/tcp
          items:
            type: string
          type: array
        privileged:
          description: Whether the container should be started in privileged mode
          example: true
          type: boolean
        registry:
          description: 'Optional container fields

            The URL of a registry associated to the image for a container template'
          example: quay.io
          type: string
        repository:
          allOf:
          - $ref: '#/components/schemas/portainer.TemplateRepository'
          description: Mandatory stack fields
        restart_policy:
          description: Container restart policy
          example: on-failure
          type: string
        stackFile:
          description: 'Mandatory Edge stack fields

            Stack file used for this template'
          type: string
        title:
          description: Title of the template
          example: Nginx
          type: string
        type:
          allOf:
          - $ref: '#/components/schemas/portainer.TemplateType'
          description: 'Template type. Valid values are: 1 (container), 2 (Swarm stack), 3 (Compose stack), 4 (Compose edge stack)'
          example: 1
        volumes:
          description: A list of volumes used during the container template deployment
          items:
            $ref: '#/components/schemas/portainer.TemplateVolume'
          type: array
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-KEY
      type: apiKey
    jwt:
      in: header
      name: Authorization
      type: apiKey