Upsun Project Activity API

openapi: 3.0.1
info:
  title: Upsun.com Rest Add-ons Project Activity 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:
- OAuth2: []
tags:
- name: Project Activity
paths:
  /projects/{projectId}/activities:
    get:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      operationId: list-projects-activities
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityCollection'
      tags:
      - Project Activity
      summary: Get project activity log
      description: 'Retrieve a project''s activity log including logging actions in all

        environments within a project. This returns a list of objects

        with records of actions such as:


        - Commits being pushed to the repository

        - A new environment being branched out from the specified environment

        - A snapshot being created of the specified environment


        The object includes a timestamp of when the action occurred

        (`created_at`), when the action concluded (`updated_at`),

        the current `state` of the action, the action''s completion

        percentage (`completion_percent`), the `environments` it

        applies to and when the activity expires (`expires_at`).


        There are other related information in the `payload`.

        The contents of the `payload` varies based on the `type` of the

        activity. For example:


        - An `environment.branch` action''s `payload` can contain objects

        representing the environment''s `parent` environment and the

        branching action''s `outcome`.


        - An `environment.push` action''s `payload` can contain objects

        representing the `environment`, the specific `commits` included in

        the push, and the `user` who pushed.


        Expired activities are removed from the project activity log, except

        the last 100 expired objects provided they are not of type `environment.cron`

        or `environment.backup`.

        '
  /projects/{projectId}/activities/{activityId}:
    get:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: activityId
      operationId: get-projects-activities
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
      tags:
      - Project Activity
      summary: Get a project activity log entry
      description: 'Retrieve a single activity log entry as specified by an

        `id` returned by the

        [Get project activity log](#tag/Project-Activity%2Fpaths%2F~1projects~1%7BprojectId%7D~1activities%2Fget)

        endpoint. See the documentation on that endpoint for details about

        the information this endpoint can return.

        '
  /projects/{projectId}/activities/{activityId}/cancel:
    post:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: activityId
      operationId: action-projects-activities-cancel
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
      tags:
      - Project Activity
      summary: Cancel a project activity
      description: 'Cancel a single activity as specified by an `id` returned by the

        [Get project activity log](#tag/Project-Activity%2Fpaths%2F~1projects~1%7BprojectId%7D~1activities%2Fget)

        endpoint.


        Please note that not all activities are cancelable.

        '
components:
  schemas:
    Activity:
      type: object
      properties:
        id:
          type: string
          title: Activity Identifier
          description: The identifier of Activity
        created_at:
          type: string
          format: date-time
          nullable: true
          title: Creation date
          description: The creation date
        updated_at:
          type: string
          format: date-time
          nullable: true
          title: Update date
          description: The update date
        type:
          type: string
          title: Type
          description: The type of the activity
        parameters:
          type: object
          title: Parameters
          description: The parameters of the activity
        project:
          type: string
          title: Project
          description: The project the activity belongs to
        integration:
          type: string
          title: Integration
          description: The integration the activity belongs to
        environments:
          type: array
          items:
            type: string
          title: Environments
          description: The environments related to the activity
        state:
          type: string
          enum:
          - cancelled
          - complete
          - in_progress
          - pending
          - scheduled
          - staged
          title: State
          description: The state of the activity
        result:
          type: string
          enum:
          - failure
          - success
          nullable: true
          title: Result
          description: The result of the activity
        started_at:
          type: string
          format: date-time
          nullable: true
          title: Start date
          description: The start date of the activity
        completed_at:
          type: string
          format: date-time
          nullable: true
          title: Completion date
          description: The completion date of the activity
        completion_percent:
          type: integer
          title: Completion percentage
          description: The completion percentage of the activity
        cancelled_at:
          type: string
          format: date-time
          nullable: true
          title: Cancellation date
          description: The Cancellation date of the activity
        timings:
          type: object
          additionalProperties:
            type: number
            format: float
          title: Timings
          description: Timings related to different phases of the activity
        log:
          type: string
          title: Log
          description: The log of the activity
          deprecated: true
          x-stability: DEPRECATED
        payload:
          type: object
          title: Payload
          description: The payload of the activity
        description:
          type: string
          nullable: true
          title: Activity HTML description
          description: The description of the activity, formatted with HTML
        text:
          type: string
          nullable: true
          title: Activity text description
          description: The description of the activity, formatted as plain text
        expires_at:
          type: string
          format: date-time
          nullable: true
          title: Expiration date
          description: The date at which the activity will expire
        commands:
          type: array
          items:
            type: object
            properties:
              app:
                type: string
                title: Application
                description: ''
              type:
                type: string
                title: Type
                description: ''
              exit_code:
                type: integer
                title: Exit status code
                description: ''
            required:
            - app
            - type
            - exit_code
            additionalProperties: false
          title: Commands
          description: The commands of the activity
      required:
      - id
      - created_at
      - updated_at
      - type
      - parameters
      - project
      - state
      - result
      - started_at
      - completed_at
      - completion_percent
      - cancelled_at
      - timings
      - log
      - payload
      - description
      - text
      - expires_at
      - commands
      additionalProperties: false
    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
    ActivityCollection:
      type: array
      items:
        $ref: '#/components/schemas/Activity'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          tokenUrl: https://auth.api.platform.sh/oauth2/token
          refreshUrl: https://auth.api.platform.sh/oauth2/token
          scopes: {}
          authorizationUrl: https://auth.api.platform.sh/oauth2/authorize
      description: ''
    OAuth2Admin:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.api.platform.sh/oauth2/token
          refreshUrl: ''
          scopes:
            admin: administrative operations
      description: ''
x-tagGroups:
- name: Organization Administration
  tags:
  - Organizations
  - Organization Members
  - Organization Invitations
  - Organization Projects
  - Add-ons
- name: Project Administration
  tags:
  - Project
  - 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
- 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
- name: Global Info
  tags:
  - Project Discovery
  - References
  - Regions
- name: Internal APIs
  tags:
  - Project Settings
  - Environment Settings
  - Deployment Target
  - System Information
  - Container Profile