openapi: 3.1.0
info:
  title: Coolify Applications Services API
  version: '0.1'
  description: Applications
servers:
- url: https://app.coolify.io/api/v1
  description: Coolify Cloud API. Change the host to your own instance if you are self-hosting.
tags:
- name: Services
  description: Services
paths:
  /services:
    get:
      tags:
      - Services
      summary: List
      description: List all services.
      operationId: list-services
      responses:
        '200':
          description: Get all services
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
      security:
      - bearerAuth: []
    post:
      tags:
      - Services
      summary: Create service
      description: Create a one-click / custom service
      operationId: create-service
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - server_uuid
              - project_uuid
              - environment_name
              - environment_uuid
              properties:
                type:
                  description: The one-click service type (e.g. "actualbudget", "calibre-web", "gitea-with-mysql" ...)
                  type: string
                name:
                  type: string
                  maxLength: 255
                  description: Name of the service.
                description:
                  type: string
                  nullable: true
                  description: Description of the service.
                project_uuid:
                  type: string
                  description: Project UUID.
                environment_name:
                  type: string
                  description: Environment name. You need to provide at least one of environment_name or environment_uuid.
                environment_uuid:
                  type: string
                  description: Environment UUID. You need to provide at least one of environment_name or environment_uuid.
                server_uuid:
                  type: string
                  description: Server UUID.
                destination_uuid:
                  type: string
                  description: Destination UUID. Required if server has multiple destinations.
                instant_deploy:
                  type: boolean
                  default: false
                  description: Start the service immediately after creation.
                docker_compose_raw:
                  type: string
                  description: The base64 encoded Docker Compose content.
                urls:
                  type: array
                  description: Array of URLs to be applied to containers of a service.
                  items:
                    properties:
                      name:
                        type: string
                        description: The service name as defined in docker-compose.
                      url:
                        type: string
                        description: Comma-separated list of URLs (e.g. "https://app.coolify.io,https://app2.coolify.io").
                    type: object
                force_domain_override:
                  type: boolean
                  default: false
                  description: Force domain override even if conflicts are detected.
                is_container_label_escape_enabled:
                  type: boolean
                  default: true
                  description: Escape special characters in labels. By default, $ (and other chars) is escaped. If you want to use env variables inside the labels, turn this off.
              type: object
      responses:
        '201':
          description: Service created successfully.
          content:
            application/json:
              schema:
                properties:
                  uuid:
                    type: string
                    description: Service UUID.
                  domains:
                    type: array
                    items:
                      type: string
                    description: Service domains.
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '409':
          description: Domain conflicts detected.
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: Domain conflicts detected. Use force_domain_override=true to proceed.
                  warning:
                    type: string
                    example: Using the same domain for multiple resources can cause routing conflicts and unpredictable behavior.
                  conflicts:
                    type: array
                    items:
                      properties:
                        domain:
                          type: string
                          example: example.com
                        resource_name:
                          type: string
                          example: My Application
                        resource_uuid:
                          type: string
                          nullable: true
                          example: abc123-def456
                        resource_type:
                          type: string
                          enum:
                          - application
                          - service
                          - instance
                          example: application
                        message:
                          type: string
                          example: Domain example.com is already in use by application 'My Application'
                      type: object
                type: object
        '422':
          $ref: '#/components/responses/422'
      security:
      - bearerAuth: []
  /services/{uuid}:
    get:
      tags:
      - Services
      summary: Get
      description: Get service by UUID.
      operationId: get-service-by-uuid
      parameters:
      - name: uuid
        in: path
        description: Service UUID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Get a service by UUID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
      security:
      - bearerAuth: []
    delete:
      tags:
      - Services
      summary: Delete
      description: Delete service by UUID.
      operationId: delete-service-by-uuid
      parameters:
      - name: uuid
        in: path
        description: Service UUID
        required: true
        schema:
          type: string
      - name: delete_configurations
        in: query
        description: Delete configurations.
        required: false
        schema:
          type: boolean
          default: true
      - name: delete_volumes
        in: query
        description: Delete volumes.
        required: false
        schema:
          type: boolean
          default: true
      - name: docker_cleanup
        in: query
        description: Run docker cleanup.
        required: false
        schema:
          type: boolean
          default: true
      - name: delete_connected_networks
        in: query
        description: Delete connected networks.
        required: false
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Delete a service by UUID
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: Service deletion request queued.
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
      security:
      - bearerAuth: []
    patch:
      tags:
      - Services
      summary: Update
      description: Update service by UUID.
      operationId: update-service-by-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      requestBody:
        description: Service updated.
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                  description: The service name.
                description:
                  type: string
                  description: The service description.
                project_uuid:
                  type: string
                  description: The project UUID.
                environment_name:
                  type: string
                  description: The environment name.
                environment_uuid:
                  type: string
                  description: The environment UUID.
                server_uuid:
                  type: string
                  description: The server UUID.
                destination_uuid:
                  type: string
                  description: The destination UUID.
                instant_deploy:
                  type: boolean
                  description: The flag to indicate if the service should be deployed instantly.
                connect_to_docker_network:
                  type: boolean
                  default: false
                  description: Connect the service to the predefined docker network.
                docker_compose_raw:
                  type: string
                  description: The base64 encoded Docker Compose content.
                urls:
                  type: array
                  description: Array of URLs to be applied to containers of a service.
                  items:
                    properties:
                      name:
                        type: string
                        description: The service name as defined in docker-compose.
                      url:
                        type: string
                        description: Comma-separated list of URLs (e.g. "https://app.coolify.io,https://app2.coolify.io").
                    type: object
                force_domain_override:
                  type: boolean
                  default: false
                  description: Force domain override even if conflicts are detected.
                is_container_label_escape_enabled:
                  type: boolean
                  default: true
                  description: Escape special characters in labels. By default, $ (and other chars) is escaped. If you want to use env variables inside the labels, turn this off.
              type: object
      responses:
        '200':
          description: Service updated.
          content:
            application/json:
              schema:
                properties:
                  uuid:
                    type: string
                    description: Service UUID.
                  domains:
                    type: array
                    items:
                      type: string
                    description: Service domains.
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '409':
          description: Domain conflicts detected.
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: Domain conflicts detected. Use force_domain_override=true to proceed.
                  warning:
                    type: string
                    example: Using the same domain for multiple resources can cause routing conflicts and unpredictable behavior.
                  conflicts:
                    type: array
                    items:
                      properties:
                        domain:
                          type: string
                          example: example.com
                        resource_name:
                          type: string
                          example: My Application
                        resource_uuid:
                          type: string
                          nullable: true
                          example: abc123-def456
                        resource_type:
                          type: string
                          enum:
                          - application
                          - service
                          - instance
                          example: application
                        message:
                          type: string
                          example: Domain example.com is already in use by application 'My Application'
                      type: object
                type: object
        '422':
          $ref: '#/components/responses/422'
      security:
      - bearerAuth: []
  /services/{uuid}/envs:
    get:
      tags:
      - Services
      summary: List Envs
      description: List all envs by service UUID.
      operationId: list-envs-by-service-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: All environment variables by service UUID.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EnvironmentVariable'
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
      security:
      - bearerAuth: []
    post:
      tags:
      - Services
      summary: Create Env
      description: Create env by service UUID.
      operationId: create-env-by-service-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      requestBody:
        description: Env created.
        required: true
        content:
          application/json:
            schema:
              properties:
                key:
                  type: string
                  description: The key of the environment variable.
                value:
                  type: string
                  description: The value of the environment variable.
                is_preview:
                  type: boolean
                  description: The flag to indicate if the environment variable is used in preview deployments.
                is_literal:
                  type: boolean
                  description: The flag to indicate if the environment variable is a literal, nothing espaced.
                is_multiline:
                  type: boolean
                  description: The flag to indicate if the environment variable is multiline.
                is_shown_once:
                  type: boolean
                  description: The flag to indicate if the environment variable's value is shown on the UI.
              type: object
      responses:
        '201':
          description: Environment variable created.
          content:
            application/json:
              schema:
                properties:
                  uuid:
                    type: string
                    example: nc0k04gk8g0cgsk440g0koko
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
      security:
      - bearerAuth: []
    patch:
      tags:
      - Services
      summary: Update Env
      description: Update env by service UUID.
      operationId: update-env-by-service-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      requestBody:
        description: Env updated.
        required: true
        content:
          application/json:
            schema:
              required:
              - key
              - value
              properties:
                key:
                  type: string
                  description: The key of the environment variable.
                value:
                  type: string
                  description: The value of the environment variable.
                is_preview:
                  type: boolean
                  description: The flag to indicate if the environment variable is used in preview deployments.
                is_literal:
                  type: boolean
                  description: The flag to indicate if the environment variable is a literal, nothing espaced.
                is_multiline:
                  type: boolean
                  description: The flag to indicate if the environment variable is multiline.
                is_shown_once:
                  type: boolean
                  description: The flag to indicate if the environment variable's value is shown on the UI.
              type: object
      responses:
        '201':
          description: Environment variable updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvironmentVariable'
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
      security:
      - bearerAuth: []
  /services/{uuid}/envs/bulk:
    patch:
      tags:
      - Services
      summary: Update Envs (Bulk)
      description: Update multiple envs by service UUID.
      operationId: update-envs-by-service-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      requestBody:
        description: Bulk envs updated.
        required: true
        content:
          application/json:
            schema:
              required:
              - data
              properties:
                data:
                  type: array
                  items:
                    properties:
                      key:
                        type: string
                        description: The key of the environment variable.
                      value:
                        type: string
                        description: The value of the environment variable.
                      is_preview:
                        type: boolean
                        description: The flag to indicate if the environment variable is used in preview deployments.
                      is_literal:
                        type: boolean
                        description: The flag to indicate if the environment variable is a literal, nothing espaced.
                      is_multiline:
                        type: boolean
                        description: The flag to indicate if the environment variable is multiline.
                      is_shown_once:
                        type: boolean
                        description: The flag to indicate if the environment variable's value is shown on the UI.
                    type: object
              type: object
      responses:
        '201':
          description: Environment variables updated.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EnvironmentVariable'
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
      security:
      - bearerAuth: []
  /services/{uuid}/envs/{env_uuid}:
    delete:
      tags:
      - Services
      summary: Delete Env
      description: Delete env by UUID.
      operationId: delete-env-by-service-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      - name: env_uuid
        in: path
        description: UUID of the environment variable.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Environment variable deleted.
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: Environment variable deleted.
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
      security:
      - bearerAuth: []
  /services/{uuid}/start:
    get:
      tags:
      - Services
      summary: Start
      description: Start service. `Post` request is also accepted.
      operationId: start-service-by-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Start service.
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: Service starting request queued.
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
      security:
      - bearerAuth: []
  /services/{uuid}/stop:
    get:
      tags:
      - Services
      summary: Stop
      description: Stop service. `Post` request is also accepted.
      operationId: stop-service-by-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      - name: docker_cleanup
        in: query
        description: Perform docker cleanup (prune networks, volumes, etc.).
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Stop service.
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: Service stopping request queued.
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
      security:
      - bearerAuth: []
  /services/{uuid}/restart:
    get:
      tags:
      - Services
      summary: Restart
      description: Restart service. `Post` request is also accepted.
      operationId: restart-service-by-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      - name: latest
        in: query
        description: Pull latest images.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Restart service.
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: Service restaring request queued.
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
      security:
      - bearerAuth: []
  /services/{uuid}/storages:
    get:
      tags:
      - Services
      summary: List Storages
      description: List all persistent storages and file storages by service UUID.
      operationId: list-storages-by-service-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: All storages by service UUID.
          content:
            application/json:
              schema:
                properties:
                  persistent_storages:
                    type: array
                    items:
                      type: object
                  file_storages:
                    type: array
                    items:
                      type: object
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
      security:
      - bearerAuth: []
    post:
      tags:
      - Services
      summary: Create Storage
      description: Create a persistent storage or file storage for a service sub-resource.
      operationId: create-storage-by-service-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
              - type
              - mount_path
              - resource_uuid
              properties:
                type:
                  type: string
                  enum:
                  - persistent
                  - file
                  description: The type of storage.
                resource_uuid:
                  type: string
                  description: UUID of the service application or database sub-resource.
                name:
                  type: string
                  description: Volume name (persistent only, required for persistent).
                mount_path:
                  type: string
                  description: The container mount path.
                host_path:
                  type: string
                  nullable: true
                  description: The host path (persistent only, optional).
                content:
                  type: string
                  nullable: true
                  description: File content (file only, optional).
                is_directory:
                  type: boolean
                  description: Whether this is a directory mount (file only, default false).
                fs_path:
                  type: string
                  description: Host directory path (required when is_directory is true).
              type: object
              additionalProperties: false
      responses:
        '201':
          description: Storage created.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
      security:
      - bearerAuth: []
    patch:
      tags:
      - Services
      summary: Update Storage
      description: Update a persistent storage or file storage by service UUID.
      operationId: update-storage-by-service-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      requestBody:
        description: Storage updated. For read-only storages (from docker-compose or services), only is_preview_suffix_enabled can be updated.
        required: true
        content:
          application/json:
            schema:
              required:
              - type
              properties:
                uuid:
                  type: string
                  description: The UUID of the storage (preferred).
                id:
                  type: integer
                  description: The ID of the storage (deprecated, use uuid instead).
                type:
                  type: string
                  enum:
                  - persistent
                  - file
                  description: 'The type of storage: persistent or file.'
                is_preview_suffix_enabled:
                  type: boolean
                  description: Whether to add -pr-N suffix for preview deployments.
                name:
                  type: string
                  description: The volume name (persistent only, not allowed for read-only storages).
                mount_path:
                  type: string
                  description: The container mount path (not allowed for read-only storages).
                host_path:
                  type: string
                  nullable: true
                  description: The host path (persistent only, not allowed for read-only storages).
                content:
                  type: string
                  nullable: true
                  description: The file content (file only, not allowed for read-only storages).
              type: object
              additionalProperties: false
      responses:
        '200':
          description: Storage updated.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
      security:
      - bearerAuth: []
  /services/{uuid}/storages/{storage_uuid}:
    delete:
      tags:
      - Services
      summary: Delete Storage
      description: Delete a persistent storage or file storage by service UUID.
      operationId: delete-storage-by-service-uuid
      parameters:
      - name: uuid
        in: path
        description: UUID of the service.
        required: true
        schema:
          type: string
      - name: storage_uuid
        in: path
        description: UUID of the storage.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Storage deleted.
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
      security:
      - bearerAuth: []
