# :fontawesome-solid-code: API
Portainer exposes an HTTP API that you can use to automate everything you do via the Portainer UI. You may also use Portainer as a gateway (HTTP queries against the Portainer API) to the underlying Docker/Kubernetes API.
!!! Note "API documentation is available [here](../api-schema/)"
## :octicons-code-review-16: Examples
!!! Note "The following examples use [httpie](https://httpie.org/){target=_blank} to execute API calls against Portainer"
### Initialize the admin password
On a fresh install of Portainer, you need to create an admin account to initialize Portainer. You will be asked for this when you visit the Portainer url for the very first time. You can acheive the same using the below
```shell
http POST /api/users/admin/init Username="" Password=""
```
### Authenticate against the API using the admin account
```shell
http POST /api/auth Username="" Password=""
```
The response is a JSON object containing the JWT token inside the jwt field:
```shell
{
"jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE"
}
```
You need to retrieve this token. You will need to pass this token inside the Authorization header when executing an authentication query against the API.
The value of the Authorization header must be of the form Bearer .
```
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE
```
**Note**: This token has a 8 hour validity, you'll need to generate another token to execute authenticated queries once this one expires.
### Create a new endpoint
Here, We'll show how to create 3 different types of endpoints:
* Local endpoint using Docker socket communication
* Remote endpoint using TCP communication
* Remote endpoint using TCP communication secured via TLS
#### Local endpoint via the Docker socket
This query will create an endpoint called test-local and will use the Docker socket to communicate with this environment.
**Note**: This example requires to you bind-mount the Docker socket when running Portainer.
```shell
http --form POST " \
Name="" EndpointCreationType=1
```
The response is a JSON object representing the endpoint:
```json
{
"AuthorizedTeams": [],
"AuthorizedUsers": [],
"Extensions": [],
"GroupId": 1,
"Id": 2,
"Name": "",
"PublicURL": "",
"Type": 1,
"TLSConfig": {
"TLS": false,
"TLSSkipVerify": false
},
"Type": 1,
"URL": "unix:///var/run/docker.sock"
}
```
#### Remote endpoint
This query will create an endpoint called test-remote and will communicate with this environment over TCP using the IP address 10.0.7.10 and port 2375 (these are example values, ensure that you're using the correct IP & port).
**Note**: The Docker API must be exposed on that IP address & port. Please refer to the Docker documentation to check how to configure this.
```shell
http --form POST /api/endpoints \
"Authorization: Bearer " \
Name="test-remote" URL="tcp://10.0.7.10:2375" EndpointCreationType=1
```
The response is a JSON object representing the endpoint:
```json
{
"AuthorizedTeams": [],
"AuthorizedUsers": [],
"Extensions": [],
"GroupId": 1,
"Id": 1,
"Type": 1,
"Name": "test-remote",
"PublicURL": "",
"TLSConfig": {
"TLS": false,
"TLSSkipVerify": false
},
"Type": 1,
"URL": "tcp://10.0.7.10:2375"
}
```
#### Remote endpoint secured using TLS
This query will create an endpoint called test-remote-tls and will communicate with this environment over TCP (secured with TLS) using the IP address 10.0.7.10 and port 2376 (these are example values, ensure that you're using the correct IP & port).
**Note**: The Docker API must be exposed on that IP address & port. Please refer to the Docker documentation to check how to configure this.
```shell
http --form POST /api/endpoints \
"Authorization: Bearer " \
Name="test-remote-tls" URL="tcp://10.0.7.10:2376" EndpointCreationType=1 TLS="true" TLSCACertFile@/path/to/ca.pem TLSCertFile@/path/to/cert.pem TLSKeyFile@/path/to/key.pem
```
The response is a JSON object representing the endpoint:
```json
{
"AuthorizedTeams": [],
"AuthorizedUsers": [],
"Extensions": [],
"GroupId": 1,
"Id": 1,
"Type": 1,
"Name": "test-remote",
"PublicURL": "",
"TLSConfig": {
"TLS": true,
"TLSCACert": "/data/tls/1/ca.pem",
"TLSCert": "/data/tls/1/cert.pem",
"TLSKey": "/data/tls/1/key.pem",
"TLSSkipVerify": false
},
"Type": 1,
"URL": "tcp://10.0.7.10:2376"
}
```
### Execute Docker queries against a specific endpoint
By using the following Portainer HTTP API endpoint /api/endpoints//docker, you can now execute any of the Docker HTTP API requests.
This Portainer HTTP API endpoint acts as a reverse-proxy to the Docker HTTP API.
**Note**: You can refer to the Docker API [documentation](https://docs.docker.com/engine/api/) to get more information on how you can query the Docker engine.
#### List all containers
Here is how you can list all the containers available in a specific endpoint:
```shell
http GET /api/endpoints/1/docker/containers/json \
"Authorization: Bearer " \
all==true
```
The response is exactly the same as returned by the ContainerList operation of the Docker API, see the [documentation for the ContainerList operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerList){target=_blank}.
#### Create a container
Here is how you can create a container in a specific endpoint using the Portainer HTTP API as a gateway.
This query will create a new Docker container inside the endpoint using the ID 1. The container will be named web01, use the nginx:latest Docker image and publish the container port 80 on via the 8080 port on the host.
See the link below to retrieve more information on how you can create a container using the Docker HTTP API.
```shell
http POST /api/endpoints/1/docker/containers/create \
"Authorization: Bearer " \
name=="web01" Image="nginx:latest" \
ExposedPorts:='{ "80/tcp": {} }' \
HostConfig:='{ "PortBindings": { "80/tcp": [{ "HostPort": "8080" }] } }'
```
The response is exactly the same as returned by the ContainerCreate operation of the Docker API, see the [documentation for the ContainerCreate operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerCreate){target=_blank}.
Example response:
```json
{
"Id": "5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107",
"Warnings": null
}
```
Retrieve the ID of the container, you will need it to execute actions against that container.
#### Start a container
You can now start the container that you previously created using the endpoint /api/endpoints//docker/containers//start (ensure you retrieved the ID of the container created previsouly):
```shell
http POST /api/endpoints/1/docker/containers/5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107/start \
"Authorization: Bearer "
```
The response is exactly the same as returned by the ContainerStart operation of the Docker API, see the [documentation for the ContainerStart operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerStart){target=_blank}.
#### Delete a container
You can create a container using the following endpoint /api/endpoints//docker/containers/:
```shell
http DELETE /api/endpoints/1/docker/containers/5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107 \
"Authorization: " \
force==true
```
The response is exactly the same as returned by the ContainerDelete operation of the Docker API, see the [documentation for the ContainerDelete operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerDelete){target=_blank}.
*More Examples to be added soon*
## :material-note-text: Notes
[Contribute to these docs](https://github.com/portainer/portainer-docs/blob/master/contributing.md){target=_blank}