Platform.sh Task API

openapi: 3.2.0
info:
  title: Upsun.com Rest Task API
  version: '1.0'
  contact:
    name: Support
    url: https://upsun.com/contact-us/
  termsOfService: https://upsun.com/trust-center/legal/tos/
  description: "# Introduction\n\nUpsun, formerly Platform.sh, is a container-based Platform-as-a-Service. Our main API\nis simply Git. With a single `git push` and a couple of YAML files in\nyour repository you can deploy an arbitrarily complex cluster.\nEvery [**Project**](#tag/Project) can have multiple applications (PHP,\nNode.js, Python, Ruby, Go, etc.) and managed, automatically\nprovisioned services (databases, message queues, etc.).\n\nEach project also comes with multiple concurrent\nlive staging/development [**Environments**](#tag/Environment).\nThese ephemeral development environments\nare automatically created every time you push a new branch or create a\npull request, and each has a full copy of the data of its parent branch,\nwhich is created on-the-fly in seconds.\n\nOur Git implementation supports integrations with third party Git\nproviders such as GitHub, Bitbucket, or GitLab, allowing you to simply\nintegrate Upsun into your existing workflow.\n\n## Using the REST API\n\nIn addition to the Git API, we also offer a REST API that allows you to manage\nevery aspect of the platform, from managing projects and environments,\nto accessing accounts and subscriptions, to creating robust workflows\nand integrations with your CI systems and internal services.\n\nThese API docs are generated from a standard **OpenAPI (Swagger)** Specification document\nwhich you can find here in [YAML](openapispec-upsun.yaml) and in [JSON](openapispec-upsun.json) formats.\n\nThis RESTful API consumes and produces HAL-style JSON over HTTPS,\nand any REST library can be used to access it. On GitHub, we also host\na few API libraries that you can use to make API access easier, such as our\n[PHP API client](https://github.com/upsun/upsun-sdk-php).\n\nIn order to use the API you will first need to have an [Upsun account](https://auth.upsun.com/register/)\nand [create an API Token](https://docs.upsun.com/anchors/cli/api-token/).\n\n# Authentication\n\n## OAuth2\n\nAPI authentication is done with OAuth2 access tokens.\n\n### API tokens\n\nYou can use an API token as one way to get an OAuth2 access token. This\nis particularly useful in scripts, e.g. for CI pipelines.\n\nTo create an API token, go to the \"API Tokens\" section\nof the \"Account Settings\" tab on the [Console](https://console.upsun.com).\n\nTo exchange this API token for an access token, a `POST` request\nmust be made to `https://auth.upsun.com/oauth2/token`.\n\nThe request will look like this in cURL:\n\n<pre>\ncurl -u platform-api-user: \\\n    -d 'grant_type=api_token&amp;api_token=<em><b>API_TOKEN</b></em>' \\\n    https://auth.upsun.com/oauth2/token\n</pre>\n\nThis will return a \"Bearer\" access token that\ncan be used to authenticate further API requests, for example:\n\n<pre>\n{\n    \"access_token\": \"<em><b>abcdefghij1234567890</b></em>\",\n    \"expires_in\": 900,\n    \"token_type\": \"bearer\"\n}\n</pre>\n\n### Using the Access Token\n\nTo authenticate further API requests, include this returned bearer token\nin the `Authorization` header. For example, to retrieve a list of\n[Projects](#tag/Project)\naccessible by the current user, you can make the following request\n(substituting the dummy token for your own):\n\n<pre>\ncurl -H \"Authorization: Bearer <em><b>abcdefghij1234567890</b></em>\" \\\n    https://api.upsun.com/projects\n</pre>\n\n# HAL Links\n\nMost endpoints in the API return fields which defines a HAL\n(Hypertext Application Language) schema for the requested endpoint.\nThe particular objects returns and their contents can vary by endpoint.\nThe payload examples we give here for the requests do not show these\nelements. These links can allow you to create a fully dynamic API client\nthat does not need to hardcode any method or schema.\n\nUnless they are used for pagination we do not show the HAL links in the\npayload examples in this documentation for brevity and as their content\nis contextual (based on the permissions of the user).\n\n## _links Objects\n\nMost endpoints that respond to `GET` requests will include a `_links` object\nin their response. The `_links` object contains a key-object pair labelled `self`, which defines\ntwo further key-value pairs:\n\n* `href` - A URL string referring to the fully qualified name of the returned object. For many endpoints, this will be the direct link to the API endpoint on the region gateway, rather than on the general API gateway. This means it may reference a host of, for example, `eu-2.platform.sh` rather than `api.upsun.com`.\n* `meta` - An object defining the OpenAPI Specification (OAS) [schema object](https://swagger.io/specification/#schemaObject) of the component returned by the endpoint.\n\nThere may be zero or more other fields in the `_links` object resembling fragment identifiers\nbeginning with a hash mark, e.g. `#edit` or `#delete`. Each of these keys\nrefers to a JSON object containing two key-value pairs:\n\n* `href` - A URL string referring to the path name of endpoint which can perform the action named in the key.\n* `meta` - An object defining the OAS schema of the endpoint. This consists of a key-value pair, with the key defining an HTTP method and the value defining the [operation object](https://swagger.io/specification/#operationObject) of the endpoint.\n\nTo use one of these HAL links, you must send a new request to the URL defined\nin the `href` field which contains a body defined the schema object in the `meta` field.\n\nFor example, if you make a request such as `GET /projects/abcdefghij1234567890`, the `_links`\nobject in the returned response will include the key `#delete`. That object\nwill look something like this fragment:\n\n```\n\"#delete\": {\n    \"href\": \"/api/projects/abcdefghij1234567890\",\n    \"meta\": {\n        \"delete\": {\n            \"responses\": {\n                . . . // Response definition omitted for space\n            },\n            \"parameters\": []\n        }\n    }\n}\n```\n\nTo use this information to delete a project, you would then send a `DELETE`\nrequest to the endpoint `https://api.upsun.com/api/projects/abcdefghij1234567890`\nwith no body or parameters to delete the project that was originally requested.\n\n## _embedded Objects\n\nRequests to endpoints which create or modify objects, such as `POST`, `PATCH`, or `DELETE`\nrequests, will include an `_embedded` key in their response. The object\nrepresented by this key will contain the created or modified object. This\nobject is identical to what would be returned by a subsequent `GET` request\nfor the object referred to by the endpoint.\n"
  x-logo:
    url: https://docs.upsun.com/images/upsun-api.svg
    href: https://upsun.com/#section/Introduction
    altText: Upsun logo
