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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/portainer-stacks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
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
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 Stacks API
version: 2.39.1
servers:
- url: /api
tags:
- description: Manage stacks
name: stacks
paths:
/stacks:
get:
description: 'List all stacks based on the current user authorizations.
Will return all stacks if using an administrator account otherwise it
will only return the list of stacks the user have access to.
Limited stacks will not be returned by this endpoint.
**Access policy**: authenticated'
operationId: StackList
parameters:
- description: 'Filters to process on the stack list. Encoded as JSON (a map[string]string). For example, {''SwarmID'': ''jpofkc0i9uo9wtx1zesuk649w''} will only return stacks that are part of the specified Swarm cluster. Available filters: EndpointID, SwarmID.'
in: query
name: filters
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
items:
$ref: '#/components/schemas/portainer.Stack'
type: array
'204':
description: Success
'400':
description: Invalid request
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: List stacks
tags:
- stacks
/stacks/{id}:
delete:
description: 'Remove a stack.
**Access policy**: restricted'
operationId: StackDelete
parameters:
- description: Stack identifier
in: path
name: id
required: true
schema:
type: integer
- description: Set to true to delete an external stack. Only external Swarm stacks are supported
in: query
name: external
schema:
type: boolean
- description: Environment identifier
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'204':
description: Success
'400':
description: Invalid request
'403':
description: Permission denied
'404':
description: Not found
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Remove a stack
tags:
- stacks
get:
description: 'Retrieve details about a stack.
**Access policy**: restricted'
operationId: StackInspect
parameters:
- description: Stack identifier
in: path
name: id
required: true
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'403':
description: Permission denied
'404':
description: Stack not found
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Inspect a stack
tags:
- stacks
put:
description: 'Update a stack, only for file based stacks.
**Access policy**: authenticated'
operationId: StackUpdate
parameters:
- description: Stack identifier
in: path
name: id
required: true
schema:
type: integer
- description: Environment identifier
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'403':
description: Permission denied
'404':
description: Not found
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Update a stack
tags:
- stacks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.updateSwarmStackPayload'
description: Stack details
required: true
/stacks/{id}/associate:
put:
description: '**Access policy**: administrator'
operationId: StackAssociate
parameters:
- description: Stack identifier
in: path
name: id
required: true
schema:
type: integer
- description: Environment identifier
in: query
name: endpointId
required: true
schema:
type: integer
- description: Swarm identifier
in: query
name: swarmId
required: true
schema:
type: integer
- description: Indicates whether the stack is orphaned
in: query
name: orphanedRunning
required: true
schema:
type: boolean
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'403':
description: Permission denied
'404':
description: Stack not found
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Associate an orphaned stack to a new environment(endpoint)
tags:
- stacks
/stacks/{id}/file:
get:
description: 'Get Stack file content.
**Access policy**: restricted'
operationId: StackFileInspect
parameters:
- description: Stack identifier
in: path
name: id
required: true
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.stackFileResponse'
'400':
description: Invalid request
'403':
description: Permission denied
'404':
description: Stack not found
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Retrieve the content of the Stack file for the specified stack
tags:
- stacks
/stacks/{id}/git:
post:
description: 'Update the Git settings in a stack, e.g., RepositoryReferenceName and AutoUpdate
**Access policy**: authenticated'
operationId: StackUpdateGit
parameters:
- description: Stack identifier
in: path
name: id
required: true
schema:
type: integer
- description: Stacks created before version 1.18.0 might not have an associated environment(endpoint) identifier. Use this optional parameter to set the environment(endpoint) identifier used by the stack.
in: query
name: endpointId
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'403':
description: Permission denied
'404':
description: Not found
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Update a stack's Git configs
tags:
- stacks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.stackGitUpdatePayload'
description: Git configs for pull and redeploy a stack
required: true
/stacks/{id}/git/redeploy:
put:
description: 'Pull and redeploy a stack via Git
**Access policy**: authenticated'
operationId: StackGitRedeploy
parameters:
- description: Stack identifier
in: path
name: id
required: true
schema:
type: integer
- description: Stacks created before version 1.18.0 might not have an associated environment(endpoint) identifier. Use this optional parameter to set the environment(endpoint) identifier used by the stack.
in: query
name: endpointId
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'403':
description: Permission denied
'404':
description: Not found
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Redeploy a stack
tags:
- stacks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.stackGitRedployPayload'
description: Git configs for pull and redeploy of a stack. **StackName** may only be populated for Kuberenetes stacks, and if specified with a blank string, it will be set to blank
required: true
/stacks/{id}/migrate:
post:
description: 'Migrate a stack from an environment(endpoint) to another environment(endpoint). It will re-create the stack inside the target environment(endpoint) before removing the original stack.
**Access policy**: authenticated'
operationId: StackMigrate
parameters:
- description: Stack identifier
in: path
name: id
required: true
schema:
type: integer
- description: Stacks created before version 1.18.0 might not have an associated environment(endpoint) identifier. Use this optional parameter to set the environment(endpoint) identifier used by the stack.
in: query
name: endpointId
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'403':
description: Permission denied
'404':
description: Stack not found
'409':
description: A stack with the same name is already running on the target environment(endpoint)
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Migrate a stack to another environment(endpoint)
tags:
- stacks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.stackMigratePayload'
description: Stack migration details
required: true
/stacks/{id}/start:
post:
description: 'Starts a stopped Stack.
**Access policy**: authenticated'
operationId: StackStart
parameters:
- description: Stack identifier
in: path
name: id
required: true
schema:
type: integer
- description: Environment identifier
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'403':
description: Permission denied
'404':
description: Not found
'409':
description: Stack name is not unique
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Starts a stopped Stack
tags:
- stacks
/stacks/{id}/stop:
post:
description: 'Stops a stopped Stack.
**Access policy**: authenticated'
operationId: StackStop
parameters:
- description: Stack identifier
in: path
name: id
required: true
schema:
type: integer
- description: Environment identifier
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'403':
description: Permission denied
'404':
description: Not found
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Stops a stopped Stack
tags:
- stacks
/stacks/create/kubernetes/repository:
post:
description: 'Deploy a new stack into a Docker environment specified via the environment identifier.
**Access policy**: authenticated'
operationId: StackCreateKubernetesGit
parameters:
- description: Identifier of the environment that will be used to deploy the stack
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'409':
description: Stack name or webhook ID already exists
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Deploy a new kubernetes stack from a git repository
tags:
- stacks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.kubernetesGitDeploymentPayload'
description: stack config
required: true
/stacks/create/kubernetes/string:
post:
description: 'Deploy a new stack into a Docker environment specified via the environment identifier.
**Access policy**: authenticated'
operationId: StackCreateKubernetesFile
parameters:
- description: Identifier of the environment that will be used to deploy the stack
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Deploy a new kubernetes stack from a file
tags:
- stacks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.kubernetesStringDeploymentPayload'
description: stack config
required: true
/stacks/create/kubernetes/url:
post:
description: 'Deploy a new stack into a Docker environment specified via the environment identifier.
**Access policy**: authenticated'
operationId: StackCreateKubernetesUrl
parameters:
- description: Identifier of the environment that will be used to deploy the stack
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Deploy a new kubernetes stack from a url
tags:
- stacks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.kubernetesManifestURLDeploymentPayload'
description: stack config
required: true
/stacks/create/standalone/file:
post:
description: 'Deploy a new stack into a Docker environment specified via the environment identifier.
**Access policy**: authenticated'
operationId: StackCreateDockerStandaloneFile
parameters:
- description: Identifier of the environment that will be used to deploy the stack
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Deploy a new compose stack from a file
tags:
- stacks
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
Name:
type: string
description: Name of the stack
Env:
type: string
description: 'Environment variables passed during deployment, represented as a JSON array [{''name'': ''name'', ''value'': ''value''}].'
file:
type: string
description: Stack file
format: binary
required:
- Name
/stacks/create/standalone/repository:
post:
description: 'Deploy a new stack into a Docker environment specified via the environment identifier.
**Access policy**: authenticated'
operationId: StackCreateDockerStandaloneRepository
parameters:
- description: Identifier of the environment that will be used to deploy the stack
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'409':
description: Stack name or webhook ID already exists
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Deploy a new compose stack from repository
tags:
- stacks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.composeStackFromGitRepositoryPayload'
description: stack config
required: true
/stacks/create/standalone/string:
post:
description: 'Deploy a new stack into a Docker environment specified via the environment identifier.
**Access policy**: authenticated'
operationId: StackCreateDockerStandaloneString
parameters:
- description: Identifier of the environment that will be used to deploy the stack
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Deploy a new compose stack from a text
tags:
- stacks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.composeStackFromFileContentPayload'
description: stack config
required: true
/stacks/create/swarm/file:
post:
description: 'Deploy a new stack into a Docker environment specified via the environment identifier.
**Access policy**: authenticated'
operationId: StackCreateDockerSwarmFile
parameters:
- description: Identifier of the environment that will be used to deploy the stack
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Deploy a new swarm stack from a file
tags:
- stacks
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
Name:
type: string
description: Name of the stack
SwarmID:
type: string
description: Swarm cluster identifier.
Env:
type: string
description: 'Environment variables passed during deployment, represented as a JSON array [{''name'': ''name'', ''value'': ''value''}]. Optional'
file:
type: string
description: Stack file
format: binary
/stacks/create/swarm/repository:
post:
description: 'Deploy a new stack into a Docker environment specified via the environment identifier.
**Access policy**: authenticated'
operationId: StackCreateDockerSwarmRepository
parameters:
- description: Identifier of the environment that will be used to deploy the stack
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'409':
description: Stack name or webhook ID already exists
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Deploy a new swarm stack from a git repository
tags:
- stacks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.swarmStackFromGitRepositoryPayload'
description: stack config
required: true
/stacks/create/swarm/string:
post:
description: 'Deploy a new stack into a Docker environment specified via the environment identifier.
**Access policy**: authenticated'
operationId: StackCreateDockerSwarmString
parameters:
- description: Identifier of the environment that will be used to deploy the stack
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/portainer.Stack'
'400':
description: Invalid request
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Deploy a new swarm stack from a text
tags:
- stacks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/stacks.swarmStackFromFileContentPayload'
description: stack config
required: true
/stacks/name/{name}:
delete:
description: 'Remove a stack.
**Access policy**: restricted'
operationId: StackDeleteKubernetesByName
parameters:
- description: Stack name
in: path
name: name
required: true
schema:
type: string
- description: Set to true to delete an external stack. Only external Swarm stacks are supported
in: query
name: external
schema:
type: boolean
- description: Environment identifier
in: query
name: endpointId
required: true
schema:
type: integer
responses:
'204':
description: Success
'400':
description: Invalid request
'403':
description: Permission denied
'404':
description: Not found
'500':
description: Server error
security:
- ApiKeyAuth: []
- jwt: []
summary: Remove Kubernetes stacks by name
tags:
- stacks
/stacks/webhooks/{webhookID}:
post:
description: '**Access policy**: public'
operationId: WebhookInvoke
parameters:
- description: Stack identifier
in: path
name: webhookID
required: true
schema:
type: string
responses:
'200':
description: Success
'400':
description: Invalid request
'409':
description: Autoupdate for the stack isn't available
'500':
description: Server error
summary: Webhook for triggering stack updates from git
tags:
- stacks
components:
schemas:
portainer.UserResourceAccess:
properties:
AccessLevel:
$ref: '#/components/schemas/portainer.ResourceAccessLevel'
UserId:
type: integer
type: object
stacks.composeStackFromFileContentPayload:
properties:
Env:
description: A list of environment variables used during stack deployment
items:
$ref: '#/components/schemas/portainer.Pair'
type: array
FromAppTemplate:
description: Whether the stack is from a app template
example: false
type: boolean
Name:
description: Name of the stack
example: myStack
type: string
StackFileContent:
description: Content of the Stack file
example: "version: 3\n services:\n web:\n image:nginx"
type: string
required:
- Name
- StackFileContent
type: object
portainer.Pair:
properties:
name:
example: name
type: string
value:
example: value
type: string
type: object
portainer.StackType:
enum:
- 0
- 1
- 2
- 3
type: integer
x-enum-varnames:
- _
- DockerSwarmStack
- DockerComposeStack
- KubernetesStack
stacks.stackGitUpdatePayload:
properties:
AutoUpdate:
$ref: '#/components/schemas/portainer.AutoUpdateSettings'
Env:
items:
$ref: '#/components/schemas/portainer.Pair'
type: array
Prune:
type: boolean
RepositoryAuthentication:
type: boolean
RepositoryAuthorizationType:
$ref: '#/components/schemas/gittypes.GitCredentialAuthType'
RepositoryPassword:
type: string
RepositoryReferenceName:
type: string
RepositoryUsername:
type: string
TLSSkipVerify:
type: boolean
type: object
portainer.ResourceControlType:
enum:
- 0
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
type: integer
x-enum-varnames:
- _
- ContainerResourceControl
- ServiceResourceControl
- VolumeResourceControl
- NetworkResourceControl
- SecretResourceControl
- StackResourceControl
- ConfigResourceControl
- CustomTemplateResourceControl
- ContainerGroupResourceControl
stacks.updateSwarmStackPayload:
properties:
Env:
description: A list of environment(endpoint) variables used during stack deployment
items:
$ref: '#/components/schemas/portainer.Pair'
type: array
Prune:
description: Prune services that are no longer referenced (only available for Swarm stacks)
example: true
type: boolean
PullImage:
description: 'Deprecated(2.36): use RepullImageAndRedeploy instead for cleaner responsibility
Force a pulling to current image with the original tag though the image is already the latest'
example: false
type: boolean
RepullImageAndRedeploy:
description: RepullImageAndRed
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/portainer/refs/heads/main/openapi/portainer-stacks-api-openapi.yml