components:
  schemas:
    Service:
      description: Service model
      properties:
        id:
          type: integer
          description: The unique identifier of the service. Only used for database identification.
        uuid:
          type: string
          description: The unique identifier of the service.
        name:
          type: string
          description: The name of the service.
        environment_id:
          type: integer
          description: The unique identifier of the environment where the service is attached to.
        server_id:
          type: integer
          description: The unique identifier of the server where the service is running.
        description:
          type: string
          description: The description of the service.
        docker_compose_raw:
          type: string
          description: The raw docker-compose.yml file of the service.
        docker_compose:
          type: string
          description: The docker-compose.yml file that is parsed and modified by Coolify.
        destination_type:
          type: string
          description: Destination type.
        destination_id:
          type: integer
          description: The unique identifier of the destination where the service is running.
        connect_to_docker_network:
          type: boolean
          description: The flag to connect the service to the predefined Docker network.
        is_container_label_escape_enabled:
          type: boolean
          description: The flag to enable the container label escape.
        is_container_label_readonly_enabled:
          type: boolean
          description: The flag to enable the container label readonly.
        config_hash:
          type: string
          description: The hash of the service configuration.
        service_type:
          type: string
          description: The type of the service.
        created_at:
          type: string
          description: The date and time when the service was created.
        updated_at:
          type: string
          description: The date and time when the service was last updated.
        deleted_at:
          type: string
          description: The date and time when the service was deleted.
      type: object
    EnvironmentVariable:
      description: Environment Variable model
      properties:
        id:
          type: integer
        uuid:
          type: string
        resourceable_type:
          type: string
        resourceable_id:
          type: integer
        is_literal:
          type: boolean
        is_multiline:
          type: boolean
        is_preview:
          type: boolean
        is_runtime:
          type: boolean
        is_buildtime:
          type: boolean
        is_shared:
          type: boolean
        is_shown_once:
          type: boolean
        key:
          type: string
        value:
          type: string
        real_value:
          type: string
        comment:
          type: string
          nullable: true
        version:
          type: string
        created_at:
          type: string
        updated_at:
          type: string
      type: object
  responses:
    '400':
      description: Invalid token.
      content:
        application/json:
          schema:
            properties:
              message:
                type: string
                example: Invalid token.
            type: object
    '404':
      description: Resource not found.
      content:
        application/json:
          schema:
            properties:
              message:
                type: string
                example: Resource not found.
            type: object
    '401':
      description: Unauthenticated.
      content:
        application/json:
          schema:
            properties:
              message:
                type: string
                example: Unauthenticated.
            type: object
    '422':
      description: Validation error.
      content:
        application/json:
          schema:
            properties:
              message:
                type: string
                example: Validation error.
              errors:
                type: object
                example:
                  name:
                  - The name field is required.
                  api_url:
                  - The api url field is required.
                  - The api url format is invalid.
                additionalProperties:
                  type: array
                  items:
                    type: string
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      description: Go to `Keys & Tokens` / `API tokens` and create a new token. Use the token as the bearer token.
      scheme: bearer