Platform.sh Blackfire Profiling API

openapi: 3.2.0
info:
  title: Upsun.com Rest Blackfire Profiling 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: Blackfire Profiling
paths:
  /projects/{projectId}/environments/{environmentId}/observability/profiles/{uuid}/timeline:
    get:
      tags:
      - Blackfire Profiling
      summary: Get profile timeline data
      description: Returns timeline visualization data for a Blackfire profile, showing the execution flow over time.
      operationId: blackfire_profile_timeline
      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
      - name: uuid
        in: path
        description: The profile UUID
        required: true
        schema:
          type: string
          format: uuid
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          example: 4b5266a2-fd71-468b-bf05-87b342079cbf
      responses:
        '200':
          description: Timeline data retrieved successfully
          content:
            application/json:
              schema:
                required:
                - _project_id
                - _environment_id
                - _branch_machine_name
                - _agent
                - _uuid
                - timeline
                - dimension
                - time
                - language
                properties:
                  _project_id:
                    description: Project identifier
                    type: string
                    example: abc123def456
                  _environment_id:
                    description: Environment identifier
                    type: string
                    example: main
                  _branch_machine_name:
                    description: Branch machine name
                    type: string
                    example: main-bvxea6i
                  _agent:
                    description: Blackfire Agent UUID
                    type: string
                    format: uuid
                    example: a38f69ca-3b56-4ea6-beac-272b2568164a
                  _uuid:
                    description: Profile UUID
                    type: string
                    format: uuid
                    example: 4b5266a2-fd71-468b-bf05-87b342079cbf
                  timeline:
                    description: Timeline event data including stack frames, memory graph, labels, markers, spans, and hierarchy
                    type: object
                  dimension:
                    description: Active timeline dimension
                    type: string
                    example: wt
                  time:
                    description: Total time for the active dimension in microseconds
                    type: integer
                    example: 4329972
                  language:
                    description: Profiled application language
                    type: string
                    example: php
                    enum:
                    - php
                    - python
                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)
  /projects/{projectId}/environments/{environmentId}/observability/profiles/{uuid}/subprofiles:
    get:
      tags:
      - Blackfire Profiling
      summary: Get profile subprofiles
      description: Returns subprofiles (child profiles) associated with a Blackfire profile.
      operationId: blackfire_profile_subprofiles
      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
      - name: uuid
        in: path
        description: The profile UUID
        required: true
        schema:
          type: string
          format: uuid
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          example: 4b5266a2-fd71-468b-bf05-87b342079cbf
      responses:
        '200':
          description: Subprofiles retrieved successfully
          content:
            application/json:
              schema:
                required:
                - _project_id
                - _environment_id
                - _branch_machine_name
                - _agent
                - _uuid
                - subprofiles
                properties:
                  _project_id:
                    description: Project identifier
                    type: string
                    example: abc123def456
                  _environment_id:
                    description: Environment identifier
                    type: string
                    example: main
                  _branch_machine_name:
                    description: Branch machine name
                    type: string
                    example: main-bvxea6i
                  _agent:
                    description: Blackfire Agent UUID
                    type: string
                    format: uuid
                    example: a38f69ca-3b56-4ea6-beac-272b2568164a
                  _uuid:
                    description: Profile UUID
                    type: string
                    format: uuid
                    example: 4b5266a2-fd71-468b-bf05-87b342079cbf
                  subprofiles:
                    description: Profile tree with context, metrics, recommendations, and child profiles
                    type: object
                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)
  /projects/{projectId}/environments/{environmentId}/observability/profiles/{uuid}/profile:
    get:
      tags:
      - Blackfire Profiling
      summary: Get profile details
      description: Returns full profile data including metrics, metadata, and recommendations.
      operationId: blackfire_profile_profile
      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
      - name: uuid
        in: path
        description: The profile UUID
        required: true
        schema:
          type: string
          format: uuid
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          example: 4b5266a2-fd71-468b-bf05-87b342079cbf
      responses:
        '200':
          description: Profile details retrieved successfully
          content:
            application/json:
              schema:
                required:
                - _project_id
                - _environment_id
                - _branch_machine_name
                - _agent
                - _uuid
                - profile
                properties:
                  _project_id:
                    description: Project identifier
                    type: string
                    example: abc123def456
                  _environment_id:
                    description: Environment identifier
                    type: string
                    example: main
                  _branch_machine_name:
                    description: Branch machine name
                    type: string
                    example: main-bvxea6i
                  _agent:
                    description: Blackfire Agent UUID
                    type: string
                    format: uuid
                    example: a38f69ca-3b56-4ea6-beac-272b2568164a
                  _uuid:
                    description: Profile UUID
                    type: string
                    format: uuid
                    example: 4b5266a2-fd71-468b-bf05-87b342079cbf
                  profile:
                    description: Profile data including links, metadata, metrics, recommendations, and status information
                    type: object
                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)
  /projects/{projectId}/environments/{environmentId}/observability/profiles/{uuid}/graph:
    get:
      tags:
      - Blackfire Profiling
      summary: Get profile call graph
      description: Returns the call graph data for a Blackfire profile, showing function calls and their performance metrics.
      operationId: blackfire_profile_graph
      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
      - name: uuid
        in: path
        description: The profile UUID
        required: true
        schema:
          type: string
          format: uuid
          pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
          example: 4b5266a2-fd71-468b-bf05-87b342079cbf
      responses:
        '200':
          description: Call graph retrieved successfully
          content:
            application/json:
              schema:
                required:
                - _project_id
                - _environment_id
                - _branch_machine_name
                - _agent
                - _uuid
                - dimensions
                - root
                - nodes
                - edges
                - comparison
                - language
                properties:
                  _project_id:
                    description: Project identifier
                    type: string
                    example: abc123def456
                  _environment_id:
                    description: Environment identifier
                    type: string
                    example: main
                  _branch_machine_name:
                    description: Branch machine name
                    type: string
                    example: main-bvxea6i
                  _agent:
                    description: Blackfire Agent UUID
                    type: string
                    format: uuid
                    example: a38f69ca-3b56-4ea6-beac-272b2568164a
                  _uuid:
                    description: Profile UUID
                    type: string
                    format: uuid
                    example: 4b5266a2-fd71-468b-bf05-87b342079cbf
                  dimensions:
                    description: Available metric dimensions (wt, cpu, mu, pmu, io, nw, ct)
                    type: object
                  root:
                    description: Root node identifier
                    type: string
                    example: main()
                  nodes:
                    description: Call graph nodes with inclusive/exclusive costs and percentages
                    type: object
                  edges:
                    description: Call graph edges linking caller to callee nodes
                    type: object
                  comparison:
                    description: Whether this is a comparison graph
                    type: boolean
                    example: false
                  peaks:
                    description: Peak inclusive and exclusive costs
                    type: object
                  arguments:
                    description: Function arguments and metric data
                    type:
                    - object
                    - 'null'
                  layers:
                    description: Layer information
                    type:
                    - object
                    - 'null'
                  labels:
                    description: Timespan labels
                    type: object
                  spans:
                    description: Span metadata
                    type: object
                  spans-ot:
                    description: OpenTelemetry span data
                    type: object
                  hierarchy:
                    description: Profile hierarchy data
                    type: object
                  language:
                    description: Profiled application language
                    type: string
                    example: php
                    enum:
                    - php
                    - python
                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)
  /projects/{projectId}/environments/{environmentId}/observability/profiles/recommendations:
    get:
      tags:
      - Blackfire Profiling
      summary: Get recommendation statistics
      description: Returns recommendation statistics for the environment, optionally filtered by transaction. Proxied from the Blackfire API. Each recommendation includes the constraint details, occurrence count, and links to the latest profile and documentation.
      operationId: blackfire_profiles_recommendations
      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
      - name: from
        in: query
        description: Start of time range (Unix timestamp). Defaults to 2 weeks ago.
        required: false
        schema:
          type: integer
          example: 1704067200
      - name: to
        in: query
        description: End of time range (Unix timestamp). Defaults to now.
        required: false
        schema:
          type: integer
          example: 1704326400
      - name: transaction
        in: query
        description: Filter recommendations to a specific transaction name.
        required: false
        schema:
          type: string
          example: App\Controller\ProductController::list
      - name: limit
        in: query
        description: Maximum number of recommendation results to return. Clamped to range 10–200. Defaults to 10 (or 200 when filtering by transaction).
        required: false
        schema:
          type: integer
          example: 50
          maximum: 200
          minimum: 10
      responses:
        '200':
          description: Recommendation statistics retrieved successfully
          content:
            application/json:
              schema:
                required:
                - _project_id
                - _environment_id
                - _branch_machine_name
                - _agent
                - _from
                - _to
                - recommendations
                - total
                properties:
                  _project_id:
                    description: Project identifier
                    type: string
                    example: abc123def456
                  _environment_id:
                    description: Environment identifier
                    type: string
                    example: main
                  _branch_machine_name:
                    description: Branch machine name
                    type: string
                    example: main-bvxea6i
                  _agent:
                    description: Blackfire Agent UUID
                    type: string
                    format: uuid
                    example: a38f69ca-3b56-4ea6-beac-272b2568164a
                  _from:
                    description: Start of time range (Unix timestamp)
                    type: integer
                    example: 1704067200
                  _to:
                    description: End of time range (Unix timestamp)
                    type: integer
                    example: 1704326400
                  _transaction:
                    description: Filtered transaction name (only present when transaction filter is applied)
                    type: string
                    example: App\Controller\ProductController::list
                  recommendations:
                    description: List of failing recommendations
                    type: array
                    items:
                      required:
                      - name
                      - total
                      properties:
                        name:
                          description: Recommendation constraint name
                          type: string
                          example: tests.symfony.kernel.secret_is_set
                        constraint:
                          description: Constraint details
                          type:
                          - object
                          - 'null'
                        total:
                          description: Number of profiles failing this recommendation
                          type: integer
                          example: 15
                        _links:
                          description: API links to the latest profile that triggered this recommendation. Only present when a latest profile is available.
                          required:
                          - api_subprofiles
                          - api_profile
                          - api_graph
                          properties:
                            api_timeline:
                              description: API endpoint for timeline data (JSON)
                              required:
                              - href
                              - type
                              properties:
                                href:
                                  type: string
                                  format: uri
                                  example: https://api.upsun.com/projects/abc123/environments/main/observability/profiles/4b5266a2-fd71-468b-bf05-87b342079cbf/timeline
                                type:
                                  type: string
                                  example: application/json
                                  enum:
                                  - application/json
                              type: object
                              additionalProperties: false
                            api_subprofiles:
                              description: API endpoint for subprofiles data (JSON)
                              required:
                              - href
                              - type
                              properties:
                                href:
                                  type: string
                                  format: uri
                                  example: https://api.upsun.com/projects/abc123/environments/main/observability/profiles/4b5266a2-fd71-468b-bf05-87b342079cbf/subprofiles
                                type:
                                  type: string
                                  example: application/json
                                  enum:
                                  - application/json
                              type: object
                              additionalProperties: false
                            api_profile:
                              description: API endpoint for profile details (JSON)
                              required:
                              - href
                              - type
                              properties:
                                href:
                                  type: string
                                  format: uri
                                  example: https://api.upsun.com/projects/abc123/environments/main/observability/profiles/4b5266a2-fd71-468b-bf05-87b342079cbf/profile
                                type:
                                  type: string
                                  example: application/json
                                  enum:
                                  - application/json
                              type: object
                              additionalProperties: false
                            api_graph:
                              description: API endpoint for call graph data (JSON)
                              required:
                              - href
                              - type
                              properties:
                                href:
                                  type: string
                                  format: uri
                                  example: https://api.upsun.com/projects/abc123/environments/main/observability/profiles/4b5266a2-fd71-468b-bf05-87b342079cbf/graph
                                type:
                                  type: string
                                  example: application/json
                                  enum:
                                  - application/json
                              type: object
                              additionalProperties: false
                          type: object
                          additionalProperties: false
                      type: object
                      additionalProperties: false
                  tested_transactions:
                    description: List of transaction names that have been tested by recommendations
                    type: array
                    items:
                      type: string
                  untested_top_transactions:
                    description: List of top transaction names that have not been tested by recommendations
                    type: array
                    items:
                      type: string
                  total:
                    description: Total number of profiles with failing recommendations
                    type: integer
                    example: 42
                type: object
                additionalProperties: false
              example:
                _project_id: abc123def456
                _environment_id: main
                _branch_machine_name: main-bvxea6i
                _agent: a38f69ca-3b56-4ea6-beac-272b2568164a
                _from: 1704067200
                _to: 1704326400
                recommendations:
                - name: tests.symfony.kernel.secret_is_set
                  constraint:
                    id: tests.symfony.kernel.secret_is_set
                    name: tests.symfony.kernel.secret_is_set
                  total: 15
                  _links:
                    api_timeline:
                      href: https://api.upsun.com/projects/abc123def456/environments/main/observability/profiles/4b5266a2-fd71-468b-bf05-87b342079cbf/timeline
                      type: application/json
                    api_subprofiles:
                      href: https://api.upsun.com/projects/abc123def456/environments/main/observability/profiles/4b5266a2-fd71-468b-bf05-87b342079cbf/subprofiles
                      type: application/json
                    api_profile:
                      href: https://api.upsun.com/projects/abc123def456/environments/main/observability/profiles/4b5266a2-fd71-468b-bf05-87b342079cbf/profile
                      type: application/json
                    api_graph:
                      href: https://api.upsun.com/projects/abc123def456/environments/main/observability/profiles/4b5266a2-fd71-468b-bf05-87b342079cbf/graph
                      type: application/json
                total: 42
        '400':
          description: Bad request - Invalid parameters. Please consult the API documentation to fix the request parameters.
          content:
            application/json:
              schema:
                required:
                - type
                - title
                - status
                - violations
                properties:
                  type:
                    description: RFC 2616 reference URL identifying the error type
                    type: string
                    format: uri
                    example: https://tools.ietf.org/html/rfc2616#section-1
                  title:
                    description: Human-readable summary of the validation error
                    type: string
                    example

# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/platform.sh/refs/heads/main/openapi/platform.sh-blackfire-profiling-api-openapi.yml