swagger: '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":\}’ inside the Request Header. The parameter name is "X-Registry-Auth". \ - 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 edge_stacks API version: 2.39.1 basePath: /api schemes: - http - https tags: - description: Manage Edge Stacks name: edge_stacks paths: /edge_stacks: get: description: '**Access policy**: administrator' operationId: EdgeStackList parameters: - description: will summarize the statuses in: query name: summarizeStatuses type: boolean produces: - application/json responses: '200': description: OK schema: items: $ref: '#/definitions/portainer.EdgeStack' type: array '400': description: Bad Request '500': description: Internal Server Error '503': description: Edge compute features are disabled security: - ApiKeyAuth: [] - jwt: [] summary: Fetches the list of EdgeStacks tags: - edge_stacks /edge_stacks/{id}: delete: description: '**Access policy**: administrator' operationId: EdgeStackDelete parameters: - description: EdgeStack Id in: path name: id required: true type: integer responses: '204': description: No Content '400': description: Bad Request '500': description: Internal Server Error '503': description: Edge compute features are disabled security: - ApiKeyAuth: [] - jwt: [] summary: Delete an EdgeStack tags: - edge_stacks get: description: '**Access policy**: administrator' operationId: EdgeStackInspect parameters: - description: EdgeStack Id in: path name: id required: true type: integer produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/portainer.EdgeStack' '400': description: Bad Request '500': description: Internal Server Error '503': description: Edge compute features are disabled security: - ApiKeyAuth: [] - jwt: [] summary: Inspect an EdgeStack tags: - edge_stacks put: consumes: - application/json description: '**Access policy**: administrator' operationId: EdgeStackUpdate parameters: - description: EdgeStack Id in: path name: id required: true type: integer - description: EdgeStack data in: body name: body required: true schema: $ref: '#/definitions/edgestacks.updateEdgeStackPayload' produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/portainer.EdgeStack' '400': description: Bad Request '500': description: Internal Server Error '503': description: Edge compute features are disabled security: - ApiKeyAuth: [] - jwt: [] summary: Update an EdgeStack tags: - edge_stacks /edge_stacks/{id}/file: get: description: '**Access policy**: administrator' operationId: EdgeStackFile parameters: - description: EdgeStack Id in: path name: id required: true type: integer produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/edgestacks.stackFileResponse' '400': description: Bad Request '500': description: Internal Server Error '503': description: Edge compute features are disabled security: - ApiKeyAuth: [] - jwt: [] summary: Fetches the stack file for an EdgeStack tags: - edge_stacks /edge_stacks/{id}/status: put: consumes: - application/json description: Authorized only if the request is done by an Edge Environment(Endpoint) operationId: EdgeStackStatusUpdate parameters: - description: EdgeStack Id in: path name: id required: true type: integer - description: EdgeStack status payload in: body name: body required: true schema: $ref: '#/definitions/edgestacks.updateStatusPayload' produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/portainer.EdgeStack' '400': description: Bad Request '403': description: Forbidden '404': description: Not Found '500': description: Internal Server Error summary: Update an EdgeStack status tags: - edge_stacks /edge_stacks/create/file: post: consumes: - multipart/form-data description: '**Access policy**: administrator' operationId: EdgeStackCreateFile parameters: - description: Name of the stack. it must only consist of lowercase alphanumeric characters, hyphens, or underscores as well as start with a letter or number in: formData name: Name required: true type: string - description: Content of the Stack file in: formData name: file required: true type: file - description: JSON stringified array of Edge Groups ids in: formData name: EdgeGroups required: true type: string - description: deploy type 0 - 'compose', 1 - 'kubernetes' in: formData name: DeploymentType required: true type: integer - description: JSON stringified array of Registry ids to use for this stack in: formData name: Registries type: string - description: Uses the manifest's namespaces instead of the default one, relevant only for kube environments in: formData name: UseManifestNamespaces type: boolean - description: Pre Pull image in: formData name: PrePullImage type: boolean - description: Retry deploy in: formData name: RetryDeploy type: boolean - description: if true, will not create an edge stack, but just will check the settings and return a non-persisted edge stack object in: query name: dryrun type: string produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/portainer.EdgeStack' '400': description: Bad request '500': description: Internal server error '503': description: Edge compute features are disabled security: - ApiKeyAuth: [] - jwt: [] summary: Create an EdgeStack from file tags: - edge_stacks /edge_stacks/create/repository: post: description: '**Access policy**: administrator' operationId: EdgeStackCreateRepository parameters: - description: stack config in: body name: body required: true schema: $ref: '#/definitions/edgestacks.edgeStackFromGitRepositoryPayload' - description: if true, will not create an edge stack, but just will check the settings and return a non-persisted edge stack object in: query name: dryrun type: string produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/portainer.EdgeStack' '400': description: Bad request '500': description: Internal server error '503': description: Edge compute features are disabled security: - ApiKeyAuth: [] - jwt: [] summary: Create an EdgeStack from a git repository tags: - edge_stacks /edge_stacks/create/string: post: description: '**Access policy**: administrator' operationId: EdgeStackCreateString parameters: - description: stack config in: body name: body required: true schema: $ref: '#/definitions/edgestacks.edgeStackFromStringPayload' - description: if true, will not create an edge stack, but just will check the settings and return a non-persisted edge stack object in: query name: dryrun type: string produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/portainer.EdgeStack' '400': description: Bad request '500': description: Internal server error '503': description: Edge compute features are disabled security: - ApiKeyAuth: [] - jwt: [] summary: Create an EdgeStack from a text tags: - edge_stacks /endpoints/{id}/edge/stacks/{stackId}: get: consumes: - application/json description: '**Access policy**: public' parameters: - description: environment(endpoint) Id in: path name: id required: true type: integer - description: EdgeStack Id in: path name: stackId required: true type: integer produces: - application/json responses: '200': description: OK schema: $ref: '#/definitions/edge.StackPayload' '400': description: Bad Request '404': description: Not Found '500': description: Internal Server Error summary: Inspect an Edge Stack for an Environment(Endpoint) tags: - edge_stacks definitions: edgestacks.stackFileResponse: properties: StackFileContent: type: string type: object gittypes.GitCredentialAuthType: enum: - 0 - 1 type: integer x-enum-varnames: - GitCredentialAuthType_Basic - GitCredentialAuthType_Token portainer.EdgeStack: properties: CreatedBy: description: The username which created this stack example: admin type: string CreatedByUserId: description: The username id which created this stack example: '1' type: string CreationDate: description: StatusArray map[EndpointID][]EdgeStackStatus `json:"StatusArray"` type: integer DeploymentType: $ref: '#/definitions/portainer.EdgeStackDeploymentType' EdgeGroups: items: type: integer type: array EntryPoint: type: string Id: description: EdgeStack Identifier example: 1 type: integer ManifestPath: type: string Name: type: string NumDeployments: type: integer ProjectPath: type: string Status: additionalProperties: $ref: '#/definitions/portainer.EdgeStackStatus' type: object UseManifestNamespaces: description: Uses the manifest's namespaces instead of the default one type: boolean Version: type: integer type: object portainer.StackDeploymentInfo: properties: ConfigHash: description: ConfigHash is the commit hash of the git repository used for deploying the stack type: string FileVersion: description: FileVersion is the version of the stack file, used to detect changes type: integer Version: description: Version is the version of the stack and also is the deployed version in edge agent type: integer type: object portainer.EdgeStackDeploymentType: enum: - 0 - 1 type: integer x-enum-varnames: - EdgeStackDeploymentCompose - EdgeStackDeploymentKubernetes edgestacks.edgeStackFromGitRepositoryPayload: properties: DeploymentType: allOf: - $ref: '#/definitions/portainer.EdgeStackDeploymentType' description: 'Deployment type to deploy this stack Valid values are: 0 - ''compose'', 1 - ''kubernetes'' compose is enabled only for docker environments kubernetes is enabled only for kubernetes environments' enum: - 0 - 1 - 2 example: 0 EdgeGroups: description: List of identifiers of EdgeGroups example: - 1 items: type: integer type: array FilePathInRepository: default: docker-compose.yml description: Path to the Stack file inside the Git repository example: docker-compose.yml type: string Name: description: 'Name of the stack Max length: 255 Name must only contains lowercase characters, numbers, hyphens, or underscores Name must start with a lowercase character or number Example: stack-name or stack_123 or stackName' example: stack-name type: string Registries: description: List of Registries to use for this stack items: type: integer type: array RepositoryAuthentication: description: Use basic authentication to clone the Git repository example: true type: boolean RepositoryAuthorizationType: allOf: - $ref: '#/definitions/gittypes.GitCredentialAuthType' description: RepositoryAuthorizationType is the authorization type to use example: 0 RepositoryPassword: description: Password used in basic authentication. Required when RepositoryAuthentication is true. example: myGitPassword type: string RepositoryReferenceName: description: Reference name of a Git repository hosting the Stack file example: refs/heads/master type: string RepositoryURL: description: URL of a Git repository hosting the Stack file example: https://github.com/openfaas/faas type: string RepositoryUsername: description: Username used in basic authentication. Required when RepositoryAuthentication is true. example: myGitUsername type: string TLSSkipVerify: description: TLSSkipVerify skips SSL verification when cloning the Git repository example: false type: boolean UseManifestNamespaces: description: Uses the manifest's namespaces instead of the default one type: boolean required: - EdgeGroups - Name - RepositoryURL type: object edgestacks.updateStatusPayload: properties: EndpointID: type: integer Error: type: string Status: $ref: '#/definitions/portainer.EdgeStackStatusType' Time: type: integer Version: type: integer type: object edge.StackPayload: properties: AlwaysCloneGitRepoForRelativePath: description: 'AlwaysCloneGitRepoForRelativePath is a flag indicating if the agent must always clone the git repository for relative path. This field is only valid when SupportRelativePath is true. Used only for EE' type: boolean CreatedBy: description: 'CreatedBy is the username that created this stack Used for adding labels to Kubernetes manifests' type: string CreatedByUserId: description: 'CreatedByUserId is the user ID that created this stack Used for adding labels to Kubernetes manifests' type: string DeployerOptionsPayload: $ref: '#/definitions/edge.DeployerOptionsPayload' DirEntries: description: Content of stack folder items: $ref: '#/definitions/filesystem.DirEntry' type: array EdgeUpdateID: description: 'EdgeUpdateID is the ID of the edge update related to this stack. Used only for EE' type: integer EntryFileName: description: Name of the stack entry file type: string EnvVars: description: 'Used only for EE EnvVars is a list of environment variables to inject into the stack' items: $ref: '#/definitions/portainer.Pair' type: array FilesystemPath: description: Mount point for relative path type: string ForceUpdate: description: 'ForceUpdate is a flag indicating if the agent must force the update of the stack. Used only for EE' type: boolean HelmConfig: allOf: - $ref: '#/definitions/portainer.HelmConfig' description: HelmConfig represents the Helm configuration for an edge stack ID: description: ID of the stack type: integer Name: description: Name of the stack type: string Namespace: description: Namespace to use for kubernetes stack. Keep empty to use the manifest namespace. type: string PrePullImage: description: 'PrePullImage is a flag indicating if the agent must pull the image before deploying the stack. Used only for EE' type: boolean RePullImage: description: 'RePullImage is a flag indicating if the agent must pull the image if it is already present on the node. Used only for EE' type: boolean ReadyRePullImage: description: 'Used only for EE async edge agent ReadyRePullImage is a flag to indicate whether the auto update is trigger to re-pull image Deprecated(2.36): use DeployerOptionsPayload.ForceRecreate instead' type: boolean RegistryCredentials: description: 'RegistryCredentials holds the credentials for a Docker registry. Used only for EE' items: $ref: '#/definitions/edge.RegistryCredentials' type: array RetryDeploy: description: 'RetryDeploy is a flag indicating if the agent must retry to deploy the stack if it fails. Used only for EE' type: boolean RetryPeriod: description: 'RetryPeriod specifies the duration, in seconds, for which the agent should continue attempting to deploy the stack after a failure Used only for EE' type: integer RollbackTo: description: RollbackTo specifies the stack file version to rollback to (only support to rollback to the last version currently) type: integer StackFileContent: description: Content of the stack file (for compatibility to agent version less than 2.19.0) type: string SupportRelativePath: description: Is relative path supported type: boolean Version: description: Version of the stack file type: integer type: object portainer.EdgeStackStatusType: enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 - 13 type: integer x-enum-varnames: - EdgeStackStatusPending - EdgeStackStatusDeploymentReceived - EdgeStackStatusError - EdgeStackStatusAcknowledged - EdgeStackStatusRemoved - EdgeStackStatusRemoteUpdateSuccess - EdgeStackStatusImagesPulled - EdgeStackStatusRunning - EdgeStackStatusDeploying - EdgeStackStatusRemoving - EdgeStackStatusPausedDeploying - EdgeStackStatusRollingBack - EdgeStackStatusRolledBack - EdgeStackStatusCompleted portainer.HelmConfig: properties: Atomic: description: Enable automatic rollback on deployment failure (equivalent to helm --atomic flag) example: true type: boolean ChartPath: description: Path to a Helm chart folder for Helm git deployments example: charts/my-app type: string Timeout: description: Timeout for Helm operations (equivalent to helm --timeout flag) example: 5m0s type: string ValuesFiles: description: Array of paths to Helm values YAML files for Helm git deployments example: - '[''values/prod.yaml''' - ' ''values/secrets.yaml'']' items: type: string type: array Version: description: Helm chart version from Chart.yaml (read-only, extracted during Git sync) example: 1.2.3 type: string type: object portainer.Pair: properties: name: example: name type: string value: example: value type: string type: object edge.RegistryCredentials: properties: Secret: type: string ServerURL: type: string Username: type: string type: object portainer.EdgeStackDeploymentStatus: properties: Error: type: string RollbackTo: description: EE only feature type: integer Time: type: integer Type: $ref: '#/definitions/portainer.EdgeStackStatusType' Version: type: integer type: object filesystem.DirEntry: properties: Content: type: string IsFile: type: boolean Name: type: string Permissions: $ref: '#/definitions/os.FileMode' type: object portainer.EdgeStackStatusDetails: properties: Acknowledged: type: boolean Error: type: boolean ImagesPulled: type: boolean Ok: type: boolean Pending: type: boolean RemoteUpdateSuccess: type: boolean Remove: type: boolean type: object os.FileMode: enum: - 2147483648 - 1073741824 - 536870912 - 268435456 - 134217728 - 67108864 - 33554432 - 16777216 - 8388608 - 4194304 - 2097152 - 1048576 - 524288 - 2401763328 - 511 - 2147483648 - 1073741824 - 536870912 - 268435456 - 134217728 - 67108864 - 33554432 - 16777216 - 8388608 - 4194304 - 2097152 - 1048576 - 524288 - 2401763328 - 511 type: integer x-enum-comments: ModeAppend: 'a: append-only' ModeCharDevice: 'c: Unix character device, when ModeDevice is set' ModeDevice: 'D: device file' ModeDir: 'd: is a directory' ModeExclusive: 'l: exclusive use' ModeIrregular: '?: non-regular file; nothing else is known about this file' ModeNamedPipe: 'p: named pipe (FIFO)' ModePerm: Unix permission bits, 0o777 ModeSetgid: 'g: setgid' ModeSetuid: 'u: setuid' ModeSocket: 'S: Unix domain socket' ModeSticky: 't: sticky' ModeSymlink: 'L: symbolic link' ModeTemporary: 'T: temporary file; Plan 9 only' x-enum-varnames: - ModeDir - ModeAppend - ModeExclusive - ModeTemporary - ModeSymlink - ModeDevice - ModeNamedPipe - ModeSocket - ModeSetuid - ModeSetgid - ModeCharDevice - ModeSticky - ModeIrregular - ModeType - ModePerm edgestacks.updateEdgeStackPayload: properties: DeploymentType: $ref: '#/definitions/portainer.EdgeStackDeploymentType' EdgeGroups: items: type: integer type: array StackFileContent: type: string UpdateVersion: type: boolean UseManifestNamespaces: description: Uses the manifest's namespaces instead of the default one type: boolean type: object edgestacks.edgeStackFromStringPayload: properties: DeploymentType: allOf: - $ref: '#/definitions/portainer.EdgeStackDeploymentType' description: 'Deployment type to deploy this stack Valid values are: 0 - ''compose'', 1 - ''kubernetes'' compose is enabled only for docker environments kubernetes is enabled only for kubernetes environments' enum: - 0 - 1 - 2 example: 0 EdgeGroups: description: List of identifiers of EdgeGroups example: - 1 items: type: integer type: array Name: description: 'Name of the stack Max length: 255 Name must only contains lowercase characters, numbers, hyphens, or underscores Name must start with a lowercase character or number Example: stack-name or stack_123 or stackName' example: stack-name type: string Registries: description: List of Registries to use for this stack items: type: integer type: array StackFileContent: description: Content of the Stack file example: "version: 3\n services:\n web:\n image:nginx" type: string UseManifestNamespaces: description: Uses the manifest's namespaces instead of the default one type: boolean required: - Name - StackFileContent type: object portainer.EdgeStackStatus: properties: DeploymentInfo: allOf: - $ref: '#/definitions/portainer.StackDeploymentInfo' description: EE only feature Details: allOf: - $ref: '#/definitions/portainer.EdgeStackStatusDetails' description: Deprecated EndpointID: type: integer Error: description: Deprecated type: string ReadyRePullImage: description: ReadyRePullImage is a flag to indicate whether the auto update is trigger to re-pull image type: boolean Status: items: $ref: '#/definitions/portainer.EdgeStackDeploymentStatus' type: array Type: allOf: - $ref: '#/definitions/portainer.EdgeStackStatusType' description: Deprecated type: object edge.DeployerOptionsPayload: properties: ForceRecreate: description: 'ForceRecreate is a flag indicating if the agent must force the redeployment of the stack. This field is only used when the Force Redeployment is triggered. Once the stack is redeployed, this field will be reset to false. For standard edge agent, this field is used in agent side For async edge agent, this field is used in both agent side and server side. This flag drives `docker compose up --force-recreate` option' type: boolean Prune: description: 'Prune is a flag indicating if the agent must prune the containers or not when creating/updating an edge stack This flag drives `docker compose up --remove-orphans` and `docker stack up --prune` options Used only for EE' type: boolean RemoveVolumes: description: 'RemoveVolumes is a flag indicating if the agent must remove the named volumes declared in the compose file and anonymouse volumes attached to containers This flag drives `docker compose down --volumes` option Used only for EE' type: boolean type: object securityDefinitions: ApiKeyAuth: in: header name: X-API-KEY type: apiKey jwt: in: header name: Authorization type: apiKey