Platform.sh Entrypoint API

openapi: 3.2.0
info:
  title: Upsun.com Rest Entrypoint 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: Entrypoint
paths:
  /projects/{projectId}/environments/{environmentId}/observability:
    get:
      tags:
      - Entrypoint
      summary: Get observability entrypoint
      description: Returns API entrypoint with hypermedia links to all observability endpoints (resources, logs, HTTP traffic, continuous profiling, server metrics) following HATEOAS principles. Includes data retention policies per metric type (retention_period, max_range, recommended_default_range in minutes), environment metadata (project_id, environment_id, environment_type, vendor), and per-service resource links. Use _links for API navigation.
      operationId: observability_entrypoint
      parameters:
      - name: projectId
        in: path
        description: The unique identifier of the Upsun project
        required: true
        schema:
          type: string
          pattern: '[a-z0-9]+'
          example: abc123def456
      - name: environmentId
        in: path
        description: The environment identifier
        required: true
        schema:
          type: string
          pattern: .+
          example: main
      responses:
        '200':
          description: Observability entrypoint retrieved successfully
          content:
            application/json:
              schema:
                required:
                - message
                - project_id
                - branch_machine_name
                - environment_id
                - environment_type
                - vendor
                - psh_user_identifier
                - _links
                - retention
                - data_retention
                properties:
                  message:
                    description: Welcome message
                    type: string
                    example: bonjour, monde!
                  project_id:
                    description: Project identifier
                    type: string
                    example: abc123def456
                  branch_machine_name:
                    description: Branch machine name
                    type: string
                    example: main
                  environment_id:
                    description: Environment identifier
                    type: string
                    example: main
                  environment_type:
                    description: Environment type classification
                    type: string
                    example: production
                    enum:
                    - production
                    - staging
                    - development
                  vendor:
                    description: Platform vendor identifier
                    type: string
                    example: upsun
                    enum:
                    - upsun
                    - platformsh
                  psh_user_identifier:
                    description: Authenticated user identifier
                    type: string
                    example: user@example.com
                  _links:
                    description: HATEOAS navigation links to all observability endpoints
                    required:
                    - _self
                    - resources_by_service
                    - resources_overview
                    - resources_summary
                    - blackfire_php_server_caches
                    - blackfire_server_global
                    - blackfire_server_transactions_breakdown
                    - logs_query
                    - logs_overview
                    - http_metrics_timeline_urls
                    - http_metrics_timeline_ips
                    - http_metrics_timeline_user_agents
                    - console_sandbox_access
                    - conprof_applications
                    - conprof_application_filters
                    - conprof_timeline
                    - conprof_flamegraph
                    properties:
                      _self:
                        description: Link to this entrypoint resource
                        required:
                        - href
                        properties:
                          href:
                            description: URL to this resource
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability
                        type: object
                        additionalProperties: false
                      resources_by_service:
                        description: Per-service resource metrics endpoints with service names as keys
                        type: object
                        example:
                          app:
                            name: app
                            href: https://api.upsun.com/projects/abc123def456/environments/main/observability/resources/service/app
                          database:
                            name: database
                            href: https://api.upsun.com/projects/abc123def456/environments/main/observability/resources/service/database
                        additionalProperties:
                          required:
                          - name
                          - href
                          properties:
                            name:
                              description: Service name
                              type: string
                              example: app
                            href:
                              description: URL to service metrics endpoint
                              type: string
                              format: uri
                              example: https://api.upsun.com/projects/abc123def456/environments/main/observability/resources/service/app
                          type: object
                          additionalProperties: false
                      resources_overview:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability/resources/overview
                        type: object
                        additionalProperties: false
                      resources_summary:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability/resources/summary
                        type: object
                        additionalProperties: false
                      blackfire_php_server_caches:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability/server/caches
                        type: object
                        additionalProperties: false
                      blackfire_server_global:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability/server
                        type: object
                        additionalProperties: false
                      blackfire_server_transactions_breakdown:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability/server/transactions-break-down
                        type: object
                        additionalProperties: false
                      logs_query:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability/logs/query
                        type: object
                        additionalProperties: false
                      logs_overview:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability/logs/overview
                        type: object
                        additionalProperties: false
                      http_metrics_timeline_urls:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability/http/breakdown/urls
                        type: object
                        additionalProperties: false
                      http_metrics_timeline_ips:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability/http/breakdown/ips
                        type: object
                        additionalProperties: false
                      http_metrics_timeline_user_agents:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability/http/breakdown/user-agents
                        type: object
                        additionalProperties: false
                      console_sandbox_access:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/observability/console/sandbox-access
                        type: object
                        additionalProperties: false
                      conprof_applications:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/continuous-profiling
                        type: object
                        additionalProperties: false
                      conprof_application_filters:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/continuous-profiling/app/myapp/filter
                        type: object
                        additionalProperties: false
                      conprof_timeline:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/continuous-profiling/app/myapp
                        type: object
                        additionalProperties: false
                      conprof_flamegraph:
                        required:
                        - href
                        properties:
                          href:
                            type: string
                            format: uri
                            example: https://api.upsun.com/projects/abc123def456/environments/main/continuous-profiling/app/myapp/merge
                        type: object
                        additionalProperties: false
                    type: object
                    additionalProperties: false
                  retention:
                    description: 'DEPRECATED: Data retention periods in minutes per resource type. Use data_retention instead.'
                    required:
                    - resources
                    - logs
                    - http_traffic
                    - continuous_profiling
                    properties:
                      resources:
                        type: integer
                        example: 43200
                      logs:
                        type: integer
                        example: 43200
                      http_traffic:
                        type: integer
                        example: 43200
                      continuous_profiling:
                        type: integer
                        example: 80640
                    type: object
                    additionalProperties: false
                  data_retention:
                    description: Data retention policies per metric type with periods in minutes
                    required:
                    - _unit
                    - _unit_in_seconds
                    - resources
                    - server_monitoring
                    - logs
                    - http_traffic
                    - continuous_profiling
                    properties:
                      _unit:
                        description: Time unit for all retention values
                        type: string
                        example: minute
                      _unit_in_seconds:
                        description: Unit conversion to seconds
                        type: integer
                        example: 60
                      resources:
                        description: Resource metrics retention policy in minutes
                        required:
                        - retention_period
                        - max_range
                        - recommended_default_range
                        properties:
                          retention_period:
                            description: Data storage duration in minutes
                            type: integer
                            example: 43200
                          max_range:
                            description: Maximum query time range in minutes
                            type: integer
                            example: 43200
                          recommended_default_range:
                            description: Recommended default query time range in minutes, for user interfaces
                            type: integer
                            example: 43200
                        type: object
                        additionalProperties: false
                      server_monitoring:
                        description: Server monitoring retention policy in minutes
                        required:
                        - retention_period
                        - max_range
                        - recommended_default_range
                        properties:
                          retention_period:
                            description: Data storage duration in minutes
                            type: integer
                            example: 80640
                          max_range:
                            description: Maximum query time range in minutes
                            type: integer
                            example: 20160
                          recommended_default_range:
                            description: Recommended default query time range in minutes, for user interfaces
                            type: integer
                            example: 1440
                        type: object
                        additionalProperties: false
                      logs:
                        description: Logs retention policy in minutes
                        required:
                        - retention_period
                        - max_range
                        - recommended_default_range
                        properties:
                          retention_period:
                            description: Data storage duration in minutes
                            type: integer
                            example: 43200
                          max_range:
                            description: Maximum query time range in minutes
                            type: integer
                            example: 43200
                          recommended_default_range:
                            description: Recommended default query time range in minutes, for user interfaces
                            type: integer
                            example: 43200
                        type: object
                        additionalProperties: false
                      http_traffic:
                        description: HTTP traffic retention policy in minutes
                        required:
                        - retention_period
                        - max_range
                        - recommended_default_range
                        properties:
                          retention_period:
                            description: Data storage duration in minutes
                            type: integer
                            example: 43200
                          max_range:
                            description: Maximum query time range in minutes
                            type: integer
                            example: 43200
                          recommended_default_range:
                            description: Recommended default query time range in minutes, for user interfaces
                            type: integer
                            example: 43200
                        type: object
                        additionalProperties: false
                      continuous_profiling:
                        description: Continuous profiling retention policy in minutes
                        required:
                        - retention_period
                        - max_range
                        - recommended_default_range
                        properties:
                          retention_period:
                            description: Data storage duration in minutes
                            type: integer
                            example: 43200
                          max_range:
                            description: Maximum query time range in minutes
                            type: integer
                            example: 43200
                          recommended_default_range:
                            description: Recommended default query time range in minutes, for user interfaces
                            type: integer
                            example: 43200
                        type: object
                        additionalProperties: false
                    type: object
                    additionalProperties: false
                type: object
                additionalProperties: false
        '403':
          description: Forbidden - Access denied due to insufficient permissions, or the requested project/environment does not exist (to prevent information disclosure)
components:
  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