Upsun Third-Party Integrations API

openapi: 3.2.0
info:
  title: Upsun.com Rest Add-ons Third-Party Integrations 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: Third-Party Integrations
  description: 'Upsun can easily integrate with many third-party services, including

    Git hosting services (GitHub, GitLab, and Bitbucket),

    health notification services (email, Slack, PagerDuty),

    performance analytics platforms (New Relic, Blackfire, Tideways),

    and webhooks.


    For clarification about what information each field requires, see the

    [External Integrations](https://docs.upsun.com/anchors/integrations/)

    documentation. NOTE: The names of the CLI arguments listed in the

    documentation are not always named exactly the same as the

    required body fields in the API request.

    '
paths:
  /projects/{projectId}/integrations:
    get:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      operationId: list-projects-integrations
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationCollection'
      tags:
      - Third-Party Integrations
      summary: Get list of existing integrations for a project
    post:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      operationId: create-projects-integrations
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationCreateInput'
      tags:
      - Third-Party Integrations
      summary: Integrate project with a third-party service
  /projects/{projectId}/integrations/{integrationId}:
    get:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: integrationId
      operationId: get-projects-integrations
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Integration'
      tags:
      - Third-Party Integrations
      summary: Get information about an existing third-party integration
    patch:
      requestBody:
        description: ''
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationPatch'
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: integrationId
      operationId: update-projects-integrations
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
      tags:
      - Third-Party Integrations
      summary: Update an existing third-party integration
    delete:
      parameters:
      - in: path
        required: true
        schema:
          type: string
        name: projectId
      - in: path
        required: true
        schema:
          type: string
        name: integrationId
      operationId: delete-projects-integrations
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
      tags:
      - Third-Party Integrations
      summary: Delete an existing third-party integration
components:
  schemas:
    HealthWebHookIntegrationCreateInput:
      type: object
      properties:
        type:
          type: string
          title: Integration type
          description: ''
        shared_key:
          type:
          - string
          - 'null'
          title: Shared Key
          description: The JWS shared secret key
        url:
          type: string
          title: WebHook URL
          description: The URL of the webhook
      required:
      - type
      - url
      additionalProperties: false
    SlackIntegrationPatch:
      type: object
      properties:
        type:
          type: string
          title: Integration type
          description: ''
        token:
          type: string
          title: Slack Token
          description: The Slack token to use
        channel:
          type: string
          title: Slack Channel
          description: The Slack channel to post messages to
      required:
      - type
      - token
      - channel
      additionalProperties: false
    FastlyIntegrationPatch:
      type: object
      properties:
        type:
          type: string
          title: Integration type
          description: ''
        events:
          type: array
          items:
            type: string
          title: Events
          description: Events to execute the hook on
        environments:
          type: array
          items:
            type: string
          title: Environments
          description: The environments to execute the hook on
        excluded_environments:
          type: array
          items:
            type: string
          title: Excluded Environments
          description: The environments to not execute the hook on
        states:
          type: array
          items:
            type: string
          title: States
          description: Events to execute the hook on
        result:
          type: string
          enum:
          - '*'
          - failure
          - success
          title: Result
          description: Result to execute the hook on
        token:
          type: string
          title: Token
          description: Fastly API Token
        service_id:
          type: string
          title: Fastly Service ID
          description: ''
      required:
      - type
      - token
      - service_id
      additionalProperties: false
    SplunkIntegration:
      type: object
      properties:
        id:
          type: string
          title: SplunkIntegration Identifier
          description: The identifier of SplunkIntegration
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          title: Creation date
          description: The creation date
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          title: Update date
          description: The update date
        type:
          type: string
          title: Integration type
          description: ''
        extra:
          type: object
          additionalProperties:
            type: string
          title: Extra
          description: Arbitrary key/value pairs to include with forwarded logs
        url:
          type: string
          title: URL
          description: The Splunk HTTP Event Connector REST API endpoint
        index:
          type: string
          title: Index
          description: The Splunk Index
        sourcetype:
          type: string
          title: Sourcetype
          description: The event 'sourcetype'
        tls_verify:
          type: boolean
          title: TLS Verify
          description: Enable/Disable HTTPS certificate verification
        excluded_services:
          type: array
          items:
            type: string
          title: Excluded Services
          description: Comma separated list of service and application names to exclude from logging
      required:
      - created_at
      - updated_at
      - type
      - extra
      - url
      - index
      - sourcetype
      - tls_verify
      - excluded_services
      additionalProperties: false
    Integration:
      oneOf:
      - $ref: '#/components/schemas/BitbucketIntegration'
      - $ref: '#/components/schemas/BitbucketServerIntegration'
      - $ref: '#/components/schemas/BlackfireIntegration'
      - $ref: '#/components/schemas/FastlyIntegration'
      - $ref: '#/components/schemas/GithubIntegration'
      - $ref: '#/components/schemas/GitLabIntegration'
      - $ref: '#/components/schemas/EmailIntegration'
      - $ref: '#/components/schemas/PagerDutyIntegration'
      - $ref: '#/components/schemas/SlackIntegration'
      - $ref: '#/components/schemas/HealthWebHookIntegration'
      - $ref: '#/components/schemas/HttpLogIntegration'
      - $ref: '#/components/schemas/NewRelicIntegration'
      - $ref: '#/components/schemas/HttpLogIntegration'
      - $ref: '#/components/schemas/ScriptIntegration'
      - $ref: '#/components/schemas/SplunkIntegration'
      - $ref: '#/components/schemas/SumologicIntegration'
      - $ref: '#/components/schemas/SyslogIntegration'
      - $ref: '#/components/schemas/WebHookIntegration'
    FastlyIntegration:
      type: object
      properties:
        id:
          type: string
          title: FastlyIntegration Identifier
          description: The identifier of FastlyIntegration
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          title: Creation date
          description: The creation date
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          title: Update date
          description: The update date
        type:
          type: string
          title: Integration type
          description: ''
        events:
          type: array
          items:
            type: string
          title: Events
          description: Events to execute the hook on
        environments:
          type: array
          items:
            type: string
          title: Environments
          description: The environments to execute the hook on
        excluded_environments:
          type: array
          items:
            type: string
          title: Excluded Environments
          description: The environments to not execute the hook on
        states:
          type: array
          items:
            type: string
          title: States
          description: Events to execute the hook on
        result:
          type: string
          enum:
          - '*'
          - failure
          - success
          title: Result
          description: Result to execute the hook on
        service_id:
          type: string
          title: Fastly Service ID
          description: ''
      required:
      - created_at
      - updated_at
      - type
      - events
      - environments
      - excluded_environments
      - states
      - result
      - service_id
      additionalProperties: false
    GitLabIntegrationPatch:
      type: object
      properties:
        type:
          type: string
          title: Integration type
          description: ''
        fetch_branches:
          type: boolean
          title: Fetch Branches
          description: Whether or not to fetch branches.
        prune_branches:
          type: boolean
          title: Prune Branches
          description: Whether or not to remove branches that disappeared remotely (requires `fetch_branches`).
        environment_init_resources:
          type: string
          enum:
          - default
          - manual
          - minimum
          - parent
          title: Environment Init Resources
          description: The resources used when initializing a new service
        token:
          type: string
          title: GitLab Private Token
          description: The GitLab private token.
        rotate_token:
          type: boolean
          title: Whether or not to rotate token automatically using Gitlab API.
          description: ''
        rotate_token_validity_in_weeks:
          type: integer
          title: Validity in weeks of a new token after rotation.
          description: ''
        base_url:
          type: string
          title: GitLab Base URL
          description: The base URL of the GitLab installation.
        project:
          type: string
          title: Project
          description: The GitLab project (in the form `namespace/repo`).
        build_merge_requests:
          type: boolean
          title: Build Merge Requests
          description: Whether or not to build merge requests.
        build_wip_merge_requests:
          type: boolean
          title: Build WIP Merge Requests
          description: Whether or not to build work in progress merge requests (requires `build_merge_requests`).
        merge_requests_clone_parent_data:
          type: boolean
          title: Clone Parent Data
          description: Whether or not to clone parent data when building merge requests.
      required:
      - type
      - token
      - project
      additionalProperties: false
    GithubIntegration:
      type: object
      properties:
        id:
          type: string
          title: GithubIntegration Identifier
          description: The identifier of GithubIntegration
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          title: Creation date
          description: The creation date
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          title: Update date
          description: The update date
        type:
          type: string
          title: Integration type
          description: ''
        fetch_branches:
          type: boolean
          title: Fetch Branches
          description: Whether or not to fetch branches.
        prune_branches:
          type: boolean
          title: Prune Branches
          description: Whether or not to remove branches that disappeared remotely (requires `fetch_branches`).
        environment_init_resources:
          type: string
          enum:
          - default
          - manual
          - minimum
          - parent
          title: Environment Init Resources
          description: The resources used when initializing a new service
        base_url:
          type:
          - string
          - 'null'
          title: Base URL
          description: The base URL of the Github API endpoint.
        repository:
          type: string
          title: Repository
          description: The GitHub repository (in the form `user/repo`).
        build_pull_requests:
          type: boolean
          title: Build Pull Requests
          description: Whether or not to build pull requests.
        build_draft_pull_requests:
          type: boolean
          title: Build Draft Pull Requests
          description: Whether or not to build draft pull requests (requires `build_pull_requests`).
        build_pull_requests_post_merge:
          type: boolean
          title: Build PR Post-Merge
          description: Whether to build pull requests post-merge (if true) or pre-merge (if false).
        pull_requests_clone_parent_data:
          type: boolean
          title: Clone Parent Data
          description: Whether or not to clone parent data when building pull requests.
        token_type:
          type: string
          enum:
          - classic_personal_token
          - github_app
          title: Token Type
          description: The type of the token of this GitHub integration
      required:
      - created_at
      - updated_at
      - type
      - fetch_branches
      - prune_branches
      - environment_init_resources
      - base_url
      - repository
      - build_pull_requests
      - build_draft_pull_requests
      - build_pull_requests_post_merge
      - pull_requests_clone_parent_data
      - token_type
      additionalProperties: false
    SyslogIntegrationPatch:
      type: object
      properties:
        type:
          type: string
          title: Integration type
          description: ''
        extra:
          type: object
          additionalProperties:
            type: string
          title: Extra
          description: Arbitrary key/value pairs to include with forwarded logs
        host:
          type: string
          title: Host
          description: Syslog relay/collector host
        port:
          type: integer
          title: Port
          description: Syslog relay/collector port
        protocol:
          type: string
          enum:
          - tcp
          - tls
          - udp
          title: Protocol
          description: Transport protocol
        facility:
          type: integer
          title: Facility
          description: Syslog facility
        message_format:
          type: string
          enum:
          - rfc3164
          - rfc5424
          title: Message format
          description: Syslog message format
        auth_token:
          type: string
          title: Authentication token
          description: ''
        auth_mode:
          type: string
          enum:
          - prefix
          - structured_data
          title: Authentication mode
          description: ''
        tls_verify:
          type: boolean
          title: TLS Verify
          description: Enable/Disable HTTPS certificate verification
        excluded_services:
          type: array
          items:
            type: string
          title: Excluded Services
          description: Comma separated list of service and application names to exclude from logging
      required:
      - type
      additionalProperties: false
    HttpLogIntegrationPatch:
      type: object
      properties:
        type:
          type: string
          title: Integration type
          description: ''
        extra:
          type: object
          additionalProperties:
            type: string
          title: Extra
          description: Arbitrary key/value pairs to include with forwarded logs
        url:
          type: string
          title: HTTP endpoint
          description: ''
        headers:
          type: object
          additionalProperties:
            type: string
          title: HTTP Headers
          description: HTTP headers to use in POST requests
        tls_verify:
          type: boolean
          title: TLS Verify
          description: Enable/Disable HTTPS certificate verification
        excluded_services:
          type: array
          items:
            type: string
          title: Excluded Services
          description: Comma separated list of service and application names to exclude from logging
      required:
      - type
      - url
      additionalProperties: false
    BitbucketServerIntegrationCreateInput:
      type: object
      properties:
        type:
          type: string
          title: Integration type
          description: ''
        fetch_branches:
          type: boolean
          title: Fetch Branches
          description: Whether or not to fetch branches.
        prune_branches:
          type: boolean
          title: Prune Branches
          description: Whether or not to remove branches that disappeared remotely (requires `fetch_branches`).
        environment_init_resources:
          type: string
          enum:
          - default
          - manual
          - minimum
          - parent
          title: Environment Init Resources
          description: The resources used when initializing a new service
        url:
          type: string
          title: URL
          description: The base URL of the Bitbucket Server installation.
        username:
          type: string
          title: Username
          description: The Bitbucket Server user.
        token:
          type: string
          title: Token
          description: The Bitbucket Server personal access token.
        project:
          type: string
          title: Project
          description: The Bitbucket Server project
        repository:
          type: string
          title: Repository
          description: The Bitbucket Server repository
        build_pull_requests:
          type: boolean
          title: Build Pull Requests
          description: Whether or not to build pull requests.
        pull_requests_clone_parent_data:
          type: boolean
          title: Clone Parent Data
          description: Whether or not to clone parent data when building merge requests.
      required:
      - type
      - url
      - username
      - token
      - project
      - repository
      additionalProperties: false
    WebHookIntegration:
      type: object
      properties:
        id:
          type: string
          title: WebHookIntegration Identifier
          description: The identifier of WebHookIntegration
        created_at:
          type:
          - string
          - 'null'
          format: date-time
          title: Creation date
          description: The creation date
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          title: Update date
          description: The update date
        type:
          type: string
          title: Integration type
          description: ''
        events:
          type: array
          items:
            type: string
          title: Events
          description: Events to execute the hook on
        environments:
          type: array
          items:
            type: string
          title: Environments
          description: The environments to execute the hook on
        excluded_environments:
          type: array
          items:
            type: string
          title: Excluded Environments
          description: The environments to not execute the hook on
        states:
          type: array
          items:
            type: string
          title: States
          description: Events to execute the hook on
        result:
          type: string
          enum:
          - '*'
          - failure
          - success
          title: Result
          description: Result to execute the hook on
        shared_key:
          type:
          - string
          - 'null'
          title: Shared Key
          description: The JWS shared secret key
        url:
          type: string
          title: URL
          description: The URL of the webhook
      required:
      - created_at
      - updated_at
      - type
      - events
      - environments
      - excluded_environments
      - states
      - result
      - shared_key
      - url
      additionalProperties: false
    NewRelicIntegrationCreateInput:
      type: object
      properties:
        type:
          type: string
          title: Integration type
          description: ''
        extra:
          type: object
          additionalProperties:
            type: string
          title: Extra
          description: Arbitrary key/value pairs to include with forwarded logs
        url:
          type: string
          title: The NewRelic Logs endpoint
          description: ''
        license_key:
          type: string
          title: License Key
          description: The NewRelic Logs License Key
        tls_verify:
          type: boolean
          title: TLS Verify
          description: Enable/Disable HTTPS certificate verification
        excluded_services:
          type: array
          items:
            type: string
          title: Excluded Services
          description: Comma separated list of service and application names to exclude from logging
      required:
      - type
      - url
      - license_key
      additionalProperties: false
    SyslogIntegrationCreateInput:
      type: object
      properties:
        type:
          type: string
          title: Integration type
          description: ''
        extra:
          type: object
          additionalProperties:
            type: string
          title: Extra
          description: Arbitrary key/value pairs to include with forwarded logs
        host:
          type: string
          title: Host
          description: Syslog relay/collector host
        port:
          type: integer
          title: Port
          description: Syslog relay/collector port
        protocol:
          type: string
          enum:
          - tcp
          - tls
          - udp
          title: Protocol
          description: Transport protocol
        facility:
          type: integer
          title: Facility
          description: Syslog facility
        message_format:
          type: string
          enum:
          - rfc3164
          - rfc5424
          title: Message format
          description: Syslog message format
        auth_token:
          type: string
          title: Authentication token
          description: ''
        auth_mode:
          type: string
          enum:
          - prefix
          - structured_data
          title: Authentication mode
          description: ''
        tls_verify:
          type: boolean
          title: TLS Verify
          description: Enable/Disable HTTPS certificate verification
        excluded_services:
          type: array
          items:
            type: string
          title: Excluded Services
          description: Comma separated list of service and application names to exclude from logging
      required:
      - type
      additionalProperties: false
    BlackfireIntegrationPatch:
      type: object
      properties:
        type:
          type: string
          title: Integration type
          description: ''
      required:
      - type
      

# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/upsun/refs/heads/main/openapi/upsun-third-party-integrations-api-openapi.yml