THIS IS A TEST INSTANCE ONLY! REPOSITORIES CAN BE DELETED AT ANY TIME!

This is Gitea test Portainer repository mirror from Github
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

4783 lines
140 KiB

  1. ---
  2. swagger: "2.0"
  3. info:
  4. description: |
  5. 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.
  6. Examples are available at https://gist.github.com/deviantony/77026d402366b4b43fa5918d41bc42f8
  7. You can find out more about Portainer at [http://portainer.io](http://portainer.io) and get some support on [Slack](http://portainer.io/slack/).
  8. # Authentication
  9. Most of the API endpoints require to be authenticated as well as some level of authorization to be used.
  10. Portainer API uses JSON Web Token to manage authentication and thus requires you to provide a token in the **Authorization** header of each request
  11. with the **Bearer** authentication mechanism.
  12. Example:
  13. ```
  14. Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE
  15. ```
  16. # Security
  17. Each API endpoint has an associated access policy, it is documented in the description of each endpoint.
  18. Different access policies are available:
  19. * Public access
  20. * Authenticated access
  21. * Restricted access
  22. * Administrator access
  23. ### Public access
  24. No authentication is required to access the endpoints with this access policy.
  25. ### Authenticated access
  26. Authentication is required to access the endpoints with this access policy.
  27. ### Restricted access
  28. Authentication is required to access the endpoints with this access policy.
  29. Extra-checks might be added to ensure access to the resource is granted. Returned data might also be filtered.
  30. ### Administrator access
  31. Authentication as well as an administrator role are required to access the endpoints with this access policy.
  32. # Execute Docker requests
  33. Portainer **DO NOT** expose specific endpoints to manage your Docker resources (create a container, remove a volume, etc...).
  34. 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.
  35. To do so, you can use the `/endpoints/{id}/docker` Portainer API endpoint (which is not documented below due to Swagger limitations). This endpoint has a restricted access policy so you still need to be authenticated to be able to query this endpoint. Any query on this endpoint will be proxied to the Docker API of the associated endpoint (requests and responses objects are the same as documented in the Docker API).
  36. **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://gist.github.com/deviantony/77026d402366b4b43fa5918d41bc42f8).
  37. version: "1.24.0-dev"
  38. title: "Portainer API"
  39. contact:
  40. email: "info@portainer.io"
  41. host: "portainer.domain"
  42. basePath: "/api"
  43. tags:
  44. - name: "auth"
  45. description: "Authenticate against Portainer HTTP API"
  46. - name: "dockerhub"
  47. description: "Manage how Portainer connects to the DockerHub"
  48. - name: "endpoints"
  49. description: "Manage Docker environments"
  50. - name: "endpoint_groups"
  51. description: "Manage endpoint groups"
  52. - name: "extensions"
  53. description: "Manage extensions"
  54. - name: "registries"
  55. description: "Manage Docker registries"
  56. - name: "resource_controls"
  57. description: "Manage access control on Docker resources"
  58. - name: "roles"
  59. description: "Manage roles"
  60. - name: "settings"
  61. description: "Manage Portainer settings"
  62. - name: "status"
  63. description: "Information about the Portainer instance"
  64. - name: "stacks"
  65. description: "Manage Docker stacks"
  66. - name: "users"
  67. description: "Manage users"
  68. - name: "tags"
  69. description: "Manage tags"
  70. - name: "teams"
  71. description: "Manage teams"
  72. - name: "team_memberships"
  73. description: "Manage team memberships"
  74. - name: "templates"
  75. description: "Manage App Templates"
  76. - name: "stacks"
  77. description: "Manage stacks"
  78. - name: "upload"
  79. description: "Upload files"
  80. - name: "websocket"
  81. description: "Create exec sessions using websockets"
  82. schemes:
  83. - "http"
  84. - "https"
  85. paths:
  86. /auth:
  87. post:
  88. tags:
  89. - "auth"
  90. summary: "Authenticate a user"
  91. description: |
  92. Use this endpoint to authenticate against Portainer using a username and password.
  93. **Access policy**: public
  94. operationId: "AuthenticateUser"
  95. consumes:
  96. - "application/json"
  97. produces:
  98. - "application/json"
  99. parameters:
  100. - in: "body"
  101. name: "body"
  102. description: "Credentials used for authentication"
  103. required: true
  104. schema:
  105. $ref: "#/definitions/AuthenticateUserRequest"
  106. responses:
  107. 200:
  108. description: "Success"
  109. schema:
  110. $ref: "#/definitions/AuthenticateUserResponse"
  111. 400:
  112. description: "Invalid request"
  113. schema:
  114. $ref: "#/definitions/GenericError"
  115. examples:
  116. application/json:
  117. err: "Invalid credentials"
  118. 500:
  119. description: "Server error"
  120. schema:
  121. $ref: "#/definitions/GenericError"
  122. 503:
  123. description: "Authentication disabled"
  124. schema:
  125. $ref: "#/definitions/GenericError"
  126. examples:
  127. application/json:
  128. err: "Authentication is disabled"
  129. /dockerhub:
  130. get:
  131. tags:
  132. - "dockerhub"
  133. summary: "Retrieve DockerHub information"
  134. description: |
  135. Use this endpoint to retrieve the information used to connect to the DockerHub
  136. **Access policy**: authenticated
  137. operationId: "DockerHubInspect"
  138. produces:
  139. - "application/json"
  140. security:
  141. - jwt: []
  142. parameters: []
  143. responses:
  144. 200:
  145. description: "Success"
  146. schema:
  147. $ref: "#/definitions/DockerHubSubset"
  148. 500:
  149. description: "Server error"
  150. schema:
  151. $ref: "#/definitions/GenericError"
  152. put:
  153. tags:
  154. - "dockerhub"
  155. summary: "Update DockerHub information"
  156. description: |
  157. Use this endpoint to update the information used to connect to the DockerHub
  158. **Access policy**: administrator
  159. operationId: "DockerHubUpdate"
  160. consumes:
  161. - "application/json"
  162. produces:
  163. - "application/json"
  164. security:
  165. - jwt: []
  166. parameters:
  167. - in: "body"
  168. name: "body"
  169. description: "DockerHub information"
  170. required: true
  171. schema:
  172. $ref: "#/definitions/DockerHubUpdateRequest"
  173. responses:
  174. 200:
  175. description: "Success"
  176. schema:
  177. $ref: "#/definitions/DockerHub"
  178. 400:
  179. description: "Invalid request"
  180. schema:
  181. $ref: "#/definitions/GenericError"
  182. examples:
  183. application/json:
  184. err: "Invalid request data format"
  185. 500:
  186. description: "Server error"
  187. schema:
  188. $ref: "#/definitions/GenericError"
  189. /endpoints:
  190. get:
  191. tags:
  192. - "endpoints"
  193. summary: "List endpoints"
  194. description: |
  195. List all endpoints based on the current user authorizations. Will
  196. return all endpoints if using an administrator account otherwise it will
  197. only return authorized endpoints.
  198. **Access policy**: restricted
  199. operationId: "EndpointList"
  200. produces:
  201. - "application/json"
  202. security:
  203. - jwt: []
  204. parameters: []
  205. responses:
  206. 200:
  207. description: "Success"
  208. schema:
  209. $ref: "#/definitions/EndpointListResponse"
  210. 500:
  211. description: "Server error"
  212. schema:
  213. $ref: "#/definitions/GenericError"
  214. post:
  215. tags:
  216. - "endpoints"
  217. summary: "Create a new endpoint"
  218. description: |
  219. Create a new endpoint that will be used to manage a Docker environment.
  220. **Access policy**: administrator
  221. operationId: "EndpointCreate"
  222. consumes:
  223. - "multipart/form-data"
  224. produces:
  225. - "application/json"
  226. security:
  227. - jwt: []
  228. parameters:
  229. - name: "Name"
  230. in: "formData"
  231. type: "string"
  232. description: "Name that will be used to identify this endpoint (example: my-endpoint)"
  233. required: true
  234. - name: "EndpointType"
  235. in: "formData"
  236. type: "integer"
  237. description: "Environment type. Value must be one of: 1 (Docker environment), 2 (Agent environment), 3 (Azure environment) or 4 (Edge agent environment)"
  238. required: true
  239. - name: "URL"
  240. in: "formData"
  241. type: "string"
  242. description: "URL or IP address of a Docker host (example: docker.mydomain.tld:2375).\
  243. \ Defaults to local if not specified (Linux: /var/run/docker.sock, Windows: //./pipe/docker_engine)"
  244. - name: "PublicURL"
  245. in: "formData"
  246. type: "string"
  247. description: "URL or IP address where exposed containers will be reachable.\
  248. \ Defaults to URL if not specified (example: docker.mydomain.tld:2375)"
  249. - name: "GroupID"
  250. in: "formData"
  251. type: "string"
  252. description: "Endpoint group identifier. If not specified will default to 1 (unassigned)."
  253. - name: "TLS"
  254. in: "formData"
  255. type: "string"
  256. description: "Require TLS to connect against this endpoint (example: true)"
  257. - name: "TLSSkipVerify"
  258. in: "formData"
  259. type: "string"
  260. description: "Skip server verification when using TLS (example: false)"
  261. - name: "TLSSkipClientVerify"
  262. in: "formData"
  263. type: "string"
  264. description: "Skip client verification when using TLS (example: false)"
  265. - name: "TLSCACertFile"
  266. in: "formData"
  267. type: "file"
  268. description: "TLS CA certificate file"
  269. - name: "TLSCertFile"
  270. in: "formData"
  271. type: "file"
  272. description: "TLS client certificate file"
  273. - name: "TLSKeyFile"
  274. in: "formData"
  275. type: "file"
  276. description: "TLS client key file"
  277. - name: "AzureApplicationID"
  278. in: "formData"
  279. type: "string"
  280. description: "Azure application ID. Required if endpoint type is set to 3"
  281. - name: "AzureTenantID"
  282. in: "formData"
  283. type: "string"
  284. description: "Azure tenant ID. Required if endpoint type is set to 3"
  285. - name: "AzureAuthenticationKey"
  286. in: "formData"
  287. type: "string"
  288. description: "Azure authentication key. Required if endpoint type is set to 3"
  289. responses:
  290. 200:
  291. description: "Success"
  292. schema:
  293. $ref: "#/definitions/Endpoint"
  294. 400:
  295. description: "Invalid request"
  296. schema:
  297. $ref: "#/definitions/GenericError"
  298. examples:
  299. application/json:
  300. err: "Invalid request data format"
  301. 500:
  302. description: "Server error"
  303. schema:
  304. $ref: "#/definitions/GenericError"
  305. 503:
  306. description: "Endpoint management disabled"
  307. schema:
  308. $ref: "#/definitions/GenericError"
  309. examples:
  310. application/json:
  311. err: "Endpoint management is disabled"
  312. /endpoints/{id}:
  313. get:
  314. tags:
  315. - "endpoints"
  316. summary: "Inspect an endpoint"
  317. description: |
  318. Retrieve details abount an endpoint.
  319. **Access policy**: restricted
  320. operationId: "EndpointInspect"
  321. produces:
  322. - "application/json"
  323. security:
  324. - jwt: []
  325. parameters:
  326. - name: "id"
  327. in: "path"
  328. description: "Endpoint identifier"
  329. required: true
  330. type: "integer"
  331. responses:
  332. 200:
  333. description: "Success"
  334. schema:
  335. $ref: "#/definitions/Endpoint"
  336. 400:
  337. description: "Invalid request"
  338. schema:
  339. $ref: "#/definitions/GenericError"
  340. examples:
  341. application/json:
  342. err: "Invalid request"
  343. 404:
  344. description: "Endpoint not found"
  345. schema:
  346. $ref: "#/definitions/GenericError"
  347. examples:
  348. application/json:
  349. err: "Endpoint not found"
  350. 500:
  351. description: "Server error"
  352. schema:
  353. $ref: "#/definitions/GenericError"
  354. put:
  355. tags:
  356. - "endpoints"
  357. summary: "Update an endpoint"
  358. description: |
  359. Update an endpoint.
  360. **Access policy**: administrator
  361. operationId: "EndpointUpdate"
  362. consumes:
  363. - "application/json"
  364. produces:
  365. - "application/json"
  366. security:
  367. - jwt: []
  368. parameters:
  369. - name: "id"
  370. in: "path"
  371. description: "Endpoint identifier"
  372. required: true
  373. type: "integer"
  374. - in: "body"
  375. name: "body"
  376. description: "Endpoint details"
  377. required: true
  378. schema:
  379. $ref: "#/definitions/EndpointUpdateRequest"
  380. responses:
  381. 200:
  382. description: "Success"
  383. 400:
  384. description: "Invalid request"
  385. schema:
  386. $ref: "#/definitions/GenericError"
  387. examples:
  388. application/json:
  389. err: "Invalid request data format"
  390. 404:
  391. description: "Endpoint not found"
  392. schema:
  393. $ref: "#/definitions/GenericError"
  394. examples:
  395. application/json:
  396. err: "Endpoint not found"
  397. 500:
  398. description: "Server error"
  399. schema:
  400. $ref: "#/definitions/GenericError"
  401. 503:
  402. description: "Endpoint management disabled"
  403. schema:
  404. $ref: "#/definitions/GenericError"
  405. examples:
  406. application/json:
  407. err: "Endpoint management is disabled"
  408. delete:
  409. tags:
  410. - "endpoints"
  411. summary: "Remove an endpoint"
  412. description: |
  413. Remove an endpoint.
  414. **Access policy**: administrator
  415. operationId: "EndpointDelete"
  416. security:
  417. - jwt: []
  418. parameters:
  419. - name: "id"
  420. in: "path"
  421. description: "Endpoint identifier"
  422. required: true
  423. type: "integer"
  424. responses:
  425. 204:
  426. description: "Success"
  427. 400:
  428. description: "Invalid request"
  429. schema:
  430. $ref: "#/definitions/GenericError"
  431. examples:
  432. application/json:
  433. err: "Invalid request"
  434. 404:
  435. description: "Endpoint not found"
  436. schema:
  437. $ref: "#/definitions/GenericError"
  438. examples:
  439. application/json:
  440. err: "Endpoint not found"
  441. 500:
  442. description: "Server error"
  443. schema:
  444. $ref: "#/definitions/GenericError"
  445. 503:
  446. description: "Endpoint management disabled"
  447. schema:
  448. $ref: "#/definitions/GenericError"
  449. examples:
  450. application/json:
  451. err: "Endpoint management is disabled"
  452. /endpoints/{id}/job:
  453. post:
  454. tags:
  455. - "endpoints"
  456. summary: "Execute a job on the endpoint host"
  457. description: |
  458. Execute a job (script) on the underlying host of the endpoint.
  459. **Access policy**: administrator
  460. operationId: "EndpointJob"
  461. consumes:
  462. - "multipart/form-data"
  463. produces:
  464. - "application/json"
  465. security:
  466. - jwt: []
  467. parameters:
  468. - name: "id"
  469. in: "path"
  470. description: "Endpoint identifier"
  471. required: true
  472. type: "integer"
  473. - name: "method"
  474. in: "query"
  475. description: "Job execution method. Possible values: file or string."
  476. required: true
  477. type: "string"
  478. - name: "nodeName"
  479. in: "query"
  480. description: "Optional. Hostname of a node when targeting a Portainer agent cluster."
  481. required: true
  482. type: "string"
  483. - in: "body"
  484. name: "body"
  485. description: "Job details. Required when method equals string."
  486. required: true
  487. schema:
  488. $ref: "#/definitions/EndpointJobRequest"
  489. - name: "Image"
  490. in: "formData"
  491. type: "string"
  492. description: "Container image which will be used to execute the job. Required when method equals file."
  493. - name: "file"
  494. in: "formData"
  495. type: "file"
  496. description: "Job script file. Required when method equals file."
  497. responses:
  498. 200:
  499. description: "Success"
  500. schema:
  501. $ref: "#/definitions/Endpoint"
  502. 400:
  503. description: "Invalid request"
  504. schema:
  505. $ref: "#/definitions/GenericError"
  506. examples:
  507. application/json:
  508. err: "Invalid request data format"
  509. 403:
  510. description: "Unauthorized"
  511. schema:
  512. $ref: "#/definitions/GenericError"
  513. 404:
  514. description: "Endpoint not found"
  515. schema:
  516. $ref: "#/definitions/GenericError"
  517. examples:
  518. application/json:
  519. err: "Endpoint not found"
  520. 500:
  521. description: "Server error"
  522. schema:
  523. $ref: "#/definitions/GenericError"
  524. /endpoint_groups:
  525. get:
  526. tags:
  527. - "endpoint_groups"
  528. summary: "List endpoint groups"
  529. description: |
  530. List all endpoint groups based on the current user authorizations. Will
  531. return all endpoint groups if using an administrator account otherwise it will
  532. only return authorized endpoint groups.
  533. **Access policy**: restricted
  534. operationId: "EndpointGroupList"
  535. produces:
  536. - "application/json"
  537. security:
  538. - jwt: []
  539. parameters: []
  540. responses:
  541. 200:
  542. description: "Success"
  543. schema:
  544. $ref: "#/definitions/EndpointGroupListResponse"
  545. 500:
  546. description: "Server error"
  547. schema:
  548. $ref: "#/definitions/GenericError"
  549. post:
  550. tags:
  551. - "endpoint_groups"
  552. summary: "Create a new endpoint"
  553. description: |
  554. Create a new endpoint group.
  555. **Access policy**: administrator
  556. operationId: "EndpointGroupCreate"
  557. consumes:
  558. - "application/json"
  559. produces:
  560. - "application/json"
  561. security:
  562. - jwt: []
  563. parameters:
  564. - in: "body"
  565. name: "body"
  566. description: "Registry details"
  567. required: true
  568. schema:
  569. $ref: "#/definitions/EndpointGroupCreateRequest"
  570. responses:
  571. 200:
  572. description: "Success"
  573. schema:
  574. $ref: "#/definitions/EndpointGroup"
  575. 400:
  576. description: "Invalid request"
  577. schema:
  578. $ref: "#/definitions/GenericError"
  579. examples:
  580. application/json:
  581. err: "Invalid request data format"
  582. 500:
  583. description: "Server error"
  584. schema:
  585. $ref: "#/definitions/GenericError"
  586. /endpoint_groups/{id}:
  587. get:
  588. tags:
  589. - "endpoint_groups"
  590. summary: "Inspect an endpoint group"
  591. description: |
  592. Retrieve details abount an endpoint group.
  593. **Access policy**: administrator
  594. operationId: "EndpointGroupInspect"
  595. produces:
  596. - "application/json"
  597. security:
  598. - jwt: []
  599. parameters:
  600. - name: "id"
  601. in: "path"
  602. description: "Endpoint group identifier"
  603. required: true
  604. type: "integer"
  605. responses:
  606. 200:
  607. description: "Success"
  608. schema:
  609. $ref: "#/definitions/EndpointGroup"
  610. 400:
  611. description: "Invalid request"
  612. schema:
  613. $ref: "#/definitions/GenericError"
  614. examples:
  615. application/json:
  616. err: "Invalid request"
  617. 404:
  618. description: "EndpointGroup not found"
  619. schema:
  620. $ref: "#/definitions/GenericError"
  621. examples:
  622. application/json:
  623. err: "EndpointGroup not found"
  624. 500:
  625. description: "Server error"
  626. schema:
  627. $ref: "#/definitions/GenericError"
  628. put:
  629. tags:
  630. - "endpoint_groups"
  631. summary: "Update an endpoint group"
  632. description: |
  633. Update an endpoint group.
  634. **Access policy**: administrator
  635. operationId: "EndpointGroupUpdate"
  636. consumes:
  637. - "application/json"
  638. produces:
  639. - "application/json"
  640. security:
  641. - jwt: []
  642. parameters:
  643. - name: "id"
  644. in: "path"
  645. description: "EndpointGroup identifier"
  646. required: true
  647. type: "integer"
  648. - in: "body"
  649. name: "body"
  650. description: "EndpointGroup details"
  651. required: true
  652. schema:
  653. $ref: "#/definitions/EndpointGroupUpdateRequest"
  654. responses:
  655. 200:
  656. description: "Success"
  657. schema:
  658. $ref: "#/definitions/EndpointGroup"
  659. 400:
  660. description: "Invalid request"
  661. schema:
  662. $ref: "#/definitions/GenericError"
  663. examples:
  664. application/json:
  665. err: "Invalid request data format"
  666. 404:
  667. description: "EndpointGroup not found"
  668. schema:
  669. $ref: "#/definitions/GenericError"
  670. examples:
  671. application/json:
  672. err: "EndpointGroup not found"
  673. 500:
  674. description: "Server error"
  675. schema:
  676. $ref: "#/definitions/GenericError"
  677. 503:
  678. description: "EndpointGroup management disabled"
  679. schema:
  680. $ref: "#/definitions/GenericError"
  681. examples:
  682. application/json:
  683. err: "EndpointGroup management is disabled"
  684. delete:
  685. tags:
  686. - "endpoint_groups"
  687. summary: "Remove an endpoint group"
  688. description: |
  689. Remove an endpoint group.
  690. **Access policy**: administrator
  691. operationId: "EndpointGroupDelete"
  692. security:
  693. - jwt: []
  694. parameters:
  695. - name: "id"
  696. in: "path"
  697. description: "EndpointGroup identifier"
  698. required: true
  699. type: "integer"
  700. responses:
  701. 204:
  702. description: "Success"
  703. 400:
  704. description: "Invalid request"
  705. schema:
  706. $ref: "#/definitions/GenericError"
  707. examples:
  708. application/json:
  709. err: "Invalid request"
  710. 404:
  711. description: "EndpointGroup not found"
  712. schema:
  713. $ref: "#/definitions/GenericError"
  714. examples:
  715. application/json:
  716. err: "EndpointGroup not found"
  717. 500:
  718. description: "Server error"
  719. schema:
  720. $ref: "#/definitions/GenericError"
  721. 503:
  722. description: "EndpointGroup management disabled"
  723. schema:
  724. $ref: "#/definitions/GenericError"
  725. examples:
  726. application/json:
  727. err: "EndpointGroup management is disabled"
  728. /endpoint_groups/{id}/endpoints/{endpointId}:
  729. put:
  730. tags:
  731. - "endpoint_groups"
  732. summary: "Add an endpoint to an endpoint group"
  733. description: |
  734. Add an endpoint to an endpoint group
  735. **Access policy**: administrator
  736. operationId: "EndpointGroupAddEndpoint"
  737. consumes:
  738. - "application/json"
  739. produces:
  740. - "application/json"
  741. security:
  742. - jwt: []
  743. parameters:
  744. - name: "id"
  745. in: "path"
  746. description: "EndpointGroup identifier"
  747. required: true
  748. type: "integer"
  749. - name: "endpointId"
  750. in: "path"
  751. description: "Endpoint identifier"
  752. required: true
  753. type: "integer"
  754. responses:
  755. 204:
  756. description: "Success"
  757. 400:
  758. description: "Invalid request"
  759. schema:
  760. $ref: "#/definitions/GenericError"
  761. examples:
  762. application/json:
  763. err: "Invalid request data format"
  764. 404:
  765. description: "EndpointGroup not found"
  766. schema:
  767. $ref: "#/definitions/GenericError"
  768. examples:
  769. application/json:
  770. err: "EndpointGroup not found"
  771. 500:
  772. description: "Server error"
  773. schema:
  774. $ref: "#/definitions/GenericError"
  775. delete:
  776. tags:
  777. - "endpoint_groups"
  778. summary: "Remove an endpoint group"
  779. description: |
  780. Remove an endpoint group.
  781. **Access policy**: administrator
  782. operationId: "EndpointGroupDeleteEndpoint"
  783. security:
  784. - jwt: []
  785. parameters:
  786. - name: "id"
  787. in: "path"
  788. description: "EndpointGroup identifier"
  789. required: true
  790. type: "integer"
  791. - name: "endpointId"
  792. in: "path"
  793. description: "Endpoint identifier"
  794. required: true
  795. type: "integer"
  796. responses:
  797. 204:
  798. description: "Success"
  799. 400:
  800. description: "Invalid request"
  801. schema:
  802. $ref: "#/definitions/GenericError"
  803. examples:
  804. application/json:
  805. err: "Invalid request"
  806. 404:
  807. description: "EndpointGroup not found"
  808. schema:
  809. $ref: "#/definitions/GenericError"
  810. examples:
  811. application/json:
  812. err: "EndpointGroup not found"
  813. 500:
  814. description: "Server error"
  815. schema:
  816. $ref: "#/definitions/GenericError"
  817. /extensions:
  818. get:
  819. tags:
  820. - "extensions"
  821. summary: "List extensions"
  822. description: |
  823. List all extensions registered inside Portainer. If the store parameter is set to true,
  824. will retrieve extensions details from the online repository.
  825. **Access policy**: administrator
  826. operationId: "ExtensionList"
  827. produces:
  828. - "application/json"
  829. security:
  830. - jwt: []
  831. parameters:
  832. - name: "store"
  833. in: "query"
  834. description: "Retrieve online information about extensions. Possible values: true or false."
  835. required: false
  836. type: "boolean"
  837. responses:
  838. 200:
  839. description: "Success"
  840. schema:
  841. $ref: "#/definitions/ExtensionListResponse"
  842. 500:
  843. description: "Server error"
  844. schema:
  845. $ref: "#/definitions/GenericError"
  846. post:
  847. tags:
  848. - "extensions"
  849. summary: "Enable an extension"
  850. description: |
  851. Enable an extension.
  852. **Access policy**: administrator
  853. operationId: "ExtensionCreate"
  854. consumes:
  855. - "application/json"
  856. produces:
  857. - "application/json"
  858. security:
  859. - jwt: []
  860. parameters:
  861. - in: "body"
  862. name: "body"
  863. description: "Extension details"
  864. required: true
  865. schema:
  866. $ref: "#/definitions/ExtensionCreateRequest"
  867. responses:
  868. 204:
  869. description: "Success"
  870. 400:
  871. description: "Invalid request"
  872. schema:
  873. $ref: "#/definitions/GenericError"
  874. examples:
  875. application/json:
  876. err: "Invalid request data format"
  877. 500:
  878. description: "Server error"
  879. schema:
  880. $ref: "#/definitions/GenericError"
  881. /extensions/{id}:
  882. get:
  883. tags:
  884. - "extensions"
  885. summary: "Inspect an extension"
  886. description: |
  887. Retrieve details abount an extension.
  888. **Access policy**: administrator
  889. operationId: "ExtensionInspect"
  890. produces:
  891. - "application/json"
  892. security:
  893. - jwt: []
  894. parameters:
  895. - name: "id"
  896. in: "path"
  897. description: "extension identifier"
  898. required: true
  899. type: "integer"
  900. responses:
  901. 200:
  902. description: "Success"
  903. schema:
  904. $ref: "#/definitions/Extension"
  905. 400:
  906. description: "Invalid request"
  907. schema:
  908. $ref: "#/definitions/GenericError"
  909. examples:
  910. application/json:
  911. err: "Invalid request"
  912. 404:
  913. description: "Extension not found"
  914. schema:
  915. $ref: "#/definitions/GenericError"
  916. examples:
  917. application/json:
  918. err: "Extension not found"
  919. 500:
  920. description: "Server error"
  921. schema:
  922. $ref: "#/definitions/GenericError"
  923. put:
  924. tags:
  925. - "extensions"
  926. summary: "Update an extension"
  927. description: |
  928. Update an extension to a specific version of the extension.
  929. **Access policy**: administrator
  930. operationId: "ExtensionUpdate"
  931. consumes:
  932. - "application/json"
  933. produces:
  934. - "application/json"
  935. security:
  936. - jwt: []
  937. parameters:
  938. - name: "id"
  939. in: "path"
  940. description: "Extension identifier"
  941. required: true
  942. type: "integer"
  943. - in: "body"
  944. name: "body"
  945. description: "Extension details"
  946. required: true
  947. schema:
  948. $ref: "#/definitions/ExtensionUpdateRequest"
  949. responses:
  950. 204:
  951. description: "Success"
  952. 400:
  953. description: "Invalid request"
  954. schema:
  955. $ref: "#/definitions/GenericError"
  956. examples:
  957. application/json:
  958. err: "Invalid request data format"
  959. 404:
  960. description: "Extension not found"
  961. schema:
  962. $ref: "#/definitions/GenericError"
  963. examples:
  964. application/json:
  965. err: "Extension not found"
  966. 500:
  967. description: "Server error"
  968. schema:
  969. $ref: "#/definitions/GenericError"
  970. delete:
  971. tags:
  972. - "extensions"
  973. summary: "Disable an extension"
  974. description: |
  975. Disable an extension.
  976. **Access policy**: administrator
  977. operationId: "ExtensionDelete"
  978. security:
  979. - jwt: []
  980. parameters:
  981. - name: "id"
  982. in: "path"
  983. description: "Extension identifier"
  984. required: true
  985. type: "integer"
  986. responses:
  987. 204:
  988. description: "Success"
  989. 400:
  990. description: "Invalid request"
  991. schema:
  992. $ref: "#/definitions/GenericError"
  993. examples:
  994. application/json:
  995. err: "Invalid request"
  996. 404:
  997. description: "Extension not found"
  998. schema:
  999. $ref: "#/definitions/GenericError"
  1000. examples:
  1001. application/json:
  1002. err: "Extension not found"
  1003. 500:
  1004. description: "Server error"
  1005. schema:
  1006. $ref: "#/definitions/GenericError"
  1007. /registries:
  1008. get:
  1009. tags:
  1010. - "registries"
  1011. summary: "List registries"
  1012. description: |
  1013. List all registries based on the current user authorizations.
  1014. Will return all registries if using an administrator account otherwise it
  1015. will only return authorized registries.
  1016. **Access policy**: restricted
  1017. operationId: "RegistryList"
  1018. produces:
  1019. - "application/json"
  1020. security:
  1021. - jwt: []
  1022. parameters: []
  1023. responses:
  1024. 200:
  1025. description: "Success"
  1026. schema:
  1027. $ref: "#/definitions/RegistryListResponse"
  1028. 500:
  1029. description: "Server error"
  1030. schema:
  1031. $ref: "#/definitions/GenericError"
  1032. post:
  1033. tags:
  1034. - "registries"
  1035. summary: "Create a new registry"
  1036. description: |
  1037. Create a new registry.
  1038. **Access policy**: administrator
  1039. operationId: "RegistryCreate"
  1040. consumes:
  1041. - "application/json"
  1042. produces:
  1043. - "application/json"
  1044. security:
  1045. - jwt: []
  1046. parameters:
  1047. - in: "body"
  1048. name: "body"
  1049. description: "Registry details"
  1050. required: true
  1051. schema:
  1052. $ref: "#/definitions/RegistryCreateRequest"
  1053. responses:
  1054. 200:
  1055. description: "Success"
  1056. schema:
  1057. $ref: "#/definitions/Registry"
  1058. 400:
  1059. description: "Invalid request"
  1060. schema:
  1061. $ref: "#/definitions/GenericError"
  1062. examples:
  1063. application/json:
  1064. err: "Invalid request data format"
  1065. 409:
  1066. description: "Registry already exists"
  1067. schema:
  1068. $ref: "#/definitions/GenericError"
  1069. examples:
  1070. application/json:
  1071. err: "A registry is already defined for this URL"
  1072. 500:
  1073. description: "Server error"
  1074. schema:
  1075. $ref: "#/definitions/GenericError"
  1076. /registries/{id}:
  1077. get:
  1078. tags:
  1079. - "registries"
  1080. summary: "Inspect a registry"
  1081. description: |
  1082. Retrieve details about a registry.
  1083. **Access policy**: administrator
  1084. operationId: "RegistryInspect"
  1085. produces:
  1086. - "application/json"
  1087. security:
  1088. - jwt: []
  1089. parameters:
  1090. - name: "id"
  1091. in: "path"
  1092. description: "Registry identifier"
  1093. required: true
  1094. type: "integer"
  1095. responses:
  1096. 200:
  1097. description: "Success"
  1098. schema:
  1099. $ref: "#/definitions/Registry"
  1100. 400:
  1101. description: "Invalid request"
  1102. schema:
  1103. $ref: "#/definitions/GenericError"
  1104. examples:
  1105. application/json:
  1106. err: "Invalid request"
  1107. 404:
  1108. description: "Registry not found"
  1109. schema:
  1110. $ref: "#/definitions/GenericError"
  1111. examples:
  1112. application/json:
  1113. err: "Registry not found"
  1114. 500:
  1115. description: "Server error"
  1116. schema:
  1117. $ref: "#/definitions/GenericError"
  1118. put:
  1119. tags:
  1120. - "registries"
  1121. summary: "Update a registry"
  1122. description: |
  1123. Update a registry.
  1124. **Access policy**: administrator
  1125. operationId: "RegistryUpdate"
  1126. consumes:
  1127. - "application/json"
  1128. produces:
  1129. - "application/json"
  1130. security:
  1131. - jwt: []
  1132. parameters:
  1133. - name: "id"
  1134. in: "path"
  1135. description: "Registry identifier"
  1136. required: true
  1137. type: "integer"
  1138. - in: "body"
  1139. name: "body"
  1140. description: "Registry details"
  1141. required: true
  1142. schema:
  1143. $ref: "#/definitions/RegistryUpdateRequest"
  1144. responses:
  1145. 200:
  1146. description: "Success"
  1147. schema:
  1148. $ref: "#/definitions/Registry"
  1149. 400:
  1150. description: "Invalid request"
  1151. schema:
  1152. $ref: "#/definitions/GenericError"
  1153. examples:
  1154. application/json:
  1155. err: "Invalid request data format"
  1156. 404:
  1157. description: "Registry not found"
  1158. schema:
  1159. $ref: "#/definitions/GenericError"
  1160. examples:
  1161. application/json:
  1162. err: "Endpoint not found"
  1163. 409:
  1164. description: "Registry already exists"
  1165. schema:
  1166. $ref: "#/definitions/GenericError"
  1167. examples:
  1168. application/json:
  1169. err: "A registry is already defined for this URL"
  1170. 500:
  1171. description: "Server error"
  1172. schema:
  1173. $ref: "#/definitions/GenericError"
  1174. delete:
  1175. tags:
  1176. - "registries"
  1177. summary: "Remove a registry"
  1178. description: |
  1179. Remove a registry.
  1180. **Access policy**: administrator
  1181. operationId: "RegistryDelete"
  1182. security:
  1183. - jwt: []
  1184. parameters:
  1185. - name: "id"
  1186. in: "path"
  1187. description: "Registry identifier"
  1188. required: true
  1189. type: "integer"
  1190. responses:
  1191. 204:
  1192. description: "Success"
  1193. 400:
  1194. description: "Invalid request"
  1195. schema:
  1196. $ref: "#/definitions/GenericError"
  1197. examples:
  1198. application/json:
  1199. err: "Invalid request"
  1200. 404:
  1201. description: "Registry not found"
  1202. schema:
  1203. $ref: "#/definitions/GenericError"
  1204. examples:
  1205. application/json:
  1206. err: "Registry not found"
  1207. 500:
  1208. description: "Server error"
  1209. schema:
  1210. $ref: "#/definitions/GenericError"
  1211. /resource_controls:
  1212. post:
  1213. tags:
  1214. - "resource_controls"
  1215. summary: "Create a new resource control"
  1216. description: |
  1217. Create a new resource control to restrict access to a Docker resource.
  1218. **Access policy**: administrator
  1219. operationId: "ResourceControlCreate"
  1220. consumes:
  1221. - "application/json"
  1222. produces:
  1223. - "application/json"
  1224. security:
  1225. - jwt: []
  1226. parameters:
  1227. - in: "body"
  1228. name: "body"
  1229. description: "Resource control details"
  1230. required: true
  1231. schema:
  1232. $ref: "#/definitions/ResourceControlCreateRequest"
  1233. responses:
  1234. 200:
  1235. description: "Success"
  1236. schema:
  1237. $ref: "#/definitions/ResourceControl"
  1238. 400:
  1239. description: "Invalid request"
  1240. schema:
  1241. $ref: "#/definitions/GenericError"
  1242. examples:
  1243. application/json:
  1244. err: "Invalid request data format"
  1245. 403:
  1246. description: "Unauthorized"
  1247. schema:
  1248. $ref: "#/definitions/GenericError"
  1249. examples:
  1250. application/json:
  1251. err: "Access denied to resource"
  1252. 409:
  1253. description: "Resource control already exists"
  1254. schema:
  1255. $ref: "#/definitions/GenericError"
  1256. examples:
  1257. application/json:
  1258. err: "A resource control is already applied on this resource"
  1259. 500:
  1260. description: "Server error"
  1261. schema:
  1262. $ref: "#/definitions/GenericError"
  1263. /resource_controls/{id}:
  1264. put:
  1265. tags:
  1266. - "resource_controls"
  1267. summary: "Update a resource control"
  1268. description: |
  1269. Update a resource control.
  1270. **Access policy**: restricted
  1271. operationId: "ResourceControlUpdate"
  1272. consumes:
  1273. - "application/json"
  1274. produces:
  1275. - "application/json"
  1276. security:
  1277. - jwt: []
  1278. parameters:
  1279. - name: "id"
  1280. in: "path"
  1281. description: "Resource control identifier"
  1282. required: true
  1283. type: "integer"
  1284. - in: "body"
  1285. name: "body"
  1286. description: "Resource control details"
  1287. required: true
  1288. schema:
  1289. $ref: "#/definitions/ResourceControlUpdateRequest"
  1290. responses:
  1291. 200:
  1292. description: "Success"
  1293. schema:
  1294. $ref: "#/definitions/ResourceControl"
  1295. 400:
  1296. description: "Invalid request"
  1297. schema:
  1298. $ref: "#/definitions/GenericError"
  1299. examples:
  1300. application/json:
  1301. err: "Invalid request data format"
  1302. 403:
  1303. description: "Unauthorized"
  1304. schema:
  1305. $ref: "#/definitions/GenericError"
  1306. examples:
  1307. application/json:
  1308. err: "Access denied to resource"
  1309. 404:
  1310. description: "Resource control not found"
  1311. schema:
  1312. $ref: "#/definitions/GenericError"
  1313. examples:
  1314. application/json:
  1315. err: "Resource control not found"
  1316. 500:
  1317. description: "Server error"
  1318. schema:
  1319. $ref: "#/definitions/GenericError"
  1320. delete:
  1321. tags:
  1322. - "resource_controls"
  1323. summary: "Remove a resource control"
  1324. description: |
  1325. Remove a resource control.
  1326. **Access policy**: administrator
  1327. operationId: "ResourceControlDelete"
  1328. security:
  1329. - jwt: []
  1330. parameters:
  1331. - name: "id"
  1332. in: "path"
  1333. description: "Resource control identifier"
  1334. required: true
  1335. type: "integer"
  1336. responses:
  1337. 204:
  1338. description: "Success"
  1339. 400:
  1340. description: "Invalid request"
  1341. schema:
  1342. $ref: "#/definitions/GenericError"
  1343. examples:
  1344. application/json:
  1345. err: "Invalid request"
  1346. 403:
  1347. description: "Unauthorized"
  1348. schema:
  1349. $ref: "#/definitions/GenericError"
  1350. examples:
  1351. application/json:
  1352. err: "Access denied to resource"
  1353. 404:
  1354. description: "Resource control not found"
  1355. schema:
  1356. $ref: "#/definitions/GenericError"
  1357. examples:
  1358. application/json:
  1359. err: "Resource control not found"
  1360. 500:
  1361. description: "Server error"
  1362. schema:
  1363. $ref: "#/definitions/GenericError"
  1364. /roles:
  1365. get:
  1366. tags:
  1367. - "roles"
  1368. summary: "List roles"
  1369. description: |
  1370. List all roles available for use with the RBAC extension.
  1371. **Access policy**: administrator
  1372. operationId: "RoleList"
  1373. produces:
  1374. - "application/json"
  1375. security:
  1376. - jwt: []
  1377. parameters: []
  1378. responses:
  1379. 200:
  1380. description: "Success"
  1381. schema:
  1382. $ref: "#/definitions/RoleListResponse"
  1383. 500:
  1384. description: "Server error"
  1385. schema:
  1386. $ref: "#/definitions/GenericError"
  1387. /settings:
  1388. get:
  1389. tags:
  1390. - "settings"
  1391. summary: "Retrieve Portainer settings"
  1392. description: |
  1393. Retrieve Portainer settings.
  1394. **Access policy**: administrator
  1395. operationId: "SettingsInspect"
  1396. produces:
  1397. - "application/json"
  1398. security:
  1399. - jwt: []
  1400. parameters: []
  1401. responses:
  1402. 200:
  1403. description: "Success"
  1404. schema:
  1405. $ref: "#/definitions/Settings"
  1406. 500:
  1407. description: "Server error"
  1408. schema:
  1409. $ref: "#/definitions/GenericError"
  1410. put:
  1411. tags:
  1412. - "settings"
  1413. summary: "Update Portainer settings"
  1414. description: |
  1415. Update Portainer settings.
  1416. **Access policy**: administrator
  1417. operationId: "SettingsUpdate"
  1418. consumes:
  1419. - "application/json"
  1420. produces:
  1421. - "application/json"
  1422. security:
  1423. - jwt: []
  1424. parameters:
  1425. - in: "body"
  1426. name: "body"
  1427. description: "New settings"
  1428. required: true
  1429. schema:
  1430. $ref: "#/definitions/SettingsUpdateRequest"
  1431. responses:
  1432. 200:
  1433. description: "Success"
  1434. schema:
  1435. $ref: "#/definitions/Settings"
  1436. 400:
  1437. description: "Invalid request"
  1438. schema:
  1439. $ref: "#/definitions/GenericError"
  1440. examples:
  1441. application/json:
  1442. err: "Invalid request data format"
  1443. 500:
  1444. description: "Server error"
  1445. schema:
  1446. $ref: "#/definitions/GenericError"
  1447. /settings/public:
  1448. get:
  1449. tags:
  1450. - "settings"
  1451. summary: "Retrieve Portainer public settings"
  1452. description: |
  1453. Retrieve public settings. Returns a small set of settings that are not reserved to administrators only.
  1454. **Access policy**: public
  1455. operationId: "PublicSettingsInspect"
  1456. produces:
  1457. - "application/json"
  1458. security:
  1459. - jwt: []
  1460. parameters: []
  1461. responses:
  1462. 200:
  1463. description: "Success"
  1464. schema:
  1465. $ref: "#/definitions/PublicSettingsInspectResponse"
  1466. 500:
  1467. description: "Server error"
  1468. schema:
  1469. $ref: "#/definitions/GenericError"
  1470. /settings/authentication/checkLDAP:
  1471. put:
  1472. tags:
  1473. - "settings"
  1474. summary: "Test LDAP connectivity"
  1475. description: |
  1476. Test LDAP connectivity using LDAP details.
  1477. **Access policy**: administrator
  1478. operationId: "SettingsLDAPCheck"
  1479. consumes:
  1480. - "application/json"
  1481. produces:
  1482. - "application/json"
  1483. security:
  1484. - jwt: []
  1485. parameters:
  1486. - in: "body"
  1487. name: "body"
  1488. description: "LDAP settings"
  1489. required: true
  1490. schema:
  1491. $ref: "#/definitions/SettingsLDAPCheckRequest"
  1492. responses:
  1493. 204:
  1494. description: "Success"
  1495. 400:
  1496. description: "Invalid request"
  1497. schema:
  1498. $ref: "#/definitions/GenericError"
  1499. examples:
  1500. application/json:
  1501. err: "Invalid request data format"
  1502. 500:
  1503. description: "Server error"
  1504. schema:
  1505. $ref: "#/definitions/GenericError"
  1506. /status:
  1507. get:
  1508. tags:
  1509. - "status"
  1510. summary: "Check Portainer status"
  1511. description: |
  1512. Retrieve Portainer status.
  1513. **Access policy**: public
  1514. operationId: "StatusInspect"
  1515. produces:
  1516. - "application/json"
  1517. security:
  1518. - jwt: []
  1519. parameters: []
  1520. responses:
  1521. 200:
  1522. description: "Success"
  1523. schema:
  1524. $ref: "#/definitions/Status"
  1525. 500:
  1526. description: "Server error"
  1527. schema:
  1528. $ref: "#/definitions/GenericError"
  1529. /stacks:
  1530. get:
  1531. tags:
  1532. - "stacks"
  1533. summary: "List stacks"
  1534. description: |
  1535. List all stacks based on the current user authorizations.
  1536. Will return all stacks if using an administrator account otherwise it
  1537. will only return the list of stacks the user have access to.
  1538. **Access policy**: restricted
  1539. operationId: "StackList"
  1540. produces:
  1541. - "application/json"
  1542. security:
  1543. - jwt: []
  1544. parameters:
  1545. - name: "filters"
  1546. in: "query"
  1547. description: |
  1548. Filters to process on the stack list. Encoded as JSON (a map[string]string).
  1549. For example, {"SwarmID": "jpofkc0i9uo9wtx1zesuk649w"} will only return stacks that are part
  1550. of the specified Swarm cluster. Available filters: EndpointID, SwarmID.
  1551. type: "string"
  1552. responses:
  1553. 200:
  1554. description: "Success"
  1555. schema:
  1556. $ref: "#/definitions/StackListResponse"
  1557. examples:
  1558. application/json:
  1559. err: "Access denied to resource"
  1560. 500:
  1561. description: "Server error"
  1562. schema:
  1563. $ref: "#/definitions/GenericError"
  1564. post:
  1565. tags:
  1566. - "stacks"
  1567. summary: "Deploy a new stack"
  1568. description: |
  1569. Deploy a new stack into a Docker environment specified via the endpoint identifier.
  1570. **Access policy**: restricted
  1571. operationId: "StackCreate"
  1572. consumes:
  1573. - "multipart/form-data"
  1574. produces:
  1575. - "application/json"
  1576. security:
  1577. - jwt: []
  1578. parameters:
  1579. - name: "type"
  1580. in: "query"
  1581. description: "Stack deployment type. Possible values: 1 (Swarm stack) or 2 (Compose stack)."
  1582. required: true
  1583. type: "integer"
  1584. - name: "method"
  1585. in: "query"
  1586. description: "Stack deployment method. Possible values: file, string or repository."
  1587. required: true
  1588. type: "string"
  1589. - name: "endpointId"
  1590. in: "query"
  1591. description: "Identifier of the endpoint that will be used to deploy the stack."
  1592. required: true
  1593. type: "integer"
  1594. - in: "body"
  1595. name: "body"
  1596. description: "Stack details. Required when method equals string or repository."
  1597. schema:
  1598. $ref: "#/definitions/StackCreateRequest"
  1599. - name: "Name"
  1600. in: "formData"
  1601. type: "string"
  1602. description: "Name of the stack. Required when method equals file."
  1603. - name: "EndpointID"
  1604. in: "formData"
  1605. type: "string"
  1606. description: "Endpoint identifier used to deploy the stack. Required when method equals file."
  1607. - name: "SwarmID"
  1608. in: "formData"
  1609. type: "string"
  1610. description: "Swarm cluster identifier. Required when method equals file and type equals 1."
  1611. - name: "file"
  1612. in: "formData"
  1613. type: "file"
  1614. description: "Stack file. Required when method equals file."
  1615. - name: "Env"
  1616. in: "formData"
  1617. type: "string"
  1618. description: "Environment variables passed during deployment, represented as a JSON array [{'name': 'name', 'value': 'value'}]. Optional, used when method equals file and type equals 1."
  1619. responses:
  1620. 200:
  1621. description: "Success"
  1622. schema:
  1623. $ref: "#/definitions/Stack"
  1624. 400:
  1625. description: "Invalid request"
  1626. schema:
  1627. $ref: "#/definitions/GenericError"
  1628. examples:
  1629. application/json:
  1630. err: "Invalid request data format"
  1631. 403:
  1632. description: "Unauthorized"
  1633. schema:
  1634. $ref: "#/definitions/GenericError"
  1635. 404:
  1636. description: "Endpoint not found"
  1637. schema:
  1638. $ref: "#/definitions/GenericError"
  1639. examples:
  1640. application/json:
  1641. err: "Endpoint not found"
  1642. 500:
  1643. description: "Server error"
  1644. schema:
  1645. $ref: "#/definitions/GenericError"
  1646. /stacks/{id}:
  1647. get:
  1648. tags:
  1649. - "stacks"
  1650. summary: "Inspect a stack"
  1651. description: |
  1652. Retrieve details about a stack.
  1653. **Access policy**: restricted
  1654. operationId: "StackInspect"
  1655. produces:
  1656. - "application/json"
  1657. security:
  1658. - jwt: []
  1659. parameters:
  1660. - name: "id"
  1661. in: "path"
  1662. description: "Stack identifier"
  1663. required: true
  1664. type: "integer"
  1665. responses:
  1666. 200:
  1667. description: "Success"
  1668. schema:
  1669. $ref: "#/definitions/Stack"
  1670. 400:
  1671. description: "Invalid request"
  1672. schema:
  1673. $ref: "#/definitions/GenericError"
  1674. examples:
  1675. application/json:
  1676. err: "Invalid request"
  1677. 403:
  1678. description: "Unauthorized"
  1679. schema:
  1680. $ref: "#/definitions/GenericError"
  1681. 404:
  1682. description: "Stack not found"
  1683. schema:
  1684. $ref: "#/definitions/GenericError"
  1685. examples:
  1686. application/json:
  1687. err: "Stack not found"
  1688. 500:
  1689. description: "Server error"
  1690. schema:
  1691. $ref: "#/definitions/GenericError"
  1692. put:
  1693. tags:
  1694. - "stacks"
  1695. summary: "Update a stack"
  1696. description: |
  1697. Update a stack.
  1698. **Access policy**: restricted
  1699. operationId: "StackUpdate"
  1700. consumes:
  1701. - "application/json"
  1702. produces:
  1703. - "application/json"
  1704. security:
  1705. - jwt: []
  1706. parameters:
  1707. - name: "id"
  1708. in: "path"
  1709. description: "Stack identifier"
  1710. required: true
  1711. type: "integer"
  1712. - name: "endpointId"
  1713. in: "query"
  1714. description: "Stacks created before version 1.18.0 might not have an associated endpoint identifier. Use this \
  1715. optional parameter to set the endpoint identifier used by the stack."
  1716. type: "integer"
  1717. - in: "body"
  1718. name: "body"
  1719. description: "Stack details"
  1720. required: true
  1721. schema:
  1722. $ref: "#/definitions/StackUpdateRequest"
  1723. responses:
  1724. 200:
  1725. description: "Success"
  1726. schema:
  1727. $ref: "#/definitions/Stack"
  1728. 400:
  1729. description: "Invalid request"
  1730. schema:
  1731. $ref: "#/definitions/GenericError"
  1732. examples:
  1733. application/json:
  1734. err: "Invalid request data format"
  1735. 403:
  1736. description: "Unauthorized"
  1737. schema:
  1738. $ref: "#/definitions/GenericError"
  1739. 404:
  1740. description: "Stack not found"
  1741. schema:
  1742. $ref: "#/definitions/GenericError"
  1743. examples:
  1744. application/json:
  1745. err: "Stack not found"
  1746. 500:
  1747. description: "Server error"
  1748. schema:
  1749. $ref: "#/definitions/GenericError"
  1750. delete:
  1751. tags:
  1752. - "stacks"
  1753. summary: "Remove a stack"
  1754. description: |
  1755. Remove a stack.
  1756. **Access policy**: restricted
  1757. operationId: "StackDelete"
  1758. security:
  1759. - jwt: []
  1760. parameters:
  1761. - name: "id"
  1762. in: "path"
  1763. description: "Stack identifier"
  1764. required: true
  1765. type: "integer"
  1766. - name: "external"
  1767. in: "query"
  1768. description: "Set to true to delete an external stack. Only external Swarm stacks are supported."
  1769. type: "boolean"
  1770. - name: "endpointId"
  1771. in: "query"
  1772. description: "Endpoint identifier used to remove an external stack (required when external is set to true)"
  1773. type: "string"
  1774. responses:
  1775. 204:
  1776. description: "Success"
  1777. 400:
  1778. description: "Invalid request"
  1779. schema:
  1780. $ref: "#/definitions/GenericError"
  1781. examples:
  1782. application/json:
  1783. err: "Invalid request"
  1784. 403:
  1785. description: "Unauthorized"
  1786. schema:
  1787. $ref: "#/definitions/GenericError"
  1788. 404:
  1789. description: "Stack not found"
  1790. schema:
  1791. $ref: "#/definitions/GenericError"
  1792. examples:
  1793. application/json:
  1794. err: "Stack not found"
  1795. 500:
  1796. description: "Server error"
  1797. schema:
  1798. $ref: "#/definitions/GenericError"
  1799. /stacks/{id}/file:
  1800. get:
  1801. tags:
  1802. - "stacks"
  1803. summary: "Retrieve the content of the Stack file for the specified stack"
  1804. description: |
  1805. Get Stack file content.
  1806. **Access policy**: restricted
  1807. operationId: "StackFileInspect"
  1808. produces:
  1809. - "application/json"
  1810. security:
  1811. - jwt: []
  1812. parameters:
  1813. - name: "id"
  1814. in: "path"
  1815. description: "Stack identifier"
  1816. required: true
  1817. type: "integer"
  1818. responses:
  1819. 200:
  1820. description: "Success"
  1821. schema:
  1822. $ref: "#/definitions/StackFileInspectResponse"
  1823. 400:
  1824. description: "Invalid request"
  1825. schema:
  1826. $ref: "#/definitions/GenericError"
  1827. examples:
  1828. application/json:
  1829. err: "Invalid request"
  1830. 403:
  1831. description: "Unauthorized"
  1832. schema:
  1833. $ref: "#/definitions/GenericError"
  1834. 404:
  1835. description: "Stack not found"
  1836. schema:
  1837. $ref: "#/definitions/GenericError"
  1838. examples:
  1839. application/json:
  1840. err: "Stack not found"
  1841. 500:
  1842. description: "Server error"
  1843. schema:
  1844. $ref: "#/definitions/GenericError"
  1845. /stacks/{id}/migrate:
  1846. post:
  1847. tags:
  1848. - "stacks"
  1849. summary: "Migrate a stack to another endpoint"
  1850. description: |
  1851. Migrate a stack from an endpoint to another endpoint. It will re-create
  1852. the stack inside the target endpoint before removing the original stack.
  1853. **Access policy**: restricted
  1854. operationId: "StackMigrate"
  1855. produces:
  1856. - "application/json"
  1857. security:
  1858. - jwt: []
  1859. parameters:
  1860. - name: "id"
  1861. in: "path"
  1862. description: "Stack identifier"
  1863. required: true
  1864. type: "integer"
  1865. - name: "endpointId"
  1866. in: "query"
  1867. description: "Stacks created before version 1.18.0 might not have an associated endpoint identifier. Use this \
  1868. optional parameter to set the endpoint identifier used by the stack."
  1869. type: "integer"
  1870. - in: "body"
  1871. name: "body"
  1872. description: "Stack migration details."
  1873. schema:
  1874. $ref: "#/definitions/StackMigrateRequest"
  1875. responses:
  1876. 200:
  1877. description: "Success"
  1878. schema:
  1879. $ref: "#/definitions/Stack"
  1880. 400:
  1881. description: "Invalid request"
  1882. schema:
  1883. $ref: "#/definitions/GenericError"
  1884. examples:
  1885. application/json:
  1886. err: "Invalid request"
  1887. 403:
  1888. description: "Unauthorized"
  1889. schema:
  1890. $ref: "#/definitions/GenericError"
  1891. 404:
  1892. description: "Stack not found"
  1893. schema:
  1894. $ref: "#/definitions/GenericError"
  1895. examples:
  1896. application/json:
  1897. err: "Stack not found"
  1898. 500:
  1899. description: "Server error"
  1900. schema:
  1901. $ref: "#/definitions/GenericError"
  1902. /users:
  1903. get:
  1904. tags:
  1905. - "users"
  1906. summary: "List users"
  1907. description: |
  1908. List Portainer users. Non-administrator users will only be able to list other non-administrator user accounts.
  1909. **Access policy**: restricted
  1910. operationId: "UserList"
  1911. produces:
  1912. - "application/json"
  1913. security:
  1914. - jwt: []
  1915. parameters: []
  1916. responses:
  1917. 200:
  1918. description: "Success"
  1919. schema:
  1920. $ref: "#/definitions/UserListResponse"
  1921. 500:
  1922. description: "Server error"
  1923. schema:
  1924. $ref: "#/definitions/GenericError"
  1925. post:
  1926. tags:
  1927. - "users"
  1928. summary: "Create a new user"
  1929. description: |
  1930. Create a new Portainer user. Only team leaders and administrators can create users. Only administrators can
  1931. create an administrator user account.
  1932. **Access policy**: restricted
  1933. operationId: "UserCreate"
  1934. consumes:
  1935. - "application/json"
  1936. produces:
  1937. - "application/json"
  1938. security:
  1939. - jwt: []
  1940. parameters:
  1941. - in: "body"
  1942. name: "body"
  1943. description: "User details"
  1944. required: true
  1945. schema:
  1946. $ref: "#/definitions/UserCreateRequest"
  1947. responses:
  1948. 200:
  1949. description: "Success"
  1950. schema:
  1951. $ref: "#/definitions/UserSubset"
  1952. 400:
  1953. description: "Invalid request"
  1954. schema:
  1955. $ref: "#/definitions/GenericError"
  1956. examples:
  1957. application/json:
  1958. err: "Invalid request data format"
  1959. 403:
  1960. description: "Unauthorized"
  1961. schema:
  1962. $ref: "#/definitions/GenericError"
  1963. examples:
  1964. application/json:
  1965. err: "Access denied to resource"
  1966. 409:
  1967. description: "User already exists"
  1968. schema:
  1969. $ref: "#/definitions/GenericError"
  1970. examples:
  1971. application/json:
  1972. err: "User already exists"
  1973. 500:
  1974. description: "Server error"
  1975. schema:
  1976. $ref: "#/definitions/GenericError"
  1977. /users/{id}:
  1978. get:
  1979. tags:
  1980. - "users"
  1981. summary: "Inspect a user"
  1982. description: |
  1983. Retrieve details about a user.
  1984. **Access policy**: administrator
  1985. operationId: "UserInspect"
  1986. produces:
  1987. - "application/json"
  1988. security:
  1989. - jwt: []
  1990. parameters:
  1991. - name: "id"
  1992. in: "path"
  1993. description: "User identifier"
  1994. required: true
  1995. type: "integer"
  1996. responses:
  1997. 200:
  1998. description: "Success"
  1999. schema:
  2000. $ref: "#/definitions/User"
  2001. 400:
  2002. description: "Invalid request"
  2003. schema:
  2004. $ref: "#/definitions/GenericError"
  2005. examples:
  2006. application/json:
  2007. err: "Invalid request"
  2008. 404:
  2009. description: "User not found"
  2010. schema:
  2011. $ref: "#/definitions/GenericError"
  2012. examples:
  2013. application/json:
  2014. err: "User not found"
  2015. 500:
  2016. description: "Server error"
  2017. schema:
  2018. $ref: "#/definitions/GenericError"
  2019. put:
  2020. tags:
  2021. - "users"
  2022. summary: "Update a user"
  2023. description: |
  2024. Update user details. A regular user account can only update his details.
  2025. **Access policy**: authenticated
  2026. operationId: "UserUpdate"
  2027. consumes:
  2028. - "application/json"
  2029. produces:
  2030. - "application/json"
  2031. security:
  2032. - jwt: []
  2033. parameters:
  2034. - name: "id"
  2035. in: "path"
  2036. description: "User identifier"
  2037. required: true
  2038. type: "integer"
  2039. - in: "body"
  2040. name: "body"
  2041. description: "User details"
  2042. required: true
  2043. schema:
  2044. $ref: "#/definitions/UserUpdateRequest"
  2045. responses:
  2046. 200:
  2047. description: "Success"
  2048. schema:
  2049. $ref: "#/definitions/User"
  2050. 400:
  2051. description: "Invalid request"
  2052. schema:
  2053. $ref: "#/definitions/GenericError"
  2054. examples:
  2055. application/json:
  2056. err: "Invalid request data format"
  2057. 403:
  2058. description: "Unauthorized"
  2059. schema:
  2060. $ref: "#/definitions/GenericError"
  2061. examples:
  2062. application/json:
  2063. err: "Access denied to resource"
  2064. 404:
  2065. description: "User not found"
  2066. schema:
  2067. $ref: "#/definitions/GenericError"
  2068. examples:
  2069. application/json:
  2070. err: "User not found"
  2071. 500:
  2072. description: "Server error"
  2073. schema:
  2074. $ref: "#/definitions/GenericError"
  2075. delete:
  2076. tags:
  2077. - "users"
  2078. summary: "Remove a user"
  2079. description: |
  2080. Remove a user.
  2081. **Access policy**: administrator
  2082. operationId: "UserDelete"
  2083. security:
  2084. - jwt: []
  2085. parameters:
  2086. - name: "id"
  2087. in: "path"
  2088. description: "User identifier"
  2089. required: true
  2090. type: "integer"
  2091. responses:
  2092. 204:
  2093. description: "Success"
  2094. 400:
  2095. description: "Invalid request"
  2096. schema:
  2097. $ref: "#/definitions/GenericError"
  2098. examples:
  2099. application/json:
  2100. err: "Invalid request"
  2101. 404:
  2102. description: "User not found"
  2103. schema:
  2104. $ref: "#/definitions/GenericError"
  2105. examples:
  2106. application/json:
  2107. err: "User not found"
  2108. 500:
  2109. description: "Server error"
  2110. schema:
  2111. $ref: "#/definitions/GenericError"
  2112. /users/{id}/memberships:
  2113. get:
  2114. tags:
  2115. - "users"
  2116. summary: "Inspect a user memberships"
  2117. description: |
  2118. Inspect a user memberships.
  2119. **Access policy**: authenticated
  2120. operationId: "UserMembershipsInspect"
  2121. produces:
  2122. - "application/json"
  2123. security:
  2124. - jwt: []
  2125. parameters:
  2126. - name: "id"
  2127. in: "path"
  2128. description: "User identifier"
  2129. required: true
  2130. type: "integer"
  2131. responses:
  2132. 200:
  2133. description: "Success"
  2134. schema:
  2135. $ref: "#/definitions/UserMembershipsResponse"
  2136. 400:
  2137. description: "Invalid request"
  2138. schema:
  2139. $ref: "#/definitions/GenericError"
  2140. examples:
  2141. application/json:
  2142. err: "Invalid request"
  2143. 403:
  2144. description: "Unauthorized"
  2145. schema:
  2146. $ref: "#/definitions/GenericError"
  2147. examples:
  2148. application/json:
  2149. err: "Access denied to resource"
  2150. 500:
  2151. description: "Server error"
  2152. schema:
  2153. $ref: "#/definitions/GenericError"
  2154. /users/{id}/passwd:
  2155. post:
  2156. tags:
  2157. - "users"
  2158. summary: "Check password validity for a user"
  2159. description: |
  2160. Check if the submitted password is valid for the specified user.
  2161. **Access policy**: authenticated
  2162. operationId: "UserPasswordCheck"
  2163. consumes:
  2164. - "application/json"
  2165. produces:
  2166. - "application/json"
  2167. security:
  2168. - jwt: []
  2169. parameters:
  2170. - name: "id"
  2171. in: "path"
  2172. description: "User identifier"
  2173. required: true
  2174. type: "integer"
  2175. - in: "body"
  2176. name: "body"
  2177. description: "User details"
  2178. required: true
  2179. schema:
  2180. $ref: "#/definitions/UserPasswordCheckRequest"
  2181. responses:
  2182. 200:
  2183. description: "Success"
  2184. schema:
  2185. $ref: "#/definitions/UserPasswordCheckResponse"
  2186. 400:
  2187. description: "Invalid request"
  2188. schema:
  2189. $ref: "#/definitions/GenericError"
  2190. examples:
  2191. application/json:
  2192. err: "Invalid request data format"
  2193. 404:
  2194. description: "User not found"
  2195. schema:
  2196. $ref: "#/definitions/GenericError"
  2197. examples:
  2198. application/json:
  2199. err: "User not found"
  2200. 500:
  2201. description: "Server error"
  2202. schema:
  2203. $ref: "#/definitions/GenericError"
  2204. /users/admin/check:
  2205. get:
  2206. tags:
  2207. - "users"
  2208. summary: "Check administrator account existence"
  2209. description: |
  2210. Check if an administrator account exists in the database.
  2211. **Access policy**: public
  2212. operationId: "UserAdminCheck"
  2213. produces:
  2214. - "application/json"
  2215. security:
  2216. - jwt: []
  2217. parameters: []
  2218. responses:
  2219. 204:
  2220. description: "Success"
  2221. 404:
  2222. description: "User not found"
  2223. schema:
  2224. $ref: "#/definitions/GenericError"
  2225. examples:
  2226. application/json:
  2227. err: "User not found"
  2228. 500:
  2229. description: "Server error"
  2230. schema:
  2231. $ref: "#/definitions/GenericError"
  2232. /users/admin/init:
  2233. post:
  2234. tags:
  2235. - "users"
  2236. summary: "Initialize administrator account"
  2237. description: |
  2238. Initialize the 'admin' user account.
  2239. **Access policy**: public
  2240. operationId: "UserAdminInit"
  2241. consumes:
  2242. - "application/json"
  2243. produces:
  2244. - "application/json"
  2245. security:
  2246. - jwt: []
  2247. parameters:
  2248. - in: "body"
  2249. name: "body"
  2250. description: "User details"
  2251. required: true
  2252. schema:
  2253. $ref: "#/definitions/UserAdminInitRequest"
  2254. responses:
  2255. 200:
  2256. description: "Success"
  2257. schema:
  2258. $ref: "#/definitions/User"
  2259. 400:
  2260. description: "Invalid request"
  2261. schema:
  2262. $ref: "#/definitions/GenericError"
  2263. examples:
  2264. application/json:
  2265. err: "Invalid request data format"
  2266. 409:
  2267. description: "Admin user already initialized"
  2268. schema:
  2269. $ref: "#/definitions/GenericError"
  2270. examples:
  2271. application/json:
  2272. err: "User already exists"
  2273. 500:
  2274. description: "Server error"
  2275. schema:
  2276. $ref: "#/definitions/GenericError"
  2277. /upload/tls/{certificate}:
  2278. post:
  2279. tags:
  2280. - "upload"
  2281. summary: "Upload TLS files"
  2282. description: |
  2283. Use this endpoint to upload TLS files.
  2284. **Access policy**: administrator
  2285. operationId: "UploadTLS"
  2286. consumes:
  2287. - multipart/form-data
  2288. produces:
  2289. - "application/json"
  2290. security:
  2291. - jwt: []
  2292. parameters:
  2293. - in: "path"
  2294. name: "certificate"
  2295. description: "TLS file type. Valid values are 'ca', 'cert' or 'key'."
  2296. required: true
  2297. type: "string"
  2298. - in: "query"
  2299. name: "folder"
  2300. description: "Folder where the TLS file will be stored. Will be created if not existing."
  2301. required: true
  2302. type: "string"
  2303. - in: "formData"
  2304. name: "file"
  2305. type: "file"
  2306. description: "The file to upload."
  2307. responses:
  2308. 200:
  2309. description: "Success"
  2310. 400:
  2311. description: "Invalid request"
  2312. schema:
  2313. $ref: "#/definitions/GenericError"
  2314. examples:
  2315. application/json:
  2316. err: "Invalid request data"
  2317. 500:
  2318. description: "Server error"
  2319. schema:
  2320. $ref: "#/definitions/GenericError"
  2321. /tags:
  2322. get:
  2323. tags:
  2324. - "tags"
  2325. summary: "List tags"
  2326. description: |
  2327. List tags.
  2328. **Access policy**: administrator
  2329. operationId: "TagList"
  2330. produces:
  2331. - "application/json"
  2332. security:
  2333. - jwt: []
  2334. parameters: []
  2335. responses:
  2336. 200:
  2337. description: "Success"
  2338. schema:
  2339. $ref: "#/definitions/TagListResponse"
  2340. 500:
  2341. description: "Server error"
  2342. schema:
  2343. $ref: "#/definitions/GenericError"
  2344. post:
  2345. tags:
  2346. - "tags"
  2347. summary: "Create a new tag"
  2348. description: |
  2349. Create a new tag.
  2350. **Access policy**: administrator
  2351. operationId: "TagCreate"
  2352. consumes:
  2353. - "application/json"
  2354. produces:
  2355. - "application/json"
  2356. security:
  2357. - jwt: []
  2358. parameters:
  2359. - in: "body"
  2360. name: "body"
  2361. description: "Tag details"
  2362. required: true
  2363. schema:
  2364. $ref: "#/definitions/TagCreateRequest"
  2365. responses:
  2366. 200:
  2367. description: "Success"
  2368. schema:
  2369. $ref: "#/definitions/Tag"
  2370. 400:
  2371. description: "Invalid request"
  2372. schema:
  2373. $ref: "#/definitions/GenericError"
  2374. examples:
  2375. application/json:
  2376. err: "Invalid request data format"
  2377. 409:
  2378. description: "Conflict"
  2379. schema:
  2380. $ref: "#/definitions/GenericError"
  2381. examples:
  2382. application/json:
  2383. err: "A tag with the specified name already exists"
  2384. 500:
  2385. description: "Server error"
  2386. schema:
  2387. $ref: "#/definitions/GenericError"
  2388. /tags/{id}:
  2389. delete:
  2390. tags:
  2391. - "tags"
  2392. summary: "Remove a tag"
  2393. description: |
  2394. Remove a tag.
  2395. **Access policy**: administrator
  2396. operationId: "TagDelete"
  2397. security:
  2398. - jwt: []
  2399. parameters:
  2400. - name: "id"
  2401. in: "path"
  2402. description: "Tag identifier"
  2403. required: true
  2404. type: "integer"
  2405. responses:
  2406. 204:
  2407. description: "Success"
  2408. 400:
  2409. description: "Invalid request"
  2410. schema:
  2411. $ref: "#/definitions/GenericError"
  2412. examples:
  2413. application/json:
  2414. err: "Invalid request"
  2415. 500:
  2416. description: "Server error"
  2417. schema:
  2418. $ref: "#/definitions/GenericError"
  2419. /teams:
  2420. get:
  2421. tags:
  2422. - "teams"
  2423. summary: "List teams"
  2424. description: |
  2425. List teams. For non-administrator users, will only list the teams they are member of.
  2426. **Access policy**: restricted
  2427. operationId: "TeamList"
  2428. produces:
  2429. - "application/json"
  2430. security:
  2431. - jwt: []
  2432. parameters: []
  2433. responses:
  2434. 200:
  2435. description: "Success"
  2436. schema:
  2437. $ref: "#/definitions/TeamListResponse"
  2438. 500:
  2439. description: "Server error"
  2440. schema:
  2441. $ref: "#/definitions/GenericError"
  2442. post:
  2443. tags:
  2444. - "teams"
  2445. summary: "Create a new team"
  2446. description: |
  2447. Create a new team.
  2448. **Access policy**: administrator
  2449. operationId: "TeamCreate"
  2450. consumes:
  2451. - "application/json"
  2452. produces:
  2453. - "application/json"
  2454. security:
  2455. - jwt: []
  2456. parameters:
  2457. - in: "body"
  2458. name: "body"
  2459. description: "Team details"
  2460. required: true
  2461. schema:
  2462. $ref: "#/definitions/TeamCreateRequest"
  2463. responses:
  2464. 200:
  2465. description: "Success"
  2466. schema:
  2467. $ref: "#/definitions/Team"
  2468. 400:
  2469. description: "Invalid request"
  2470. schema:
  2471. $ref: "#/definitions/GenericError"
  2472. examples:
  2473. application/json:
  2474. err: "Invalid request data format"
  2475. 403:
  2476. description: "Unauthorized"
  2477. schema:
  2478. $ref: "#/definitions/GenericError"
  2479. examples:
  2480. application/json:
  2481. err: "Access denied to resource"
  2482. 409:
  2483. description: "Team already exists"
  2484. schema:
  2485. $ref: "#/definitions/GenericError"
  2486. examples:
  2487. application/json:
  2488. err: "Team already exists"
  2489. 500:
  2490. description: "Server error"
  2491. schema:
  2492. $ref: "#/definitions/GenericError"
  2493. /teams/{id}:
  2494. get:
  2495. tags:
  2496. - "teams"
  2497. summary: "Inspect a team"
  2498. description: |
  2499. Retrieve details about a team. Access is only available for administrator and leaders of that team.
  2500. **Access policy**: restricted
  2501. operationId: "TeamInspect"
  2502. produces:
  2503. - "application/json"
  2504. security:
  2505. - jwt: []
  2506. parameters:
  2507. - name: "id"
  2508. in: "path"
  2509. description: "Team identifier"
  2510. required: true
  2511. type: "integer"
  2512. responses:
  2513. 200:
  2514. description: "Success"
  2515. schema:
  2516. $ref: "#/definitions/Team"
  2517. 400:
  2518. description: "Invalid request"
  2519. schema:
  2520. $ref: "#/definitions/GenericError"
  2521. examples:
  2522. application/json:
  2523. err: "Invalid request"
  2524. 403:
  2525. description: "Unauthorized"
  2526. schema:
  2527. $ref: "#/definitions/GenericError"
  2528. examples:
  2529. application/json:
  2530. err: "Access denied to resource"
  2531. 404:
  2532. description: "Team not found"
  2533. schema:
  2534. $ref: "#/definitions/GenericError"
  2535. examples:
  2536. application/json:
  2537. err: "Team not found"
  2538. 500:
  2539. description: "Server error"
  2540. schema:
  2541. $ref: "#/definitions/GenericError"
  2542. put:
  2543. tags:
  2544. - "teams"
  2545. summary: "Update a team"
  2546. description: |
  2547. Update a team.
  2548. **Access policy**: administrator
  2549. operationId: "TeamUpdate"
  2550. consumes:
  2551. - "application/json"
  2552. produces:
  2553. - "application/json"
  2554. security:
  2555. - jwt: []
  2556. parameters:
  2557. - name: "id"
  2558. in: "path"
  2559. description: "Team identifier"
  2560. required: true
  2561. type: "integer"
  2562. - in: "body"
  2563. name: "body"
  2564. description: "Team details"
  2565. required: true
  2566. schema:
  2567. $ref: "#/definitions/TeamUpdateRequest"
  2568. responses:
  2569. 200:
  2570. description: "Success"
  2571. 400:
  2572. description: "Invalid request"
  2573. schema:
  2574. $ref: "#/definitions/GenericError"
  2575. examples:
  2576. application/json:
  2577. err: "Invalid request data format"
  2578. 404:
  2579. description: "Team not found"
  2580. schema:
  2581. $ref: "#/definitions/GenericError"
  2582. examples:
  2583. application/json:
  2584. err: "Team not found"
  2585. 500:
  2586. description: "Server error"
  2587. schema:
  2588. $ref: "#/definitions/GenericError"
  2589. delete:
  2590. tags:
  2591. - "teams"
  2592. summary: "Remove a team"
  2593. description: |
  2594. Remove a team.
  2595. **Access policy**: administrator
  2596. operationId: "TeamDelete"
  2597. security:
  2598. - jwt: []
  2599. parameters:
  2600. - name: "id"
  2601. in: "path"
  2602. description: "Team identifier"
  2603. required: true
  2604. type: "integer"
  2605. responses:
  2606. 204:
  2607. description: "Success"
  2608. 400:
  2609. description: "Invalid request"
  2610. schema:
  2611. $ref: "#/definitions/GenericError"
  2612. examples:
  2613. application/json:
  2614. err: "Invalid request"
  2615. 404:
  2616. description: "Team not found"
  2617. schema:
  2618. $ref: "#/definitions/GenericError"
  2619. examples:
  2620. application/json:
  2621. err: "Team not found"
  2622. 500:
  2623. description: "Server error"
  2624. schema:
  2625. $ref: "#/definitions/GenericError"
  2626. /teams/{id}/memberships:
  2627. get:
  2628. tags:
  2629. - "teams"
  2630. summary: "Inspect a team memberships"
  2631. description: |
  2632. Inspect a team memberships. Access is only available for administrator and leaders of that team.
  2633. **Access policy**: restricted
  2634. operationId: "TeamMembershipsInspect"
  2635. produces:
  2636. - "application/json"
  2637. security:
  2638. - jwt: []
  2639. parameters:
  2640. - name: "id"
  2641. in: "path"
  2642. description: "Team identifier"
  2643. required: true
  2644. type: "integer"
  2645. responses:
  2646. 200:
  2647. description: "Success"
  2648. schema:
  2649. $ref: "#/definitions/TeamMembershipsResponse"
  2650. 400:
  2651. description: "Invalid request"
  2652. schema:
  2653. $ref: "#/definitions/GenericError"
  2654. examples:
  2655. application/json:
  2656. err: "Invalid request"
  2657. 403:
  2658. description: "Unauthorized"
  2659. schema:
  2660. $ref: "#/definitions/GenericError"
  2661. examples:
  2662. application/json:
  2663. err: "Access denied to resource"
  2664. 500:
  2665. description: "Server error"
  2666. schema:
  2667. $ref: "#/definitions/GenericError"
  2668. /team_memberships:
  2669. get:
  2670. tags:
  2671. - "team_memberships"
  2672. summary: "List team memberships"
  2673. description: |
  2674. List team memberships. Access is only available to administrators and team leaders.
  2675. **Access policy**: restricted
  2676. operationId: "TeamMembershipList"
  2677. produces:
  2678. - "application/json"
  2679. security:
  2680. - jwt: []
  2681. parameters: []
  2682. responses:
  2683. 200:
  2684. description: "Success"
  2685. schema:
  2686. $ref: "#/definitions/TeamMembershipListResponse"
  2687. 403:
  2688. description: "Unauthorized"
  2689. schema:
  2690. $ref: "#/definitions/GenericError"
  2691. examples:
  2692. application/json:
  2693. err: "Access denied to resource"
  2694. 500:
  2695. description: "Server error"
  2696. schema:
  2697. $ref: "#/definitions/GenericError"
  2698. post:
  2699. tags:
  2700. - "team_memberships"
  2701. summary: "Create a new team membership"
  2702. description: |
  2703. Create a new team memberships. Access is only available to administrators leaders of the associated team.
  2704. **Access policy**: restricted
  2705. operationId: "TeamMembershipCreate"
  2706. consumes:
  2707. - "application/json"
  2708. produces:
  2709. - "application/json"
  2710. security:
  2711. - jwt: []
  2712. parameters:
  2713. - in: "body"
  2714. name: "body"
  2715. description: "Team membership details"
  2716. required: true
  2717. schema:
  2718. $ref: "#/definitions/TeamMembershipCreateRequest"
  2719. responses:
  2720. 200:
  2721. description: "Success"
  2722. schema:
  2723. $ref: "#/definitions/TeamMembership"
  2724. 400:
  2725. description: "Invalid request"
  2726. schema:
  2727. $ref: "#/definitions/GenericError"
  2728. examples:
  2729. application/json:
  2730. err: "Invalid request data format"
  2731. 403:
  2732. description: "Unauthorized"
  2733. schema:
  2734. $ref: "#/definitions/GenericError"
  2735. examples:
  2736. application/json:
  2737. err: "Access denied to resource"
  2738. 409:
  2739. description: "Team membership already exists"
  2740. schema:
  2741. $ref: "#/definitions/GenericError"
  2742. examples:
  2743. application/json:
  2744. err: "Team membership already exists for this user and team."
  2745. 500:
  2746. description: "Server error"
  2747. schema:
  2748. $ref: "#/definitions/GenericError"
  2749. /team_memberships/{id}:
  2750. put:
  2751. tags:
  2752. - "team_memberships"
  2753. summary: "Update a team membership"
  2754. description: |
  2755. Update a team membership. Access is only available to administrators leaders of the associated team.
  2756. **Access policy**: restricted
  2757. operationId: "TeamMembershipUpdate"
  2758. consumes:
  2759. - "application/json"
  2760. produces:
  2761. - "application/json"
  2762. security:
  2763. - jwt: []
  2764. parameters:
  2765. - name: "id"
  2766. in: "path"
  2767. description: "Team membership identifier"
  2768. required: true
  2769. type: "integer"
  2770. - in: "body"
  2771. name: "body"
  2772. description: "Team membership details"
  2773. required: true
  2774. schema:
  2775. $ref: "#/definitions/TeamMembershipUpdateRequest"
  2776. responses:
  2777. 200:
  2778. description: "Success"
  2779. schema:
  2780. $ref: "#/definitions/TeamMembership"
  2781. 400:
  2782. description: "Invalid request"
  2783. schema:
  2784. $ref: "#/definitions/GenericError"
  2785. examples:
  2786. application/json:
  2787. err: "Invalid request data format"
  2788. 403:
  2789. description: "Unauthorized"
  2790. schema:
  2791. $ref: "#/definitions/GenericError"
  2792. examples:
  2793. application/json:
  2794. err: "Access denied to resource"
  2795. 404:
  2796. description: "Team membership not found"
  2797. schema:
  2798. $ref: "#/definitions/GenericError"
  2799. examples:
  2800. application/json:
  2801. err: "Team membership not found"
  2802. 500:
  2803. description: "Server error"
  2804. schema:
  2805. $ref: "#/definitions/GenericError"
  2806. delete:
  2807. tags:
  2808. - "team_memberships"
  2809. summary: "Remove a team membership"
  2810. description: |
  2811. Remove a team membership. Access is only available to administrators leaders of the associated team.
  2812. **Access policy**: restricted
  2813. operationId: "TeamMembershipDelete"
  2814. security:
  2815. - jwt: []
  2816. parameters:
  2817. - name: "id"
  2818. in: "path"
  2819. description: "TeamMembership identifier"
  2820. required: true
  2821. type: "integer"
  2822. responses:
  2823. 204:
  2824. description: "Success"
  2825. 400:
  2826. description: "Invalid request"
  2827. schema:
  2828. $ref: "#/definitions/GenericError"
  2829. examples:
  2830. application/json:
  2831. err: "Invalid request"
  2832. 403:
  2833. description: "Unauthorized"
  2834. schema:
  2835. $ref: "#/definitions/GenericError"
  2836. examples:
  2837. application/json:
  2838. err: "Access denied to resource"
  2839. 404:
  2840. description: "Team membership not found"
  2841. schema:
  2842. $ref: "#/definitions/GenericError"
  2843. examples:
  2844. application/json:
  2845. err: "Team membership not found"
  2846. 500:
  2847. description: "Server error"
  2848. schema:
  2849. $ref: "#/definitions/GenericError"
  2850. /templates:
  2851. get:
  2852. tags:
  2853. - "templates"
  2854. summary: "List available templates"
  2855. description: |
  2856. List available templates.
  2857. Administrator templates will not be listed for non-administrator users.
  2858. **Access policy**: restricted
  2859. operationId: "TemplateList"
  2860. produces:
  2861. - "application/json"
  2862. security:
  2863. - jwt: []
  2864. parameters: []
  2865. responses:
  2866. 200:
  2867. description: "Success"
  2868. schema:
  2869. $ref: "#/definitions/TemplateListResponse"
  2870. 500:
  2871. description: "Server error"
  2872. schema:
  2873. $ref: "#/definitions/GenericError"
  2874. post:
  2875. tags:
  2876. - "templates"
  2877. summary: "Create a new template"
  2878. description: |
  2879. Create a new template.
  2880. **Access policy**: administrator
  2881. operationId: "TemplateCreate"
  2882. consumes:
  2883. - "application/json"
  2884. produces:
  2885. - "application/json"
  2886. security:
  2887. - jwt: []
  2888. parameters:
  2889. - in: "body"
  2890. name: "body"
  2891. description: "Template details"
  2892. required: true
  2893. schema:
  2894. $ref: "#/definitions/TemplateCreateRequest"
  2895. responses:
  2896. 200:
  2897. description: "Success"
  2898. schema:
  2899. $ref: "#/definitions/Template"
  2900. 400:
  2901. description: "Invalid request"
  2902. schema:
  2903. $ref: "#/definitions/GenericError"
  2904. examples:
  2905. application/json:
  2906. err: "Invalid request data format"
  2907. 403:
  2908. description: "Unauthorized"
  2909. schema:
  2910. $ref: "#/definitions/GenericError"
  2911. examples:
  2912. application/json:
  2913. err: "Access denied to resource"
  2914. 500:
  2915. description: "Server error"
  2916. schema:
  2917. $ref: "#/definitions/GenericError"
  2918. /templates/{id}:
  2919. get:
  2920. tags:
  2921. - "templates"
  2922. summary: "Inspect a template"
  2923. description: |
  2924. Retrieve details about a template.
  2925. **Access policy**: administrator
  2926. operationId: "TemplateInspect"
  2927. produces:
  2928. - "application/json"
  2929. security:
  2930. - jwt: []
  2931. parameters:
  2932. - name: "id"
  2933. in: "path"
  2934. description: "Template identifier"
  2935. required: true
  2936. type: "integer"
  2937. responses:
  2938. 200:
  2939. description: "Success"
  2940. schema:
  2941. $ref: "#/definitions/Template"
  2942. 400:
  2943. description: "Invalid request"
  2944. schema:
  2945. $ref: "#/definitions/GenericError"
  2946. examples:
  2947. application/json:
  2948. err: "Invalid request"
  2949. 403:
  2950. description: "Unauthorized"
  2951. schema:
  2952. $ref: "#/definitions/GenericError"
  2953. examples:
  2954. application/json:
  2955. err: "Access denied to resource"
  2956. 404:
  2957. description: "Template not found"
  2958. schema:
  2959. $ref: "#/definitions/GenericError"
  2960. examples:
  2961. application/json:
  2962. err: "Template not found"
  2963. 500:
  2964. description: "Server error"
  2965. schema:
  2966. $ref: "#/definitions/GenericError"
  2967. put:
  2968. tags:
  2969. - "templates"
  2970. summary: "Update a template"
  2971. description: |
  2972. Update a template.
  2973. **Access policy**: administrator
  2974. operationId: "TemplateUpdate"
  2975. consumes:
  2976. - "application/json"
  2977. produces:
  2978. - "application/json"
  2979. security:
  2980. - jwt: []
  2981. parameters:
  2982. - name: "id"
  2983. in: "path"
  2984. description: "Template identifier"
  2985. required: true
  2986. type: "integer"
  2987. - in: "body"
  2988. name: "body"
  2989. description: "Template details"
  2990. required: true
  2991. schema:
  2992. $ref: "#/definitions/TemplateUpdateRequest"
  2993. responses:
  2994. 200:
  2995. description: "Success"
  2996. 400:
  2997. description: "Invalid request"
  2998. schema:
  2999. $ref: "#/definitions/GenericError"
  3000. examples:
  3001. application/json:
  3002. err: "Invalid request data format"
  3003. 403:
  3004. description: "Unauthorized"
  3005. schema:
  3006. $ref: "#/definitions/GenericError"
  3007. examples:
  3008. application/json:
  3009. err: "Access denied to resource"
  3010. 404:
  3011. description: "Template not found"
  3012. schema:
  3013. $ref: "#/definitions/GenericError"
  3014. examples:
  3015. application/json:
  3016. err: "Template not found"
  3017. 500:
  3018. description: "Server error"
  3019. schema:
  3020. $ref: "#/definitions/GenericError"
  3021. delete:
  3022. tags:
  3023. - "templates"
  3024. summary: "Remove a template"
  3025. description: |
  3026. Remove a template.
  3027. **Access policy**: administrator
  3028. operationId: "TemplateDelete"
  3029. security:
  3030. - jwt: []
  3031. parameters:
  3032. - name: "id"
  3033. in: "path"
  3034. description: "Template identifier"
  3035. required: true
  3036. type: "integer"
  3037. responses:
  3038. 204:
  3039. description: "Success"
  3040. 400:
  3041. description: "Invalid request"
  3042. schema:
  3043. $ref: "#/definitions/GenericError"
  3044. examples:
  3045. application/json:
  3046. err: "Invalid request"
  3047. 500:
  3048. description: "Server error"
  3049. schema:
  3050. $ref: "#/definitions/GenericError"
  3051. securityDefinitions:
  3052. jwt:
  3053. type: "apiKey"
  3054. name: "Authorization"
  3055. in: "header"
  3056. definitions:
  3057. Tag:
  3058. type: "object"
  3059. properties:
  3060. Id:
  3061. type: "integer"
  3062. example: 1
  3063. description: "Tag identifier"
  3064. Name:
  3065. type: "string"
  3066. example: "org/acme"
  3067. description: "Tag name"
  3068. Team:
  3069. type: "object"
  3070. properties:
  3071. Id:
  3072. type: "integer"
  3073. example: 1
  3074. description: "Team identifier"
  3075. Name:
  3076. type: "string"
  3077. example: "developers"
  3078. description: "Team name"
  3079. TeamMembership:
  3080. type: "object"
  3081. properties:
  3082. Id:
  3083. type: "integer"
  3084. example: 1
  3085. description: "Membership identifier"
  3086. UserID:
  3087. type: "integer"
  3088. example: 1
  3089. description: "User identifier"
  3090. TeamID:
  3091. type: "integer"
  3092. example: 1
  3093. description: "Team identifier"
  3094. Role:
  3095. type: "integer"
  3096. example: 1
  3097. description: "Team role (1 for team leader and 2 for team member)"
  3098. UserSubset:
  3099. type: "object"
  3100. properties:
  3101. Id:
  3102. type: "integer"
  3103. example: 1
  3104. description: "User identifier"
  3105. Username:
  3106. type: "string"
  3107. example: "bob"
  3108. description: "Username"
  3109. Role:
  3110. type: "integer"
  3111. example: 1
  3112. description: "User role (1 for administrator account and 2 for regular account)"
  3113. User:
  3114. type: "object"
  3115. properties:
  3116. Id:
  3117. type: "integer"
  3118. example: 1
  3119. description: "User identifier"
  3120. Username:
  3121. type: "string"
  3122. example: "bob"
  3123. description: "Username"
  3124. Password:
  3125. type: "string"
  3126. example: "passwd"
  3127. description: "Password"
  3128. Role:
  3129. type: "integer"
  3130. example: 1
  3131. description: "User role (1 for administrator account and 2 for regular account)"
  3132. Status:
  3133. type: "object"
  3134. properties:
  3135. Authentication:
  3136. type: "boolean"
  3137. example: true
  3138. description: "Is authentication enabled"
  3139. EndpointManagement:
  3140. type: "boolean"
  3141. example: true
  3142. description: "Is endpoint management enabled"
  3143. Analytics:
  3144. type: "boolean"
  3145. example: true
  3146. description: "Is analytics enabled"
  3147. Version:
  3148. type: "string"
  3149. example: "1.24.0-dev"
  3150. description: "Portainer API version"
  3151. PublicSettingsInspectResponse:
  3152. type: "object"
  3153. properties:
  3154. LogoURL:
  3155. type: "string"
  3156. example: "https://mycompany.mydomain.tld/logo.png"
  3157. description: "URL to a logo that will be displayed on the login page as well\
  3158. \ as on top of the sidebar. Will use default Portainer logo when value is\
  3159. \ empty string"
  3160. DisplayExternalContributors:
  3161. type: "boolean"
  3162. example: false
  3163. description: "Whether to display or not external templates contributions as\
  3164. \ sub-menus in the UI."
  3165. AuthenticationMethod:
  3166. type: "integer"
  3167. example: 1
  3168. description: "Active authentication method for the Portainer instance. Valid values are: 1 for managed or 2 for LDAP."
  3169. AllowBindMountsForRegularUsers:
  3170. type: "boolean"
  3171. example: false
  3172. description: "Whether non-administrator should be able to use bind mounts when creating containers"
  3173. AllowPrivilegedModeForRegularUsers:
  3174. type: "boolean"
  3175. example: true
  3176. description: "Whether non-administrator should be able to use privileged mode when creating containers"
  3177. TLSConfiguration:
  3178. type: "object"
  3179. properties:
  3180. TLS:
  3181. type: "boolean"
  3182. example: true
  3183. description: "Use TLS"
  3184. TLSSkipVerify:
  3185. type: "boolean"
  3186. example: false
  3187. description: "Skip the verification of the server TLS certificate"
  3188. TLSCACertPath:
  3189. type: "string"
  3190. example: "/data/tls/ca.pem"
  3191. description: "Path to the TLS CA certificate file"
  3192. TLSCertPath:
  3193. type: "string"
  3194. example: "/data/tls/cert.pem"
  3195. description: "Path to the TLS client certificate file"
  3196. TLSKeyPath:
  3197. type: "string"
  3198. example: "/data/tls/key.pem"
  3199. description: "Path to the TLS client key file"
  3200. AzureCredentials:
  3201. type: "object"
  3202. properties:
  3203. ApplicationID:
  3204. type: "string"
  3205. example: "eag7cdo9-o09l-9i83-9dO9-f0b23oe78db4"
  3206. description: "Azure application ID"
  3207. TenantID:
  3208. type: "string"
  3209. example: "34ddc78d-4fel-2358-8cc1-df84c8o839f5"
  3210. description: "Azure tenant ID"
  3211. AuthenticationKey:
  3212. type: "string"
  3213. example: "cOrXoK/1D35w8YQ8nH1/8ZGwzz45JIYD5jxHKXEQknk="
  3214. description: "Azure authentication key"
  3215. LDAPSearchSettings:
  3216. type: "object"
  3217. properties:
  3218. BaseDN:
  3219. type: "string"
  3220. example: "dc=ldap,dc=domain,dc=tld"
  3221. description: "The distinguished name of the element from which the LDAP server will search for users"
  3222. Filter:
  3223. type: "string"
  3224. example: "(objectClass=account)"
  3225. description: "Optional LDAP search filter used to select user elements"
  3226. UserNameAttribute:
  3227. type: "string"
  3228. example: "uid"
  3229. description: "LDAP attribute which denotes the username"
  3230. LDAPGroupSearchSettings:
  3231. type: "object"
  3232. properties:
  3233. GroupBaseDN:
  3234. type: "string"
  3235. example: "dc=ldap,dc=domain,dc=tld"
  3236. description: "The distinguished name of the element from which the LDAP server will search for groups."
  3237. GroupFilter:
  3238. type: "string"
  3239. example: "(objectClass=account)"
  3240. description: "The LDAP search filter used to select group elements, optional."
  3241. GroupAttribute:
  3242. type: "string"
  3243. example: "member"
  3244. description: "LDAP attribute which denotes the group membership."
  3245. UserAccessPolicies:
  3246. type: "object"
  3247. description: "User access policies associated to a registry/endpoint/endpoint group. RoleID is not required for registry access policies and can be set to 0."
  3248. additionalProperties:
  3249. $ref: "#/definitions/AccessPolicy"
  3250. example:
  3251. 1: { RoleID: 1 }
  3252. 2: { RoleID: 3 }
  3253. TeamAccessPolicies:
  3254. type: "object"
  3255. description: "Team access policies associated to a registry/endpoint/endpoint group. RoleID is not required for registry access policies and can be set to 0."
  3256. additionalProperties:
  3257. $ref: "#/definitions/AccessPolicy"
  3258. example:
  3259. 1: { RoleID: 1 }
  3260. 2: { RoleID: 3 }
  3261. AccessPolicy:
  3262. type: "object"
  3263. properties:
  3264. RoleID:
  3265. type: "integer"
  3266. example: "1"
  3267. description: "Role identifier. Reference the role that will be associated to this access policy"
  3268. LDAPSettings:
  3269. type: "object"
  3270. properties:
  3271. AnonymousMode:
  3272. type: "boolean"
  3273. example: true
  3274. description: "Enable this option if the server is configured for Anonymous access. When enabled, ReaderDN and Password will not be used."
  3275. ReaderDN:
  3276. type: "string"
  3277. example: "cn=readonly-account,dc=ldap,dc=domain,dc=tld"
  3278. description: "Account that will be used to search for users"
  3279. Password:
  3280. type: "string"
  3281. example: "readonly-password"
  3282. description: "Password of the account that will be used to search users"
  3283. URL:
  3284. type: "string"
  3285. example: "myldap.domain.tld:389"
  3286. description: "URL or IP address of the LDAP server"
  3287. TLSConfig:
  3288. $ref: "#/definitions/TLSConfiguration"
  3289. StartTLS:
  3290. type: "boolean"
  3291. example: true
  3292. description: "Whether LDAP connection should use StartTLS"
  3293. SearchSettings:
  3294. type: "array"
  3295. items:
  3296. $ref: "#/definitions/LDAPSearchSettings"
  3297. GroupSearchSettings:
  3298. type: "array"
  3299. items:
  3300. $ref: "#/definitions/LDAPGroupSearchSettings"
  3301. AutoCreateUsers:
  3302. type: "boolean"
  3303. example: true
  3304. description: "Automatically provision users and assign them to matching LDAP group names"
  3305. Settings:
  3306. type: "object"
  3307. properties:
  3308. TemplatesURL:
  3309. type: "string"
  3310. example: "https://raw.githubusercontent.com/portainer/templates/master/templates.json"
  3311. description: "URL to the templates that will be displayed in the UI when navigating\
  3312. \ to App Templates"
  3313. LogoURL:
  3314. type: "string"
  3315. example: "https://mycompany.mydomain.tld/logo.png"
  3316. description: "URL to a logo that will be displayed on the login page as well\
  3317. \ as on top of the sidebar. Will use default Portainer logo when value is\
  3318. \ empty string"
  3319. BlackListedLabels:
  3320. type: "array"
  3321. description: "A list of label name & value that will be used to hide containers\
  3322. \ when querying containers"
  3323. items:
  3324. $ref: "#/definitions/Settings_BlackListedLabels"
  3325. DisplayExternalContributors:
  3326. type: "boolean"
  3327. example: false
  3328. description: "Whether to display or not external templates contributions as\
  3329. \ sub-menus in the UI."
  3330. AuthenticationMethod:
  3331. type: "integer"
  3332. example: 1
  3333. description: "Active authentication method for the Portainer instance. Valid values are: 1 for managed or 2 for LDAP."
  3334. LDAPSettings:
  3335. $ref: "#/definitions/LDAPSettings"
  3336. AllowBindMountsForRegularUsers:
  3337. type: "boolean"
  3338. example: false
  3339. description: "Whether non-administrator should be able to use bind mounts when creating containers"
  3340. AllowPrivilegedModeForRegularUsers:
  3341. type: "boolean"
  3342. example: true
  3343. description: "Whether non-administrator should be able to use privileged mode when creating containers"
  3344. Settings_BlackListedLabels:
  3345. properties:
  3346. name:
  3347. type: "string"
  3348. example: "com.foo"
  3349. value:
  3350. type: "string"
  3351. example: "bar"
  3352. Pair:
  3353. properties:
  3354. name:
  3355. type: "string"
  3356. example: "name"
  3357. value:
  3358. type: "string"
  3359. example: "value"
  3360. Registry:
  3361. type: "object"
  3362. properties:
  3363. Id:
  3364. type: "integer"
  3365. example: 1
  3366. description: "Registry identifier"
  3367. Name:
  3368. type: "string"
  3369. example: "my-registry"
  3370. description: "Registry name"
  3371. URL:
  3372. type: "string"
  3373. example: "registry.mydomain.tld:2375"
  3374. description: "URL or IP address of the Docker registry"
  3375. Authentication:
  3376. type: "boolean"
  3377. example: true
  3378. description: "Is authentication against this registry enabled"
  3379. Username:
  3380. type: "string"
  3381. example: "registry_user"
  3382. description: "Username used to authenticate against this registry"
  3383. Password:
  3384. type: "string"
  3385. example: "registry_password"
  3386. description: "Password used to authenticate against this registry"
  3387. AuthorizedUsers:
  3388. type: "array"
  3389. description: "List of user identifiers authorized to use this registry"
  3390. items:
  3391. type: "integer"
  3392. example: 1
  3393. description: "User identifier"
  3394. AuthorizedTeams:
  3395. type: "array"
  3396. description: "List of team identifiers authorized to use this registry"
  3397. items:
  3398. type: "integer"
  3399. example: 1
  3400. description: "Team identifier"
  3401. RegistrySubset:
  3402. type: "object"
  3403. properties:
  3404. Id:
  3405. type: "integer"
  3406. example: 1
  3407. description: "Registry identifier"
  3408. Name:
  3409. type: "string"
  3410. example: "my-registry"
  3411. description: "Registry name"
  3412. URL:
  3413. type: "string"
  3414. example: "registry.mydomain.tld:2375"
  3415. description: "URL or IP address of the Docker registry"
  3416. Authentication:
  3417. type: "boolean"
  3418. example: true
  3419. description: "Is authentication against this registry enabled"
  3420. Username:
  3421. type: "string"
  3422. example: "registry_user"
  3423. description: "Username used to authenticate against this registry"
  3424. AuthorizedUsers:
  3425. type: "array"
  3426. description: "List of user identifiers authorized to use this registry"
  3427. items:
  3428. type: "integer"
  3429. example: 1
  3430. description: "User identifier"
  3431. AuthorizedTeams:
  3432. type: "array"
  3433. description: "List of team identifiers authorized to use this registry"
  3434. items:
  3435. type: "integer"
  3436. example: 1
  3437. description: "Team identifier"
  3438. EndpointGroup:
  3439. type: "object"
  3440. properties:
  3441. Id:
  3442. type: "integer"
  3443. example: 1
  3444. description: "Endpoint group identifier"
  3445. Name:
  3446. type: "string"
  3447. example: "my-endpoint-group"
  3448. description: "Endpoint group name"
  3449. Description:
  3450. type: "string"
  3451. example: "Description associated to the endpoint group"
  3452. description: "Endpoint group description"
  3453. AuthorizedUsers:
  3454. type: "array"
  3455. description: "List of user identifiers authorized to connect to this endpoint group. Will be inherited by endpoints that are part of the group"
  3456. items:
  3457. type: "integer"
  3458. example: 1
  3459. description: "User identifier"
  3460. AuthorizedTeams:
  3461. type: "array"
  3462. description: "List of team identifiers authorized to connect to this endpoint. Will be inherited by endpoints that are part of the group"
  3463. items:
  3464. type: "integer"
  3465. example: 1
  3466. description: "Team identifier"
  3467. Labels:
  3468. type: "array"
  3469. items:
  3470. $ref: "#/definitions/Pair"
  3471. Endpoint:
  3472. type: "object"
  3473. properties:
  3474. Id:
  3475. type: "integer"
  3476. example: 1
  3477. description: "Endpoint identifier"
  3478. Name:
  3479. type: "string"
  3480. example: "my-endpoint"
  3481. description: "Endpoint name"
  3482. Type:
  3483. type: "integer"
  3484. example: 1
  3485. description: "Endpoint environment type. 1 for a Docker environment, 2 for an agent on Docker environment or 3 for an Azure environment."
  3486. URL:
  3487. type: "string"
  3488. example: "docker.mydomain.tld:2375"
  3489. description: "URL or IP address of the Docker host associated to this endpoint"
  3490. PublicURL:
  3491. type: "string"
  3492. example: "docker.mydomain.tld:2375"
  3493. description: "URL or IP address where exposed containers will be reachable"
  3494. GroupID:
  3495. type: "integer"
  3496. example: 1
  3497. description: "Endpoint group identifier"
  3498. AuthorizedUsers:
  3499. type: "array"
  3500. description: "List of user identifiers authorized to connect to this endpoint"
  3501. items:
  3502. type: "integer"
  3503. example: 1
  3504. description: "User identifier"
  3505. AuthorizedTeams:
  3506. type: "array"
  3507. description: "List of team identifiers authorized to connect to this endpoint"
  3508. items:
  3509. type: "integer"
  3510. example: 1
  3511. description: "Team identifier"
  3512. TLSConfig:
  3513. $ref: "#/definitions/TLSConfiguration"
  3514. AzureCredentials:
  3515. $ref: "#/definitions/AzureCredentials"
  3516. EndpointSubset:
  3517. type: "object"
  3518. properties:
  3519. Id:
  3520. type: "integer"
  3521. example: 1
  3522. description: "Endpoint identifier"
  3523. Name:
  3524. type: "string"
  3525. example: "my-endpoint"
  3526. description: "Endpoint name"
  3527. Type:
  3528. type: "integer"
  3529. example: 1
  3530. description: "Endpoint environment type. 1 for a Docker environment, 2 for an agent on Docker environment, 3 for an Azure environment."
  3531. URL:
  3532. type: "string"
  3533. example: "docker.mydomain.tld:2375"
  3534. description: "URL or IP address of the Docker host associated to this endpoint"
  3535. PublicURL:
  3536. type: "string"
  3537. example: "docker.mydomain.tld:2375"
  3538. description: "URL or IP address where exposed containers will be reachable"
  3539. GroupID:
  3540. type: "integer"
  3541. example: 1
  3542. description: "Endpoint group identifier"
  3543. AuthorizedUsers:
  3544. type: "array"
  3545. description: "List of user identifiers authorized to connect to this endpoint"
  3546. items:
  3547. type: "integer"
  3548. example: 1
  3549. description: "User identifier"
  3550. AuthorizedTeams:
  3551. type: "array"
  3552. description: "List of team identifiers authorized to connect to this endpoint"
  3553. items:
  3554. type: "integer"
  3555. example: 1
  3556. description: "Team identifier"
  3557. TLSConfig:
  3558. $ref: "#/definitions/TLSConfiguration"
  3559. GenericError:
  3560. type: "object"
  3561. properties:
  3562. err:
  3563. type: "string"
  3564. example: "Something bad happened"
  3565. description: "Error message"
  3566. AuthenticateUserRequest:
  3567. type: "object"
  3568. required:
  3569. - "Password"
  3570. - "Username"
  3571. properties:
  3572. Username:
  3573. type: "string"
  3574. example: "admin"
  3575. description: "Username"
  3576. Password:
  3577. type: "string"
  3578. example: "mypassword"
  3579. description: "Password"
  3580. AuthenticateUserResponse:
  3581. type: "object"
  3582. properties:
  3583. jwt:
  3584. type: "string"
  3585. example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE"
  3586. description: "JWT token used to authenticate against the API"
  3587. DockerHubSubset:
  3588. type: "object"
  3589. properties:
  3590. Authentication:
  3591. type: "boolean"
  3592. example: true
  3593. description: "Is authentication against DockerHub enabled"
  3594. Username:
  3595. type: "string"
  3596. example: "hub_user"
  3597. description: "Username used to authenticate against the DockerHub"
  3598. DockerHub:
  3599. type: "object"
  3600. properties:
  3601. Authentication:
  3602. type: "boolean"
  3603. example: true
  3604. description: "Is authentication against DockerHub enabled"
  3605. Username:
  3606. type: "string"
  3607. example: "hub_user"
  3608. description: "Username used to authenticate against the DockerHub"
  3609. Password:
  3610. type: "string"
  3611. example: "hub_password"
  3612. description: "Password used to authenticate against the DockerHub"
  3613. ResourceControl:
  3614. type: "object"
  3615. properties:
  3616. ResourceID:
  3617. type: "string"
  3618. example: "617c5f22bb9b023d6daab7cba43a57576f83492867bc767d1c59416b065e5f08"
  3619. description: "Docker resource identifier on which access control will be applied.\
  3620. \ In the case of a resource control applied to a stack, use the stack name as identifier"
  3621. Type:
  3622. type: "string"
  3623. example: "container"
  3624. description: "Type of Docker resource. Valid values are: container, volume\
  3625. \ service, secret, config or stack"
  3626. Public:
  3627. type: "boolean"
  3628. example: true
  3629. description: "Permit access to the associated resource to any user"
  3630. Users:
  3631. type: "array"
  3632. description: "List of user identifiers with access to the associated resource"
  3633. items:
  3634. type: "integer"
  3635. example: 1
  3636. description: "User identifier"
  3637. Teams:
  3638. type: "array"
  3639. description: "List of team identifiers with access to the associated resource"
  3640. items:
  3641. type: "integer"
  3642. example: 1
  3643. description: "Team identifier"
  3644. SubResourceIDs:
  3645. type: "array"
  3646. description: "List of Docker resources that will inherit this access control"
  3647. items:
  3648. type: "string"
  3649. example: "617c5f22bb9b023d6daab7cba43a57576f83492867bc767d1c59416b065e5f08"
  3650. description: "Docker resource identifier"
  3651. DockerHubUpdateRequest:
  3652. type: "object"
  3653. required:
  3654. - "Authentication"
  3655. - "Password"
  3656. - "Username"
  3657. properties:
  3658. Authentication:
  3659. type: "boolean"
  3660. example: true
  3661. description: "Enable authentication against DockerHub"
  3662. Username:
  3663. type: "string"
  3664. example: "hub_user"
  3665. description: "Username used to authenticate against the DockerHub"
  3666. Password:
  3667. type: "string"
  3668. example: "hub_password"
  3669. description: "Password used to authenticate against the DockerHub"
  3670. EndpointListResponse:
  3671. type: "array"
  3672. items:
  3673. $ref: "#/definitions/EndpointSubset"
  3674. EndpointGroupListResponse:
  3675. type: "array"
  3676. items:
  3677. $ref: "#/definitions/EndpointGroup"
  3678. EndpointUpdateRequest:
  3679. type: "object"
  3680. properties:
  3681. Name:
  3682. type: "string"
  3683. example: "my-endpoint"
  3684. description: "Name that will be used to identify this endpoint"
  3685. URL:
  3686. type: "string"
  3687. example: "docker.mydomain.tld:2375"
  3688. description: "URL or IP address of a Docker host"
  3689. PublicURL:
  3690. type: "string"
  3691. example: "docker.mydomain.tld:2375"
  3692. description: "URL or IP address where exposed containers will be reachable.\
  3693. \ Defaults to URL if not specified"
  3694. GroupID:
  3695. type: "integer"
  3696. example: "1"
  3697. description: "Group identifier"
  3698. TLS:
  3699. type: "boolean"
  3700. example: true
  3701. description: "Require TLS to connect against this endpoint"
  3702. TLSSkipVerify:
  3703. type: "boolean"
  3704. example: false
  3705. description: "Skip server verification when using TLS"
  3706. TLSSkipClientVerify:
  3707. type: "boolean"
  3708. example: false
  3709. description: "Skip client verification when using TLS"
  3710. ApplicationID:
  3711. type: "string"
  3712. example: "eag7cdo9-o09l-9i83-9dO9-f0b23oe78db4"
  3713. description: "Azure application ID"
  3714. TenantID:
  3715. type: "string"
  3716. example: "34ddc78d-4fel-2358-8cc1-df84c8o839f5"
  3717. description: "Azure tenant ID"
  3718. AuthenticationKey:
  3719. type: "string"
  3720. example: "cOrXoK/1D35w8YQ8nH1/8ZGwzz45JIYD5jxHKXEQknk="
  3721. description: "Azure authentication key"
  3722. UserAccessPolicies:
  3723. $ref: "#/definitions/UserAccessPolicies"
  3724. TeamAccessPolicies:
  3725. $ref: "#/definitions/TeamAccessPolicies"
  3726. RegistryCreateRequest:
  3727. type: "object"
  3728. required:
  3729. - "Authentication"
  3730. - "Name"
  3731. - "Password"
  3732. - "Type"
  3733. - "URL"
  3734. - "Username"
  3735. properties:
  3736. Name:
  3737. type: "string"
  3738. example: "my-registry"
  3739. description: "Name that will be used to identify this registry"
  3740. Type:
  3741. type: "integer"
  3742. example: 1
  3743. description: "Registry Type. Valid values are: 1 (Quay.io), 2 (Azure container registry) or 3 (custom registry)"
  3744. URL:
  3745. type: "string"
  3746. example: "registry.mydomain.tld:2375"
  3747. description: "URL or IP address of the Docker registry"
  3748. Authentication:
  3749. type: "boolean"
  3750. example: true
  3751. description: "Is authentication against this registry enabled"
  3752. Username:
  3753. type: "string"
  3754. example: "registry_user"
  3755. description: "Username used to authenticate against this registry"
  3756. Password:
  3757. type: "string"
  3758. example: "registry_password"
  3759. description: "Password used to authenticate against this registry"
  3760. RegistryListResponse:
  3761. type: "array"
  3762. items:
  3763. $ref: "#/definitions/RegistrySubset"
  3764. RegistryUpdateRequest:
  3765. type: "object"
  3766. required:
  3767. - "Name"
  3768. - "URL"
  3769. properties:
  3770. Name:
  3771. type: "string"
  3772. example: "my-registry"
  3773. description: "Name that will be used to identify this registry"
  3774. URL:
  3775. type: "string"
  3776. example: "registry.mydomain.tld:2375"
  3777. description: "URL or IP address of the Docker registry"
  3778. Authentication:
  3779. type: "boolean"
  3780. example: true
  3781. description: "Is authentication against this registry enabled"
  3782. Username:
  3783. type: "string"
  3784. example: "registry_user"
  3785. description: "Username used to authenticate against this registry"
  3786. Password:
  3787. type: "string"
  3788. example: "registry_password"
  3789. description: "Password used to authenticate against this registry"
  3790. UserAccessPolicies:
  3791. $ref: "#/definitions/UserAccessPolicies"
  3792. TeamAccessPolicies:
  3793. $ref: "#/definitions/TeamAccessPolicies"
  3794. ResourceControlCreateRequest:
  3795. type: "object"
  3796. required:
  3797. - "ResourceID"
  3798. - "Type"
  3799. properties:
  3800. ResourceID:
  3801. type: "string"
  3802. example: "617c5f22bb9b023d6daab7cba43a57576f83492867bc767d1c59416b065e5f08"
  3803. description: "Docker resource identifier on which access control will be applied.\
  3804. \ In the case of a resource control applied to a stack, use the stack name as identifier"
  3805. Type:
  3806. type: "string"
  3807. example: "container"
  3808. description: "Type of Docker resource. Valid values are: container, volume\
  3809. \ service, secret, config or stack"
  3810. Public:
  3811. type: "boolean"
  3812. example: true
  3813. description: "Permit access to the associated resource to any user"
  3814. Users:
  3815. type: "array"
  3816. description: "List of user identifiers with access to the associated resource"
  3817. items:
  3818. type: "integer"
  3819. example: 1
  3820. description: "User identifier"
  3821. Teams:
  3822. type: "array"
  3823. description: "List of team identifiers with access to the associated resource"
  3824. items:
  3825. type: "integer"
  3826. example: 1
  3827. description: "Team identifier"
  3828. SubResourceIDs:
  3829. type: "array"
  3830. description: "List of Docker resources that will inherit this access control"
  3831. items:
  3832. type: "string"
  3833. example: "617c5f22bb9b023d6daab7cba43a57576f83492867bc767d1c59416b065e5f08"
  3834. description: "Docker resource identifier"
  3835. ResourceControlUpdateRequest:
  3836. type: "object"
  3837. properties:
  3838. Public:
  3839. type: "boolean"
  3840. example: false
  3841. description: "Permit access to the associated resource to any user"
  3842. Users:
  3843. type: "array"
  3844. description: "List of user identifiers with access to the associated resource"
  3845. items:
  3846. type: "integer"
  3847. example: 1
  3848. description: "User identifier"
  3849. Teams:
  3850. type: "array"
  3851. description: "List of team identifiers with access to the associated resource"
  3852. items:
  3853. type: "integer"
  3854. example: 1
  3855. description: "Team identifier"
  3856. SettingsUpdateRequest:
  3857. type: "object"
  3858. required:
  3859. - "TemplatesURL"
  3860. - "AuthenticationMethod"
  3861. properties:
  3862. TemplatesURL:
  3863. type: "string"
  3864. example: "https://raw.githubusercontent.com/portainer/templates/master/templates.json"
  3865. description: "URL to the templates that will be displayed in the UI when navigating\
  3866. \ to App Templates"
  3867. LogoURL:
  3868. type: "string"
  3869. example: "https://mycompany.mydomain.tld/logo.png"
  3870. description: "URL to a logo that will be displayed on the login page as well\
  3871. \ as on top of the sidebar. Will use default Portainer logo when value is\
  3872. \ empty string"
  3873. BlackListedLabels:
  3874. type: "array"
  3875. description: "A list of label name & value that will be used to hide containers\
  3876. \ when querying containers"
  3877. items:
  3878. $ref: "#/definitions/Settings_BlackListedLabels"
  3879. DisplayExternalContributors:
  3880. type: "boolean"
  3881. example: false
  3882. description: "Whether to display or not external templates contributions as\
  3883. \ sub-menus in the UI."
  3884. AuthenticationMethod:
  3885. type: "integer"
  3886. example: 1
  3887. description: "Active authentication method for the Portainer instance. Valid values are: 1 for managed or 2 for LDAP."
  3888. LDAPSettings:
  3889. $ref: "#/definitions/LDAPSettings"
  3890. AllowBindMountsForRegularUsers:
  3891. type: "boolean"
  3892. example: true
  3893. description: "Whether non-administrator users should be able to use bind mounts when creating containers"
  3894. AllowPrivilegedModeForRegularUsers:
  3895. type: "boolean"
  3896. example: true
  3897. description: "Whether non-administrator users should be able to use privileged mode when creating containers"
  3898. EdgeAgentCheckinInterval:
  3899. type: "integer"
  3900. example: "30"
  3901. description: "Polling interval for Edge agent (in seconds)"
  3902. EndpointGroupCreateRequest:
  3903. type: "object"
  3904. required:
  3905. - "Name"
  3906. properties:
  3907. Name:
  3908. type: "string"
  3909. example: "my-endpoint-group"
  3910. description: "Endpoint group name"
  3911. Description:
  3912. type: "string"
  3913. example: "Endpoint group description"
  3914. description: "Endpoint group description"
  3915. Labels:
  3916. type: "array"
  3917. items:
  3918. $ref: "#/definitions/Pair"
  3919. AssociatedEndpoints:
  3920. type: "array"
  3921. description: "List of endpoint identifiers that will be part of this group"
  3922. items:
  3923. type: "integer"
  3924. example: 1
  3925. description: "Endpoint identifier"
  3926. EndpointGroupUpdateRequest:
  3927. type: "object"
  3928. properties:
  3929. Name:
  3930. type: "string"
  3931. example: "my-endpoint-group"
  3932. description: "Endpoint group name"
  3933. Description:
  3934. type: "string"
  3935. example: "Endpoint group description"
  3936. description: "Endpoint group description"
  3937. Tags:
  3938. type: "array"
  3939. description: "List of tags associated to the endpoint group"
  3940. items:
  3941. type: "string"
  3942. example: "zone/east-coast"
  3943. description: "Tag"
  3944. UserAccessPolicies:
  3945. $ref: "#/definitions/UserAccessPolicies"
  3946. TeamAccessPolicies:
  3947. $ref: "#/definitions/TeamAccessPolicies"
  3948. UserCreateRequest:
  3949. type: "object"
  3950. required:
  3951. - "Password"
  3952. - "Role"
  3953. - "Username"
  3954. properties:
  3955. Username:
  3956. type: "string"
  3957. example: "bob"
  3958. description: "Username"
  3959. Password:
  3960. type: "string"
  3961. example: "cg9Wgky3"
  3962. description: "Password"
  3963. Role:
  3964. type: "integer"
  3965. example: 1
  3966. description: "User role (1 for administrator account and 2 for regular account)"
  3967. UserListResponse:
  3968. type: "array"
  3969. items:
  3970. $ref: "#/definitions/UserSubset"
  3971. UserUpdateRequest:
  3972. type: "object"
  3973. properties:
  3974. Password:
  3975. type: "string"
  3976. example: "cg9Wgky3"
  3977. description: "Password"
  3978. Role:
  3979. type: "integer"
  3980. example: 1
  3981. description: "User role (1 for administrator account and 2 for regular account)"
  3982. UserMembershipsResponse:
  3983. type: "array"
  3984. items:
  3985. $ref: "#/definitions/TeamMembership"
  3986. UserPasswordCheckRequest:
  3987. type: "object"
  3988. required:
  3989. - "Password"
  3990. properties:
  3991. Password:
  3992. type: "string"
  3993. example: "cg9Wgky3"
  3994. description: "Password"
  3995. UserPasswordCheckResponse:
  3996. type: "object"
  3997. properties:
  3998. valid:
  3999. type: "boolean"
  4000. example: true
  4001. description: "Is the password valid"
  4002. TagListResponse:
  4003. type: "array"
  4004. items:
  4005. $ref: "#/definitions/Tag"
  4006. TagCreateRequest:
  4007. type: "object"
  4008. required:
  4009. - "Name"
  4010. properties:
  4011. Name:
  4012. type: "string"
  4013. example: "org/acme"
  4014. description: "Name"
  4015. TeamCreateRequest:
  4016. type: "object"
  4017. required:
  4018. - "Name"
  4019. properties:
  4020. Name:
  4021. type: "string"
  4022. example: "developers"
  4023. description: "Name"
  4024. TeamListResponse:
  4025. type: "array"
  4026. items:
  4027. $ref: "#/definitions/Team"
  4028. TeamUpdateRequest:
  4029. type: "object"
  4030. required:
  4031. - "Name"
  4032. properties:
  4033. Name:
  4034. type: "string"
  4035. example: "developers"
  4036. description: "Name"
  4037. TeamMembershipsResponse:
  4038. type: "array"
  4039. items:
  4040. $ref: "#/definitions/TeamMembership"
  4041. TeamMembershipCreateRequest:
  4042. type: "object"
  4043. required:
  4044. - "UserID"
  4045. - "TeamID"
  4046. - "Role"
  4047. properties:
  4048. UserID:
  4049. type: "integer"
  4050. example: 1
  4051. description: "User identifier"
  4052. TeamID:
  4053. type: "integer"
  4054. example: 1
  4055. description: "Team identifier"
  4056. Role:
  4057. type: "integer"
  4058. example: 1
  4059. description: "Role for the user inside the team (1 for leader and 2 for regular member)"
  4060. TeamMembershipListResponse:
  4061. type: "array"
  4062. items:
  4063. $ref: "#/definitions/TeamMembership"
  4064. TeamMembershipUpdateRequest:
  4065. type: "object"
  4066. required:
  4067. - "UserID"
  4068. - "TeamID"
  4069. - "Role"
  4070. properties:
  4071. UserID:
  4072. type: "integer"
  4073. example: 1
  4074. description: "User identifier"
  4075. TeamID:
  4076. type: "integer"
  4077. example: 1
  4078. description: "Team identifier"
  4079. Role:
  4080. type: "integer"
  4081. example: 1
  4082. description: "Role for the user inside the team (1 for leader and 2 for regular member)"
  4083. SettingsLDAPCheckRequest:
  4084. type: "object"
  4085. properties:
  4086. LDAPSettings:
  4087. $ref: "#/definitions/LDAPSettings"
  4088. UserAdminInitRequest:
  4089. type: "object"
  4090. properties:
  4091. Username:
  4092. type: "string"
  4093. example: "admin"
  4094. description: "Username for the admin user"
  4095. Password:
  4096. type: "string"
  4097. example: "admin-password"
  4098. description: "Password for the admin user"
  4099. TemplateListResponse:
  4100. type: "array"
  4101. items:
  4102. $ref: "#/definitions/Template"
  4103. TemplateCreateRequest:
  4104. type: "object"
  4105. required:
  4106. - "type"
  4107. - "title"
  4108. - "description"
  4109. properties:
  4110. type:
  4111. type: "integer"
  4112. example: 1
  4113. description: "Template type. Valid values are: 1 (container), 2 (Swarm stack) or 3 (Compose stack)"
  4114. title:
  4115. type: "string"
  4116. example: "Nginx"
  4117. description: "Title of the template"
  4118. description:
  4119. type: "string"
  4120. example: "High performance web server"
  4121. description: "Description of the template"
  4122. administrator_only:
  4123. type: "boolean"
  4124. example: true
  4125. description: "Whether the template should be available to administrators only"
  4126. image:
  4127. type: "string"
  4128. example: "nginx:latest"
  4129. description: "Image associated to a container template. Mandatory for a container template"
  4130. repository:
  4131. $ref: "#/definitions/TemplateRepository"
  4132. name:
  4133. type: "string"
  4134. example: "mystackname"
  4135. description: "Default name for the stack/container to be used on deployment"
  4136. logo:
  4137. type: "string"
  4138. example: "https://cloudinovasi.id/assets/img/logos/nginx.png"
  4139. description: "URL of the template's logo"
  4140. env:
  4141. type: "array"
  4142. description: "A list of environment variables used during the template deployment"
  4143. items:
  4144. $ref: "#/definitions/TemplateEnv"
  4145. note:
  4146. type: "string"
  4147. example: "This is my <b>custom</b> template"
  4148. description: "A note that will be displayed in the UI. Supports HTML content"
  4149. platform:
  4150. type: "string"
  4151. example: "linux"
  4152. description: "Platform associated to the template. Valid values are: 'linux', 'windows' or leave empty for multi-platform"
  4153. categories:
  4154. type: "array"
  4155. description: "A list of categories associated to the template"
  4156. items:
  4157. type: "string"
  4158. example: "database"
  4159. registry:
  4160. type: "string"
  4161. example: "quay.io"
  4162. description: "The URL of a registry associated to the image for a container template"
  4163. command:
  4164. type: "string"
  4165. example: "ls -lah"
  4166. description: "The command that will be executed in a container template"
  4167. network:
  4168. type: "string"
  4169. example: "mynet"
  4170. description: "Name of a network that will be used on container deployment if it exists inside the environment"
  4171. volumes:
  4172. type: "array"
  4173. description: "A list of volumes used during the container template deployment"
  4174. items:
  4175. $ref: "#/definitions/TemplateVolume"
  4176. ports:
  4177. type: "array"
  4178. description: "A list of ports exposed by the container"
  4179. items:
  4180. type: "string"
  4181. example: "8080:80/tcp"
  4182. labels:
  4183. type: "array"
  4184. description: "Container labels"
  4185. items:
  4186. $ref: '#/definitions/Pair'
  4187. privileged:
  4188. type: "boolean"
  4189. example: true
  4190. description: "Whether the container should be started in privileged mode"
  4191. interactive:
  4192. type: "boolean"
  4193. example: true
  4194. description: "Whether the container should be started in interactive mode (-i -t equivalent on the CLI)"
  4195. restart_policy:
  4196. type: "string"
  4197. example: "on-failure"
  4198. description: "Container restart policy"
  4199. hostname:
  4200. type: "string"
  4201. example: "mycontainer"
  4202. description: "Container hostname"
  4203. TemplateUpdateRequest:
  4204. type: "object"
  4205. properties:
  4206. type:
  4207. type: "integer"
  4208. example: 1
  4209. description: "Template type. Valid values are: 1 (container), 2 (Swarm stack) or 3 (Compose stack)"
  4210. title:
  4211. type: "string"
  4212. example: "Nginx"
  4213. description: "Title of the template"
  4214. description:
  4215. type: "string"
  4216. example: "High performance web server"
  4217. description: "Description of the template"
  4218. administrator_only:
  4219. type: "boolean"
  4220. example: true
  4221. description: "Whether the template should be available to administrators only"
  4222. image:
  4223. type: "string"
  4224. example: "nginx:latest"
  4225. description: "Image associated to a container template. Mandatory for a container template"
  4226. repository:
  4227. $ref: "#/definitions/TemplateRepository"
  4228. name:
  4229. type: "string"
  4230. example: "mystackname"
  4231. description: "Default name for the stack/container to be used on deployment"
  4232. logo:
  4233. type: "string"
  4234. example: "https://cloudinovasi.id/assets/img/logos/nginx.png"
  4235. description: "URL of the template's logo"
  4236. env:
  4237. type: "array"
  4238. description: "A list of environment variables used during the template deployment"
  4239. items:
  4240. $ref: "#/definitions/TemplateEnv"
  4241. note:
  4242. type: "string"
  4243. example: "This is my <b>custom</b> template"
  4244. description: "A note that will be displayed in the UI. Supports HTML content"
  4245. platform:
  4246. type: "string"
  4247. example: "linux"
  4248. description: "Platform associated to the template. Valid values are: 'linux', 'windows' or leave empty for multi-platform"
  4249. categories:
  4250. type: "array"
  4251. description: "A list of categories associated to the template"
  4252. items:
  4253. type: "string"
  4254. example: "database"
  4255. registry:
  4256. type: "string"
  4257. example: "quay.io"
  4258. description: "The URL of a registry associated to the image for a container template"
  4259. command:
  4260. type: "string"
  4261. example: "ls -lah"
  4262. description: "The command that will be executed in a container template"
  4263. network:
  4264. type: "string"
  4265. example: "mynet"
  4266. description: "Name of a network that will be used on container deployment if it exists inside the environment"
  4267. volumes:
  4268. type: "array"
  4269. description: "A list of volumes used during the container template deployment"
  4270. items:
  4271. $ref: "#/definitions/TemplateVolume"
  4272. ports:
  4273. type: "array"
  4274. description: "A list of ports exposed by the container"
  4275. items:
  4276. type: "string"
  4277. example: "8080:80/tcp"
  4278. labels:
  4279. type: "array"
  4280. description: "Container labels"
  4281. items:
  4282. $ref: '#/definitions/Pair'
  4283. privileged:
  4284. type: "boolean"
  4285. example: true
  4286. description: "Whether the container should be started in privileged mode"
  4287. interactive:
  4288. type: "boolean"
  4289. example: true
  4290. description: "Whether the container should be started in interactive mode (-i -t equivalent on the CLI)"
  4291. restart_policy:
  4292. type: "string"
  4293. example: "on-failure"
  4294. description: "Container restart policy"
  4295. hostname:
  4296. type: "string"
  4297. example: "mycontainer"
  4298. description: "Container hostname"
  4299. Template:
  4300. type: "object"
  4301. properties:
  4302. id:
  4303. type: "integer"
  4304. example: 1
  4305. description: "Template identifier"
  4306. type:
  4307. type: "integer"
  4308. example: 1
  4309. description: "Template type. Valid values are: 1 (container), 2 (Swarm stack) or 3 (Compose stack)"
  4310. title:
  4311. type: "string"
  4312. example: "Nginx"
  4313. description: "Title of the template"
  4314. description:
  4315. type: "string"
  4316. example: "High performance web server"
  4317. description: "Description of the template"
  4318. administrator_only:
  4319. type: "boolean"
  4320. example: true
  4321. description: "Whether the template should be available to administrators only"
  4322. image:
  4323. type: "string"
  4324. example: "nginx:latest"
  4325. description: "Image associated to a container template. Mandatory for a container template"
  4326. repository:
  4327. $ref: "#/definitions/TemplateRepository"
  4328. name:
  4329. type: "string"
  4330. example: "mystackname"
  4331. description: "Default name for the stack/container to be used on deployment"
  4332. logo:
  4333. type: "string"
  4334. example: "https://cloudinovasi.id/assets/img/logos/nginx.png"
  4335. description: "URL of the template's logo"
  4336. env:
  4337. type: "array"
  4338. description: "A list of environment variables used during the template deployment"
  4339. items:
  4340. $ref: "#/definitions/TemplateEnv"
  4341. note:
  4342. type: "string"
  4343. example: "This is my <b>custom</b> template"
  4344. description: "A note that will be displayed in the UI. Supports HTML content"
  4345. platform:
  4346. type: "string"
  4347. example: "linux"
  4348. description: "Platform associated to the template. Valid values are: 'linux', 'windows' or leave empty for multi-platform"
  4349. categories:
  4350. type: "array"
  4351. description: "A list of categories associated to the template"
  4352. items:
  4353. type: "string"
  4354. example: "database"
  4355. registry:
  4356. type: "string"
  4357. example: "quay.io"
  4358. description: "The URL of a registry associated to the image for a container template"
  4359. command:
  4360. type: "string"
  4361. example: "ls -lah"
  4362. description: "The command that will be executed in a container template"
  4363. network:
  4364. type: "string"
  4365. example: "mynet"
  4366. description: "Name of a network that will be used on container deployment if it exists inside the environment"
  4367. volumes:
  4368. type: "array"
  4369. description: "A list of volumes used during the container template deployment"
  4370. items:
  4371. $ref: "#/definitions/TemplateVolume"
  4372. ports:
  4373. type: "array"
  4374. description: "A list of ports exposed by the container"
  4375. items:
  4376. type: "string"
  4377. example: "8080:80/tcp"
  4378. labels:
  4379. type: "array"
  4380. description: "Container labels"
  4381. items:
  4382. $ref: '#/definitions/Pair'
  4383. privileged:
  4384. type: "boolean"
  4385. example: true
  4386. description: "Whether the container should be started in privileged mode"
  4387. interactive:
  4388. type: "boolean"
  4389. example: true
  4390. description: "Whether the container should be started in interactive mode (-i -t equivalent on the CLI)"
  4391. restart_policy:
  4392. type: "string"
  4393. example: "on-failure"
  4394. description: "Container restart policy"
  4395. hostname:
  4396. type: "string"
  4397. example: "mycontainer"
  4398. description: "Container hostname"
  4399. TemplateVolume:
  4400. type: "object"
  4401. properties:
  4402. container:
  4403. type: "string"
  4404. example: "/data"
  4405. description: "Path inside the container"
  4406. bind:
  4407. type: "string"
  4408. example: "/tmp"
  4409. description: "Path on the host"
  4410. readonly:
  4411. type: "boolean"
  4412. example: true
  4413. description: "Whether the volume used should be readonly"
  4414. TemplateEnv:
  4415. type: "object"
  4416. properties:
  4417. name:
  4418. type: "string"
  4419. example: "MYSQL_ROOT_PASSWORD"
  4420. description: "name of the environment variable"
  4421. label:
  4422. type: "string"
  4423. example: "Root password"
  4424. description: "Text for the label that will be generated in the UI"
  4425. description:
  4426. type: "string"
  4427. example: "MySQL root account password"
  4428. description: "Content of the tooltip that will be generated in the UI"
  4429. default:
  4430. type: "string"
  4431. example: "default_value"
  4432. description: "Default value that will be set for the variable"
  4433. preset:
  4434. type: "boolean"
  4435. example: true
  4436. description: "If set to true, will not generate any input for this variable in the UI"
  4437. select:
  4438. type: "array"
  4439. description: "A list of name/value that will be used to generate a dropdown in the UI"
  4440. items:
  4441. $ref: '#/definitions/TemplateEnvSelect'
  4442. TemplateEnvSelect:
  4443. type: "object"
  4444. properties:
  4445. text:
  4446. type: "string"
  4447. example: "text value"
  4448. description: "Some text that will displayed as a choice"
  4449. value:
  4450. type: "string"
  4451. example: "value"
  4452. description: "A value that will be associated to the choice"
  4453. default:
  4454. type: "boolean"
  4455. example: true
  4456. description: "Will set this choice as the default choice"
  4457. TemplateRepository:
  4458. type: "object"
  4459. required:
  4460. - "URL"
  4461. properties:
  4462. URL:
  4463. type: "string"
  4464. example: "https://github.com/portainer/portainer-compose"
  4465. description: "URL of a git repository used to deploy a stack template. Mandatory for a Swarm/Compose stack template"
  4466. stackfile:
  4467. type: "string"
  4468. example: "./subfolder/docker-compose.yml"
  4469. description: "Path to the stack file inside the git repository"
  4470. StackMigrateRequest:
  4471. type: "object"
  4472. required:
  4473. - "EndpointID"
  4474. properties:
  4475. EndpointID:
  4476. type: "integer"
  4477. example: 2
  4478. description: "Endpoint identifier of the target endpoint where the stack will be relocated"
  4479. SwarmID:
  4480. type: "string"
  4481. example: "jpofkc0i9uo9wtx1zesuk649w"
  4482. description: "Swarm cluster identifier, must match the identifier of the cluster where the stack will be relocated"
  4483. Name:
  4484. type: "string"
  4485. example: "new-stack"
  4486. description: "If provided will rename the migrated stack"
  4487. EndpointJobRequest:
  4488. type: "object"
  4489. required:
  4490. - "Image"
  4491. - "FileContent"
  4492. properties:
  4493. Image:
  4494. type: "string"
  4495. example: "ubuntu:latest"
  4496. description: "Container image which will be used to execute the job"
  4497. FileContent:
  4498. type: "string"
  4499. example: "ls -lah /host/tmp"
  4500. description: "Content of the job script"
  4501. StackCreateRequest:
  4502. type: "object"
  4503. required:
  4504. - "Name"
  4505. properties:
  4506. Name:
  4507. type: "string"
  4508. example: "myStack"
  4509. description: "Name of the stack"
  4510. SwarmID:
  4511. type: "string"
  4512. example: "jpofkc0i9uo9wtx1zesuk649w"
  4513. description: "Swarm cluster identifier. Required when creating a Swarm stack (type 1)."
  4514. StackFileContent:
  4515. type: "string"
  4516. example: "version: 3\n services:\n web:\n image:nginx"
  4517. description: "Content of the Stack file. Required when using the 'string' deployment method."
  4518. RepositoryURL:
  4519. type: "string"
  4520. example: "https://github.com/openfaas/faas"
  4521. description: "URL of a Git repository hosting the Stack file. Required when using the 'repository' deployment method."
  4522. RepositoryReferenceName:
  4523. type: "string"
  4524. example: "refs/heads/master"
  4525. description: "Reference name of a Git repository hosting the Stack file. Used in 'repository' deployment method."
  4526. ComposeFilePathInRepository:
  4527. type: "string"
  4528. example: "docker-compose.yml"
  4529. description: "Path to the Stack file inside the Git repository. Will default to 'docker-compose.yml' if not specified."
  4530. RepositoryAuthentication:
  4531. type: "boolean"
  4532. example: true
  4533. description: "Use basic authentication to clone the Git repository."
  4534. RepositoryUsername:
  4535. type: "string"
  4536. example: "myGitUsername"
  4537. description: "Username used in basic authentication. Required when RepositoryAuthentication is true."
  4538. RepositoryPassword:
  4539. type: "string"
  4540. example: "myGitPassword"
  4541. description: "Password used in basic authentication. Required when RepositoryAuthentication is true."
  4542. Env:
  4543. type: "array"
  4544. description: "A list of environment variables used during stack deployment"
  4545. items:
  4546. $ref: "#/definitions/Stack_Env"
  4547. Stack_Env:
  4548. properties:
  4549. name:
  4550. type: "string"
  4551. example: "MYSQL_ROOT_PASSWORD"
  4552. value:
  4553. type: "string"
  4554. example: "password"
  4555. StackListResponse:
  4556. type: "array"
  4557. items:
  4558. $ref: "#/definitions/Stack"
  4559. Stack:
  4560. type: "object"
  4561. properties:
  4562. Id:
  4563. type: "string"
  4564. example: "myStack_jpofkc0i9uo9wtx1zesuk649w"
  4565. description: "Stack identifier"
  4566. Name:
  4567. type: "string"
  4568. example: "myStack"
  4569. description: "Stack name"
  4570. Type:
  4571. type: "integer"
  4572. example: "1"
  4573. description: "Stack type. 1 for a Swarm stack, 2 for a Compose stack"
  4574. EndpointID:
  4575. type: "integer"
  4576. example: "1"
  4577. description: "Endpoint identifier. Reference the endpoint that will be used for deployment "
  4578. EntryPoint:
  4579. type: "string"
  4580. example: "docker-compose.yml"
  4581. description: "Path to the Stack file"
  4582. SwarmID:
  4583. type: "string"
  4584. example: "jpofkc0i9uo9wtx1zesuk649w"
  4585. description: "Cluster identifier of the Swarm cluster where the stack is deployed"
  4586. ProjectPath:
  4587. type: "string"
  4588. example: "/data/compose/myStack_jpofkc0i9uo9wtx1zesuk649w"
  4589. description: "Path on disk to the repository hosting the Stack file"
  4590. Env:
  4591. type: "array"
  4592. description: "A list of environment variables used during stack deployment"
  4593. items:
  4594. $ref: "#/definitions/Stack_Env"
  4595. StackUpdateRequest:
  4596. type: "object"
  4597. properties:
  4598. StackFileContent:
  4599. type: "string"
  4600. example: "version: 3\n services:\n web:\n image:nginx"
  4601. description: "New content of the Stack file."
  4602. Env:
  4603. type: "array"
  4604. description: "A list of environment variables used during stack deployment"
  4605. items:
  4606. $ref: "#/definitions/Stack_Env"
  4607. Prune:
  4608. type: "boolean"
  4609. example: false
  4610. description: "Prune services that are no longer referenced (only available for Swarm stacks)"
  4611. StackFileInspectResponse:
  4612. type: "object"
  4613. properties:
  4614. StackFileContent:
  4615. type: "string"
  4616. example: "version: 3\n services:\n web:\n image:nginx"
  4617. description: "Content of the Stack file."
  4618. LicenseInformation:
  4619. type: "object"
  4620. properties:
  4621. LicenseKey:
  4622. type: "string"
  4623. description: "License key"
  4624. example: "1-uKmVwboSWVIZv5URmE0VRkpbPX0rrCVeDxJl97LZ0piltw2SU28DSrNwPZAHCEAwB2SeKm6BCFcVwzGMBEixKQ"
  4625. Company:
  4626. type: "string"
  4627. description: "Company associated to the license"
  4628. example: "Portainer.io"
  4629. Expiration:
  4630. type: "string"
  4631. description: "License expiry date"
  4632. example: "2077-07-07"
  4633. Valid:
  4634. type: "boolean"
  4635. description: "Is the license valid"
  4636. example: "true"
  4637. Extension:
  4638. type: "object"
  4639. properties:
  4640. Id:
  4641. type: "integer"
  4642. example: 1
  4643. description: "Extension identifier"
  4644. Name:
  4645. type: "string"
  4646. example: "Registry Manager"
  4647. description: "Extension name"
  4648. Enabled:
  4649. type: "boolean"
  4650. example: "true"
  4651. description: "Is the extension enabled"
  4652. ShortDescription:
  4653. type: "string"
  4654. description: "Short description about the extension"
  4655. example: "Enable in-app registry management"
  4656. DescriptionURL:
  4657. type: "string"
  4658. description: "URL to the file containing the extension description"
  4659. example: https://portainer-io-assets.sfo2.digitaloceanspaces.com/description_registry_manager.html"
  4660. Available:
  4661. type: "boolean"
  4662. description: "Is the extension available for download and activation"
  4663. example: "true"
  4664. Images:
  4665. type: "array"
  4666. description: "List of screenshot URLs"
  4667. items:
  4668. type: "string"
  4669. example: "https://portainer-io-assets.sfo2.digitaloceanspaces.com/screenshots/rm01.png"
  4670. description: "Screenshot URL"
  4671. Logo:
  4672. type: "string"
  4673. description: "Icon associated to the extension"
  4674. example: "fa-database"
  4675. Price:
  4676. type: "string"
  4677. description: "Extension price"
  4678. example: "US$9.95"
  4679. PriceDescription:
  4680. type: "string"
  4681. description: "Details about extension pricing"
  4682. example: "Price per instance per year"
  4683. ShopURL:
  4684. type: "string"
  4685. description: "URL used to buy the extension"
  4686. example: "https://portainer.io/checkout/?add-to-cart=1164"
  4687. UpdateAvailable:
  4688. type: "boolean"
  4689. description: "Is an update available for this extension"
  4690. example: "true"
  4691. Version:
  4692. type: "string"
  4693. description: "Extension version"
  4694. example: "1.0.0"
  4695. License:
  4696. $ref: "#/definitions/LicenseInformation"
  4697. ExtensionListResponse:
  4698. type: "array"
  4699. items:
  4700. $ref: "#/definitions/Extension"
  4701. ExtensionCreateRequest:
  4702. type: "object"
  4703. required:
  4704. - "License"
  4705. properties:
  4706. License:
  4707. type: "string"
  4708. example: "1-uKmVwboSWVIZv5URmE0VRkpbPX0rrCVeDxJl97LZ0piltw2SU28DSrNwPZAHCEAwB2SeKm6BCFcVwzGMBEixKQ"
  4709. description: "License key"
  4710. ExtensionUpdateRequest:
  4711. type: "object"
  4712. required:
  4713. - "Version"
  4714. properties:
  4715. Version:
  4716. type: "string"
  4717. example: "1.1.0"
  4718. description: "New version of the extension"
  4719. RoleListResponse:
  4720. type: "array"
  4721. items:
  4722. $ref: "#/definitions/Role"
  4723. Role:
  4724. type: "object"
  4725. properties:
  4726. Id:
  4727. type: "integer"
  4728. description: "Role identifier"
  4729. example: 2
  4730. Name:
  4731. type: "string"
  4732. description: "Role name"
  4733. example: "HelpDesk"
  4734. Description:
  4735. type: "string"
  4736. description: "Role description"
  4737. example: "Read-only access of all resources in an endpoint"
  4738. Authorizations:
  4739. $ref: "#/definitions/Authorizations"
  4740. Authorizations:
  4741. type: "object"
  4742. description: "Authorizations associated to a role"
  4743. additionalProperties:
  4744. type: "object"
  4745. properties:
  4746. authorization:
  4747. type: "string"
  4748. value:
  4749. type: "boolean"
  4750. example:
  4751. "DockerContainerList": true
  4752. "DockerVolumeList": true