Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Upsun.com Rest Resources 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&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: Resources
paths:
/projects/{projectId}/environments/{environmentId}/observability/resources/overview:
get:
tags:
- Resources
summary: Get resource metrics overview
description: 'Returns time-series resource utilization data for all services. Each timestamp includes per-service metrics: CPU (cores), memory (bytes), swap (bytes), pressure indicators (0.0-1.0), and per-mountpoint disk/inode usage. All metrics include statistical aggregations: min, max, avg, stddev, and percentiles (p50, p95-p99). Service names and mountpoint paths are dynamic. Aggregation values are nullable when insufficient data exists.'
operationId: resources_overview
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 timestamp for the time range (Unix timestamp in seconds)
required: true
schema:
type: integer
format: int64
example: 1704067200
- name: to
in: query
description: End timestamp for the time range (Unix timestamp in seconds)
required: true
schema:
type: integer
format: int64
example: 1704153600
- name: service
in: query
description: Filter by specific service name (optional)
required: false
schema:
type: string
example: app
- name: services[]
in: query
description: Filter results to specific services. Can be specified multiple times for multiple services. When omitted, all services are included by default. Use services_mode to control inclusion/exclusion behavior. Specify parameter multiple times for multiple values (e.g., ?services[]=app&services[]=database).
required: false
style: form
explode: true
schema:
type: array
items:
type: string
example: app
- name: services_mode
in: query
description: Filter mode for services parameter. "1" (additive) includes only specified services. "-1" (subtractive, default) excludes specified services and includes all others.
required: false
schema:
type: string
example: '1'
default: null
enum:
- '1'
- '-1'
responses:
'200':
description: Resource metrics retrieved successfully
content:
application/json:
schema:
required:
- _grain
- _from
- _to
- _project_id
- _environment_id
- _branch_machine_name
- data
properties:
_grain:
description: Data granularity in seconds
type: integer
example: 5
_from:
description: Query start timestamp
type: integer
example: 1704067200
_to:
description: Query end timestamp
type: integer
example: 1704153600
_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
data:
description: Array of timestamped data points, each containing resource metrics grouped by service name. Each data point contains `timestamp` and optional data fields. Fields are omitted for timestamps with no data - this indicates no data was received.
type: array
items:
required:
- timestamp
properties:
timestamp:
description: Data point timestamp (Unix timestamp in seconds)
type: integer
example: 1704067200
services:
description: 'Object with service names as keys (dynamic, e.g., "app", "database"). Each service contains: cpu_used, cpu_limit, memory_used, memory_limit, swap_used, swap_limit, memory_pressure, cpu_pressure, io_pressure, irq_pressure, and mountpoints. All metrics except limits include min, max, avg, stddev, p50, p95-p99 aggregations (nullable).'
type: object
example:
app:
cpu_used:
min: 0.12
max: 1.85
avg: 0.45
stddev: 0.32
p50: 0.42
p95: 1.23
p96: 1.34
p97: 1.45
p98: 1.62
p99: 1.78
cpu_limit:
max: 2
memory_used:
min: 536870912
max: 715827883
avg: 612892672
stddev: 45000000
p50: 605000000
p95: 690000000
p96: 695000000
p97: 700000000
p98: 708000000
p99: 712000000
memory_limit:
max: 1073741824
swap_used:
min: 0
max: 4194304
avg: 1048576
stddev: 850000
p50: 950000
p95: 3200000
p96: 3400000
p97: 3600000
p98: 3900000
p99: 4100000
swap_limit:
max: 536870912
memory_pressure:
min: 0
max: 0.15
avg: 0.03
stddev: 0.02
p50: 0.02
p95: 0.12
p96: 0.13
p97: 0.14
p98: 0.145
p99: 0.148
cpu_pressure:
min: 0
max: 0.08
avg: 0.01
stddev: 0.01
p50: 0.01
p95: 0.05
p96: 0.06
p97: 0.065
p98: 0.07
p99: 0.075
io_pressure:
min: 0
max: 0.22
avg: 0.05
stddev: 0.04
p50: 0.04
p95: 0.18
p96: 0.19
p97: 0.2
p98: 0.21
p99: 0.215
irq_pressure:
min: 0
max: 0.01
avg: 0.001
stddev: 0.002
p50: 0
p95: 0.008
p96: 0.009
p97: 0.0095
p98: 0.0097
p99: 0.0099
mountpoints:
? ''
: disk_used:
min: 3087007744
max: 3221225472
avg: 3154116608
stddev: 35000000
p50: 3150000000
p95: 3210000000
p96: 3215000000
p97: 3217000000
p98: 3219000000
p99: 3220000000
disk_limit:
max: 10737418240
inodes_used:
min: 45000
max: 52000
avg: 48500
stddev: 1500
p50: 48400
p95: 51200
p96: 51400
p97: 51600
p98: 51800
p99: 51900
inodes_limit:
max: 655360
/tmp:
disk_used:
min: 524288
max: 2097152
avg: 1310720
stddev: 400000
p50: 1300000
p95: 1900000
p96: 1950000
p97: 2000000
p98: 2050000
p99: 2080000
disk_limit:
max: 1073741824
inodes_used:
min: 120
max: 245
avg: 182
stddev: 25
p50: 180
p95: 230
p96: 235
p97: 238
p98: 242
p99: 244
inodes_limit:
max: 65536
database:
cpu_used:
min: 0.08
max: 2.45
avg: 0.62
stddev: 0.48
p50: 0.55
p95: 1.85
p96: 2.02
p97: 2.15
p98: 2.28
p99: 2.38
cpu_limit:
max: 4
memory_used:
min: 1073741824
max: 1610612736
avg: 1342177280
stddev: 120000000
p50: 1320000000
p95: 1550000000
p96: 1570000000
p97: 1585000000
p98: 1598000000
p99: 1606000000
memory_limit:
max: 2147483648
swap_used:
min: 0
max: 8388608
avg: 2097152
stddev: 1800000
p50: 1900000
p95: 6500000
p96: 7100000
p97: 7500000
p98: 7900000
p99: 8200000
swap_limit:
max: 1073741824
memory_pressure:
min: 0
max: 0.25
avg: 0.06
stddev: 0.05
p50: 0.05
p95: 0.2
p96: 0.21
p97: 0.22
p98: 0.23
p99: 0.24
cpu_pressure:
min: 0
max: 0.12
avg: 0.02
stddev: 0.02
p50: 0.02
p95: 0.09
p96: 0.1
p97: 0.105
p98: 0.11
p99: 0.115
io_pressure:
min: 0
max: 0.45
avg: 0.12
stddev: 0.09
p50: 0.1
p95: 0.35
p96: 0.38
p97: 0.4
p98: 0.42
p99: 0.44
irq_pressure:
min: 0
max: 0.02
avg: 0.003
stddev: 0.004
p50: 0.002
p95: 0.015
p96: 0.017
p97: 0.018
p98: 0.019
p99: 0.0195
mountpoints:
? ''
: disk_used:
min: 8589934592
max: 9663676416
avg: 9126805504
stddev: 250000000
p50: 9100000000
p95: 9550000000
p96: 9580000000
p97: 9610000000
p98: 9640000000
p99: 9660000000
disk_limit:
max: 21474836480
inodes_used:
min: 125000
max: 145000
avg: 135000
stddev: 4500
p50: 134500
p95: 142800
p96: 143400
p97: 144000
p98: 144500
p99: 144800
inodes_limit:
max: 1310720
additionalProperties:
properties:
cpu_used:
description: 'CPU usage in cores. Includes statistical aggregations (all nullable): min, max, avg, stddev, p50, p95, p96, p97, p98, p99'
properties:
min:
description: Minimum CPU cores used
type:
- number
- 'null'
format: float
example: 0.12
max:
description: Maximum CPU cores used
type:
- number
- 'null'
format: float
example: 1.85
avg:
description: Average CPU cores used
type:
- number
- 'null'
format: float
example: 0.45
stddev:
description: Standard deviation of CPU cores used
type:
- number
- 'null'
format: float
example: 0.32
p50:
description: Median (50th percentile) CPU cores used
type:
- number
- 'null'
format: float
example: 0.42
p95:
description: 95th percentile CPU cores used
type:
- number
- 'null'
format: float
example: 1.23
p96:
description: 96th percentile CPU cores used
type:
- number
- 'null'
format: float
example: 1.34
p97:
description: 97th percentile CPU cores used
type:
- number
- 'null'
format: float
example: 1.45
p98:
description: 98th percentile CPU cores used
type:
- number
- 'null'
format: float
example: 1.62
p99:
description: 99th percentile CPU cores used
type:
- number
- 'null'
format: float
example: 1.78
type: object
additionalProperties: false
cpu_limit:
description: CPU limit in cores. Contains only max (nullable)
properties:
max:
description: Maximum CPU limit in cores
type:
- number
- 'null'
format: float
example: 2
type: object
additionalProperties: false
memory_used:
description: 'Memory usage in bytes. Includes statistical aggregations (all nullable): min, max, avg, stddev, p50, p95, p96, p97, p98, p99'
properties:
min:
description: Minimum memory bytes used
type:
- integer
- 'null'
format: int64
example: 536870912
max:
description: Maximum memory bytes used
type:
- integer
- 'null'
format: int64
example: 715827883
avg:
description: Average memory bytes used
type:
- number
- 'null'
format: float
example: 612892672
stddev:
description: Standard deviation of memory bytes used
type:
- number
- 'null'
format: float
example: 45000000
p50:
description: Median (50th percentile) memory bytes used
type:
- number
- 'null'
format: float
example: 605000000
p95:
description: 95th percentile memory bytes used
type:
- number
- 'null'
format: float
example: 690000000
p96:
description: 96th percentile memory bytes used
type:
- number
- 'null'
format: float
example: 695000000
p97:
description: 97th percentile memory bytes used
type:
- number
- 'null'
format: float
example: 700000000
p98:
description: 98th percentile memory bytes used
type:
- number
- 'null'
format: float
example: 708000000
p99:
description: 99th percentile memory bytes used
type:
- number
- 'null'
format: float
example: 712000000
type: object
additionalProperties: false
memory_limit:
description: Memory limit in bytes. Contains only max (nullable)
properties:
max:
description: Maximum memory limit in bytes
type:
- integer
- 'null'
format: int64
example: 1073741824
type: object
additionalProperties
# --- truncated at 32 KB (166 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/platform.sh/refs/heads/main/openapi/platform.sh-resources-api-openapi.yml