servers:
- url: '{schemes}://api.upsun.com'
  description: The Upsun.com API gateway
  variables:
    schemes:
      default: https
security:
- BearerAuth: []
tags:
- name: Task
  description: 'These endpoints can be used to manage tasks, which are one-off commands that can be run in the context of

    an environment. Tasks are useful for running database migrations, executing maintenance scripts, or performing

    any ad-hoc operations that need to be executed within the environment. For more information on how to use tasks,

    see the [Tasks](https://docs.upsun.com/anchors/environments/actions#environment-actions/) section of the

    documentation.

    '
paths:
  /projects/{projectId}/environments/{environmentId}/tasks:
    get:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: environmentId
      operationId: list-projects-environments-tasks
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskCollection'
      tags:
      - Task
  /projects/{projectId}/environments/{environmentId}/tasks/{taskId}:
    get:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: environmentId
      - in: path
        required: true
        schema:
          type: string
        name: taskId
      operationId: get-projects-environments-tasks
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
      tags:
      - Task
  /projects/{projectId}/environments/{environmentId}/tasks/{taskId}/run:
    post:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: environmentId
      - in: path
        required: true
        schema:
          type: string
        name: taskId
      operationId: run-task
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskTriggerInput'
      tags:
      - Task
components:
  schemas:
    AcceptedResponse:
      type: object
      properties:
        status:
          type: string
          title: Status text
          description: The status text of the response
        code:
          type: integer
          title: Status code
          description: The status code of the response
      required:
      - status
      - code
      additionalProperties: false
    TaskCollection:
      type: array
      items:
        $ref: '#/components/schemas/Task'
    TaskTriggerInput:
      type: object
      properties:
        variables:
          type: object
          additionalProperties:
            type: object
            additionalProperties: {}
          title: Variables
          description: Environment variables for the task
      additionalProperties: false
    Task:
      type: object
      properties:
        id:
          type: string
          title: Task Identifier
          description: The identifier of Task
        resources:
          type:
          - object
          - 'null'
          properties:
            base_memory:
              type: integer
              title: Base memory
              description: The base memory for the container
            memory_ratio:
              type: integer
              title: Memory ratio
              description: The amount of memory to allocate per units of CPU
          required:
          - base_memory
          - memory_ratio
          additionalProperties: false
          title: Resources
          description: Resources configuration (base memory and memory ratio)
        authorizations:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - env
                - task
                title: Authorization Type
                description: The resource type for this authorization.
              action:
                type: string
                title: Authorization Action
                description: The action to authorize on the target resource.
              resource:
                type:
                - string
                - 'null'
                title: Authorization Resource
                description: The target resource for this authorization.
            required:
            - type
            - action
            - resource
            additionalProperties: false
          title: Authorizations
          description: Authorizations available to this container
        relationships:
          type: object
          additionalProperties:
            type:
            - object
            - 'null'
            properties:
              service:
                type:
                - string
                - 'null'
                title: Service Name
                description: The name of the service.
              endpoint:
                type:
                - string
                - 'null'
                title: Endpoint Name
                description: The name of the endpoint on the service.
            required:
            - service
            - endpoint
            additionalProperties: false
          title: Service Relationships
          description: The relationships of the container to defined services
        additional_hosts:
          type: object
          additionalProperties:
            type: string
          title: Additional hosts
          description: A mapping of hostname to ip address to be added to the container's hosts file
        mounts:
          type: object
          additionalProperties:
            type: object
            properties:
              source:
                type: string
                enum:
                - instance
                - local
                - service
                - storage
                - temporary
                - tmp
                title: Mount type
                description: The type of mount that will provide the data.
              source_path:
                type: string
                title: Source Path
                description: The path to be mounted, relative to the root directory of the volume that's being mounted from.
              service:
                type:
                - string
                - 'null'
                title: Service Name
                description: The name of the service that the volume will be mounted from. Must be a service in `services.yaml` of type `network-storage`.
            required:
            - source
            - source_path
            additionalProperties: false
          title: Mounts
          description: Filesystem mounts of this container. If not specified the container will have no writeable disk space
        timezone:
          type:
          - string
          - 'null'
          title: Timezone
          description: The timezone of the task. Defaults to the project's timezone if not specified
        variables:
          type: object
          additionalProperties:
            type: object
            additionalProperties: {}
          title: Environment Variables
          description: Variables provide environment-sensitive information to control how this container behaves. To set a Unix environment variable, specify a key of `env:`, and then each sub-item of that is a key/value pair that will be injected into the environment
        container_profile:
          type:
          - string
          - 'null'
          title: Container Profile
          description: Selected container profile for this container
        type:
          type: string
          title: Image type
          description: The runtime type and version for the task (e.g., python:3.8)
        source:
          type: object
          properties:
            root:
              type: string
              title: Task Source Root
              description: The root of the task relative to the repository root
          required:
          - root
          additionalProperties: false
          title: Source Code Configuration
          description: Configuration related to the source code of the task
        hooks:
          type: object
          properties:
            build:
              type:
              - string
              - 'null'
              title: Build Hook
              description: Hook executed after the build process
            deploy:
              type:
              - string
              - 'null'
              title: Deploy Hook
              description: Hook executed before the task's run command
          required:
          - build
          - deploy
          additionalProperties: false
          title: Hooks
          description: Scripts executed at various points in the lifecycle of the task
        dependencies:
          type: object
          additionalProperties:
            type: object
          title: Dependencies
          description: External global dependencies of this task. They will be downloaded by the language's package manager
        runtime:
          type: object
          title: Runtime Configuration
          description: Runtime-specific configuration
        run:
          type: object
          properties:
            command:
              type: string
              title: Run Command
              description: The command to execute when running the task
            timeout:
              type: integer
              title: Timeout
              description: The maximum timeout in seconds after which the task will be forcefully killed
          required:
          - command
          - timeout
          additionalProperties: false
          title: Run Configuration
          description: Configuration for task execution
        name:
          type: string
          title: Task name
          description: The unique name of the task
      required:
      - id
      - resources
      - authorizations
      - relationships
      - additional_hosts
      - mounts
      - timezone
      - variables
      - container_profile
      - type
      - source
      - hooks
      - dependencies
      - runtime
      - run
      - name
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: Organization Administration
  tags:
  - Organizations
  - Organization Members
  - Organization Invitations
  - Organization Projects
  - Add-ons
- name: Project Administration
  tags:
  - Project
  - Domain Claim
  - Domain Management
  - Cert Management
  - Certificate Provisioner
  - Project Variables
  - Repository
  - Third-Party Integrations
  - Support
- name: Environments
  tags:
  - Environment
  - Environment Backups
  - Environment Type
  - Environment Variables
  - Routing
  - Source Operations
  - Runtime Operations
  - Deployment
  - Autoscaling
  - Task
- name: User Activity
  tags:
  - Project Activity
  - Environment Activity
- name: Project Access
  tags:
  - Project Invitations
  - Teams
  - Team Access
  - User Access
- name: Account Management
  tags:
  - API Tokens
  - Connections
  - MFA
  - Users
  - User Profiles
  - SSH Keys
  - Plans
- name: Billing
  tags:
  - Organization Management
  - Subscriptions
  - Orders
  - Invoices
  - Discounts
  - Vouchers
  - Records
  - Profiles
  - Billing Profile Projects
- name: Global Info
  tags:
  - Project Discovery
  - References
  - Regions
- name: Observability
  tags:
  - Blackfire Profiling
  - Blackfire Monitoring
  - Resources
  - Http Traffic
  - Continuous Profiling
- name: Internal APIs
  tags:
  - Project Settings
  - Environment Settings
  - Deployment Target
  - System Information
  - Container Profile