Upsun REST API
Introduction Upsun, formerly Platform.sh, is a container-based Platform-as-a-Service. Our main API is simply Git. With a single git push and a couple of YAML…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Introduction
Upsun, formerly Platform.sh, is a container-based Platform-as-a-Service. Our main API
is simply Git. With a single git push and a couple of YAML files in
your repository you can deploy an arbitrarily complex cluster.
Every Project can have multiple applications (PHP,
Node.js, Python, Ruby, Go, etc.) and managed, automatically
provisioned services (databases, message queues, etc.).
Each project also comes with multiple concurrent
live staging/development Environments.
These ephemeral development environments
are automatically created every time you push a new branch or create a
pull request, and each has a full copy of the data of its parent branch,
which is created on-the-fly in seconds.
Our Git implementation supports integrations with third party Git
providers such as GitHub, Bitbucket, or GitLab, allowing you to simply
integrate Upsun into your existing workflow.
Using the REST API
In addition to the Git API, we also offer a REST API that allows you to manage
every aspect of the platform, from managing projects and environments,
to accessing accounts and subscriptions, to creating robust workflows
and integrations with your CI systems and internal services.
These API docs are generated from a standard OpenAPI (Swagger) Specification document
which you can find here in [YAML](openapispec-upsun.yaml) and in [JSON](openapispec-upsun.json) formats.
This RESTful API consumes and produces HAL-style JSON over HTTPS,
and any REST library can be used to access it. On GitHub, we also host
a few API libraries that you can use to make API access easier, such as our
PHP API client.
In order to use the API you will first need to have an Upsun account
and create an API Token.
Authentication
OAuth2
API authentication is done with OAuth2 access tokens.
API tokens
You can use an API token as one way to get an OAuth2 access token. This
is particularly useful in scripts, e.g. for CI pipelines.
To create an API token, go to the "API Tokens" section
of the "Account Settings" tab on the Console.
To exchange this API token for an access token, a POST request
must be made to https://auth.upsun.com/oauth2/token.
The request will look like this in cURL:
curl -u platform-api-user: \
-d 'grant_type=api_token&api_token= API_TOKEN ' \
https://auth.upsun.com/oauth2/token
This will return a "Bearer" access token that
can be used to authenticate further API requests, for example:
{
"access_token": " abcdefghij1234567890 ",
"expires_in": 900,
"token_type": "bearer"
}
Using the Access Token
To authenticate further API requests, include this returned bearer token
in the Authorization header. For example, to retrieve a list of
Projects
accessible by the current user, you can make the following request
(substituting the dummy token for your own):
curl -H "Authorization: Bearer abcdefghij1234567890 " \
https://api.upsun.com/projects
HAL Links
Most endpoints in the API return fields which defines a HAL
(Hypertext Application Language) schema for the requested endpoint.
The particular objects returns and their contents can vary by endpoint.
The payload examples we give here for the requests do not show these
elements. These links can allow you to create a fully dynamic API client
that does not need to hardcode any method or schema.
Unless they are used for pagination we do not show the HAL links in the
payload examples in this documentation for brevity and as their content
is contextual (based on the permissions of the user).
_links Objects
Most endpoints that respond to GET requests will include a _links object
in their response. The _links object contains a key-object pair labelled self, which defines
two further key-value pairs:
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.shrather thanapi.upsun.com.meta- An object defining the OpenAPI Specification (OAS) schema object of the component returned by the endpoint.
There may be zero or more other fields in the _links object resembling fragment identifiers
beginning with a hash mark, e.g. #edit or #delete. Each of these keys
refers to a JSON object containing two key-value pairs:
href- A URL string referring to the path name of endpoint which can perform the action named in the key.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…
Endpoints 272
Cert Management
- GETGet list of SSL certificates
/projects/:projectId/certificatesRetrieve a list of objects representing the SSL certificates associated with a project. - POSTAdd an SSL certificate
/projects/:projectId/certificatesAdd a single SSL certificate to a project. - GETGet an SSL certificate
/projects/:projectId/certificates/:certificateIdRetrieve information about a single SSL certificate associated with a project. - DELETEDelete an SSL certificate
/projects/:projectId/certificates/:certificateIdDelete a single SSL certificate associated with a project. - PATCHUpdate an SSL certificate
/projects/:projectId/certificates/:certificateIdUpdate a single SSL certificate associated with a project. - GETlist-projects-provisioners
/projects/:projectId/provisioners - GETget-projects-provisioners
/projects/:projectId/provisioners/:certificateProvisionerDocumentId - PATCHupdate-projects-provisioners
/projects/:projectId/provisioners/:certificateProvisionerDocumentId
Environment
- GETGet list of project environments
/projects/:projectId/environmentsRetrieve a list of a project's existing environments and the information associated with each environment. - GETGet an environment
/projects/:projectId/environments/:environmentIdRetrieve the details of a single existing environment. - DELETEDelete an environment
/projects/:projectId/environments/:environmentIdDelete a specified environment. - PATCHUpdate an environment
/projects/:projectId/environments/:environmentIdUpdate the details of a single existing environment. - POSTActivate an environment
/projects/:projectId/environments/:environmentId/activateSet the specified environment's status to active - POSTBranch an environment
/projects/:projectId/environments/:environmentId/branchCreate a new environment as a branch of the current environment. - POSTDeactivate an environment
/projects/:projectId/environments/:environmentId/deactivateDestroy all services and data running on this environment so that only the Git branch remains. The environment can be reactivated later at any time;… - POSTDeploy an environment
/projects/:projectId/environments/:environmentId/deployTrigger a controlled manual deployment to release all the staged changes - POSTInitialize a new environment
/projects/:projectId/environments/:environmentId/initializeInitialize and configure a new environment with an existing repository. The payload is the url of a git repository with a profile name: { "repository":… - POSTmaintenance-redeploy-environment
/projects/:projectId/environments/:environmentId/maintenance-redeploy - POSTMerge an environment
/projects/:projectId/environments/:environmentId/mergeMerge an environment into its parent. This means that code changes from the branch environment will be merged into the parent branch, and the parent branch… - POSTPause an environment
/projects/:projectId/environments/:environmentId/pausePause an environment, stopping all services and applications (except the router). Development environments are often used for a limited time and then… - POSTRedeploy an environment
/projects/:projectId/environments/:environmentId/redeployTrigger the redeployment sequence of an environment. - POSTResume a paused environment
/projects/:projectId/environments/:environmentId/resumeResume a paused environment, restarting all services and applications. Development environments that haven't been used for 14 days will be paused… - POSTSynchronize a child environment with its parent
/projects/:projectId/environments/:environmentId/synchronizeThis synchronizes the code and/or data of an environment with that of its parent, then redeploys the environment. Synchronization is only possible if a branch…
Environment Type
- GETGet environment types
/projects/:projectId/environment-typesList all available environment types - GETGet environment type links
/projects/:projectId/environment-types/:environmentTypeIdLists the endpoints used to retrieve info about the environment type.
Environment Backups
- POSTCreate backup of environment
/projects/:projectId/environments/:environmentId/backupTrigger a new backup of an environment to be created. See the Backups section of the documentation for more information. - GETGet an environment's backup list
/projects/:projectId/environments/:environmentId/backupsRetrieve a list of objects representing backups of this environment. - GETGet an environment backup's info
/projects/:projectId/environments/:environmentId/backups/:backupIdGet the details of a specific backup from an environment using the id of the entry retrieved by the Get backups list endpoint. - DELETEDelete an environment backup
/projects/:projectId/environments/:environmentId/backups/:backupIdDelete a specific backup from an environment using the id of the entry retrieved by the Get backups list endpoint. - POSTRestore an environment snapshot
/projects/:projectId/environments/:environmentId/backups/:backupId/restoreRestore a specific backup from an environment using the id of the entry retrieved by the Get backups list endpoint.
Environment Variables
- GETGet list of environment variables
/projects/:projectId/environments/:environmentId/variablesRetrieve a list of objects representing the user-defined variables within an environment. - POSTAdd an environment variable
/projects/:projectId/environments/:environmentId/variablesAdd a variable to an environment. The value can be either a string or a JSON object (default: string), as specified by the is_json boolean flag. Additionally,… - GETGet an environment variable
/projects/:projectId/environments/:environmentId/variables/:variableIdRetrieve a single user-defined environment variable. - DELETEDelete an environment variable
/projects/:projectId/environments/:environmentId/variables/:variableIdDelete a single user-defined environment variable. - PATCHUpdate an environment variable
/projects/:projectId/environments/:environmentId/variables/:variableIdUpdate a single user-defined environment variable. The value can be either a string or a JSON object (default: string), as specified by the is_json boolean…
Autoscaling
- GETRetrieves Autoscaler settings
/projects/:projectId/environments/:environmentId/autoscaling/settingsRetrieves Autoscaler settings - POSTUpdates Autoscaler settings
/projects/:projectId/environments/:environmentId/autoscaling/settingsUpdates Autoscaler settings - PATCHModifies Autoscaler settings
/projects/:projectId/environments/:environmentId/autoscaling/settingsModifies Autoscaler settings
Task
- GETlist-projects-environments-tasks
/projects/:projectId/environments/:environmentId/tasks - GETget-projects-environments-tasks
/projects/:projectId/environments/:environmentId/tasks/:taskId - POSTrun-task
/projects/:projectId/environments/:environmentId/tasks/:taskId/run
Project
- GETGet a project
/projects/:projectIdRetrieve the details of a single project. - GETGet a project's capabilities
/projects/:projectId/capabilitiesGet a list of capabilities on a project, as defined by the billing system. For instance, one special capability that could be defined on a project is large… - POSTClear project build cache
/projects/:projectId/clear_build_cacheOn rare occasions, a project's build cache can become corrupted. This endpoint will entirely flush the project's build cache. More information on clearing the… - POSTmaintenance-redeploy-project
/projects/:projectId/maintenance-redeploy
Project Variables
- GETGet list of project variables
/projects/:projectId/variablesRetrieve a list of objects representing the user-defined variables within a project. - POSTAdd a project variable
/projects/:projectId/variablesAdd a variable to a project. The value can be either a string or a JSON object (default: string), as specified by the is_json boolean flag. See the Variables… - GETGet a project variable
/projects/:projectId/variables/:projectVariableIdRetrieve a single user-defined project variable. - DELETEDelete a project variable
/projects/:projectId/variables/:projectVariableIdDelete a single user-defined project variable. - PATCHUpdate a project variable
/projects/:projectId/variables/:projectVariableIdUpdate a single user-defined project variable. The value can be either a string or a JSON object (default: string), as specified by the is_json boolean flag.…
Project Settings
- GETGet list of project settings
/projects/:projectId/settingsRetrieve the global settings for a project. - PATCHUpdate a project setting
/projects/:projectId/settingsUpdate one or more project-level settings.
Repository
- GETGet a blob object
/projects/:projectId/git/blobs/:repositoryBlobIdRetrieve, by hash, an object representing a blob in the repository backing a project. This endpoint allows direct read-only access to the contents of files in… - GETGet a commit object
/projects/:projectId/git/commits/:repositoryCommitIdRetrieve, by hash, an object representing a commit in the repository backing a project. This endpoint functions similarly to git cat-file -p <commit-id>. The… - GETGet list of repository refs
/projects/:projectId/git/refsRetrieve a list of refs/* in the repository backing a project. This endpoint functions similarly to git show-ref, with each returned object containing a ref… - GETGet a ref object
/projects/:projectId/git/refs/:repositoryRefIdRetrieve the details of a single refs object in the repository backing a project. This endpoint functions similarly to git show-ref <pattern>, although the… - GETGet a tree object
/projects/:projectId/git/trees/:repositoryTreeIdRetrieve, by hash, the tree state represented by a commit. The returned object's tree field contains a list of files and directories present in the tree.…
Domain Claim
- GETlist-projects-domain-claims
/projects/:projectId/domain-claims - POSTcreate-projects-domain-claims
/projects/:projectId/domain-claims - GETget-projects-domain-claims
/projects/:projectId/domain-claims/:domainClaimId - DELETEdelete-projects-domain-claims
/projects/:projectId/domain-claims/:domainClaimId - PATCHupdate-projects-domain-claims
/projects/:projectId/domain-claims/:domainClaimId
Domain Management
- GETGet list of project domains
/projects/:projectId/domainsRetrieve a list of objects representing the user-specified domains associated with a project. Note that this does *not* return the domains automatically… - POSTAdd a project domain
/projects/:projectId/domainsAdd a single domain to a project. If the ssl field is left blank without an object containing a PEM-encoded SSL certificate, a certificate will be provisioned… - GETGet a project domain
/projects/:projectId/domains/:domainIdRetrieve information about a single user-specified domain associated with a project. - DELETEDelete a project domain
/projects/:projectId/domains/:domainIdDelete a single user-specified domain associated with a project. - PATCHUpdate a project domain
/projects/:projectId/domains/:domainIdUpdate the information associated with a single user-specified domain associated with a project. - GETGet a list of environment domains
/projects/:projectId/environments/:environmentId/domainsRetrieve a list of objects representing the user-specified domains associated with an environment. Note that this does *not* return the .platformsh.site… - POSTAdd an environment domain
/projects/:projectId/environments/:environmentId/domainsAdd a single domain to an environment. If the environment is not production, the replacement_for field is required, which binds a new domain to an existing… - GETGet an environment domain
/projects/:projectId/environments/:environmentId/domains/:domainIdRetrieve information about a single user-specified domain associated with an environment. - DELETEDelete an environment domain
/projects/:projectId/environments/:environmentId/domains/:domainIdDelete a single user-specified domain associated with an environment. - PATCHUpdate an environment domain
/projects/:projectId/environments/:environmentId/domains/:domainIdUpdate the information associated with a single user-specified domain associated with an environment.
Routing
- GETGet list of routes
/projects/:projectId/environments/:environmentId/routesRetrieve a list of objects containing route definitions for a specific environment. The definitions returned by this endpoint are those present in an… - GETGet a route's info
/projects/:projectId/environments/:environmentId/routes/:routeIdGet details of a route from an environment using the id of the entry retrieved by the Get environment routes list endpoint.
Source Operations
- POSTTrigger a source operation
/projects/:projectId/environments/:environmentId/source-operationThis endpoint triggers a source code operation as defined in the source.operations key in a project's .upsun/config.yaml configuration. More information on… - GETList source operations
/projects/:projectId/environments/:environmentId/source-operationsLists all the source operations, defined in .upsun/config.yaml, that are available in an environment. More information on source code operations is available…
Deployment Target
- GETGet project deployment target info
/projects/:projectId/deploymentsThe deployment target information for the project. - POSTCreate a project deployment target
/projects/:projectId/deploymentsSet the deployment target information for a project. - GETGet a single project deployment target
/projects/:projectId/deployments/:deploymentTargetConfigurationIdGet a single deployment target configuration of a project. - DELETEDelete a single project deployment target
/projects/:projectId/deployments/:deploymentTargetConfigurationIdDelete a single deployment target configuration associated with a specific project. - PATCHUpdate a project deployment
/projects/:projectId/deployments/:deploymentTargetConfigurationId
Third-Party Integrations
- GETGet list of existing integrations for a project
/projects/:projectId/integrations - POSTIntegrate project with a third-party service
/projects/:projectId/integrations - GETGet information about an existing third-party integration
/projects/:projectId/integrations/:integrationId - DELETEDelete an existing third-party integration
/projects/:projectId/integrations/:integrationId - PATCHUpdate an existing third-party integration
/projects/:projectId/integrations/:integrationId
Subscriptions
- GETChecks if the user is able to update a project.
/subscriptions/:subscriptionId/can-update - POSTChecks if the user can afford the requested resources.
/subscriptions/:subscriptionId/can-afford - GETEstimate the price of a new subscription
/organizations/:organization_id/subscriptions/estimate?plan=string&environments=0&storage=0&user_licenses=0 - GETChecks if the user is able to create a new project.
/organizations/:organization_id/subscriptions/can-create - GETEstimate the price of a subscription
/organizations/:organization_id/subscriptions/:subscription_id/estimate?plan=string - GETGet current usage for a subscription
/organizations/:organization_id/subscriptions/:subscription_id/current_usage - GETList addons for a subscription
/organizations/:organization_id/subscriptions/:subscription_id/addons - GETGet usage alerts
/organizations/:organization_id/alerts/subscriptions/:subscription_id/usageRetrieves current and available usage alerts. - PATCHUpdate usage alerts.
/organizations/:organization_id/alerts/subscriptions/:subscription_id/usageUpdates usage alerts for a subscription. - GETList subscriptions
/organizations/:organization_id/subscriptionsRetrieves subscriptions for the specified organization. - POSTCreate subscription
/organizations/:organization_id/subscriptionsCreates a subscription for the specified organization. - GETGet subscription
/organizations/:organization_id/subscriptions/:subscription_idRetrieves a subscription for the specified organization. - DELETEDelete subscription
/organizations/:organization_id/subscriptions/:subscription_idDeletes a subscription for the specified organization. - PATCHUpdate subscription
/organizations/:organization_id/subscriptions/:subscription_idUpdates a subscription for the specified organization.
Orders
- GETDownload an invoice.
/orders/download?token=string - GETList orders
/organizations/:organization_id/ordersRetrieves orders for the specified organization. - GETGet order
/organizations/:organization_id/orders/:order_idRetrieves an order for the specified organization. - POSTCreate confirmation credentials for for 3D-Secure
/organizations/:organization_id/orders/:order_id/authorizeCreates confirmation credentials for payments that require online authorization
Invoices
- GETList invoices
/organizations/:organization_id/invoicesRetrieves a list of invoices for the specified organization. - GETGet invoice
/organizations/:organization_id/invoices/:invoice_idRetrieves an invoice for the specified organization.
Vouchers
- GETList vouchers
/organizations/:organization_id/vouchersRetrieves vouchers for the specified organization. - POSTApply voucher
/organizations/:organization_id/vouchers/applyApplies a voucher for the specified organization, and refreshes the currently open order.
Records
- GETList plan records
/organizations/:organization_id/records/planRetrieves plan records for the specified organization. - GETList usage records
/organizations/:organization_id/records/usageRetrieves usage records for the specified organization.
Support
- POSTCreate a new support ticket
/tickets - PATCHUpdate a ticket
/tickets/:ticket_id - GETList support ticket priorities
/tickets/priority - GETList support ticket categories
/tickets/category
System Information
- GETGet information about the Git server.
/projects/:projectId/systemOutput information for the project. - POSTRestart the Git server
/projects/:projectId/system/restartForce the Git server to restart.
Add-ons
- GETGet add-ons
/organizations/:organization_id/addonsRetrieves information about the add-ons for an organization. - PATCHUpdate organization add-ons
/organizations/:organization_id/addonsUpdates the add-ons configuration for an organization.
Alerts
- GETGet usage alerts for a subscription
/alerts/subscriptions/:subscriptionId/usage - PATCHUpdate usage alerts.
/alerts/subscriptions/:subscriptionId/usage
Api Tokens
- GETList a user's API tokens
/users/:user_id/api-tokensRetrieves a list of API tokens associated with a single user. - POSTCreate an API token
/users/:user_id/api-tokensCreates an API token - GETGet an API token
/users/:user_id/api-tokens/:token_idRetrieves the specified API token. - DELETEDelete an API token
/users/:user_id/api-tokens/:token_idDeletes an API token
Blackfire Monitoring
- GETGet server cache metrics
/projects/:projectId/environments/:environmentId/observability/server/caches?from=1704067200&to=1704153600Returns time-series PHP cache usage ratios (0.0-1.0) for OPcache memory, OPcache interned strings buffer (ISB), APCu memory, realpath cache, and PCRE cache.… - GETGet server monitoring overview
/projects/:projectId/environments/:environmentId/observability/server?from=1704067200&to=1704153600&keys[]=wtReturns time-series server monitoring data for the specified metrics (wall time, memory usage, peak memory usage, CPU load, stdout, requests per minute).… - GETGet server transaction breakdown
/projects/:projectId/environments/:environmentId/observability/server/transactions-break-down?from=1704067200&to=1704153600Returns transaction breakdown with impact scores, showing how each transaction contributes to overall resource consumption. Includes time-series data for… - GETGet top spans
/projects/:projectId/environments/:environmentId/observability/server/top-spans?from=1704067200&to=1704153600Returns the top spans aggregated across traces, sorted by impact or other metrics. Each span includes wall time, P96, call count, percentage of traces…
Blackfire Profiling
- GETGet profile timeline data
/projects/:projectId/environments/:environmentId/observability/profiles/:uuid/timelineReturns timeline visualization data for a Blackfire profile, showing the execution flow over time. - GETGet profile subprofiles
/projects/:projectId/environments/:environmentId/observability/profiles/:uuid/subprofilesReturns subprofiles (child profiles) associated with a Blackfire profile. - GETGet profile details
/projects/:projectId/environments/:environmentId/observability/profiles/:uuid/profileReturns full profile data including metrics, metadata, and recommendations. - GETGet profile call graph
/projects/:projectId/environments/:environmentId/observability/profiles/:uuid/graphReturns the call graph data for a Blackfire profile, showing function calls and their performance metrics. - GETGet recommendation statistics
/projects/:projectId/environments/:environmentId/observability/profiles/recommendationsReturns recommendation statistics for the environment, optionally filtered by transaction. Proxied from the Blackfire API. Each recommendation includes the… - GETList profiling results
/projects/:projectId/environments/:environmentId/observability/profilesReturns a paginated list of profiles for the environment, optionally filtered by transaction name. Proxied from the Blackfire API.
Connections
- GETList federated login connections
/users/:user_id/connectionsRetrieves a list of connections associated with a single user. - GETGet a federated login connection
/users/:user_id/connections/:providerRetrieves the specified connection. - DELETEDelete a federated login connection
/users/:user_id/connections/:providerDeletes the specified connection.
Continuous Profiling
- GETList profiled applications
/projects/:projectId/environments/:envId/continuous-profilingReturns all applications reporting continuous profiling data for the authenticated agent, scoped to the given time range. Each application includes its… - GETGet application timeline
/projects/:projectId/environments/:envId/continuous-profiling/app/:appReturns timeline data points for the given application and profile type, scoped to the authenticated agent. Points are aggregated at a computed grain (60s to… - GETGet merged profile
/projects/:projectId/environments/:envId/continuous-profiling/app/:app/mergeReturns a merged profile for the given application over the specified time range. The output format is controlled by the out query parameter: pprof returns a… - GETGet application filter values
/projects/:projectId/environments/:envId/continuous-profiling/app/:app/filterReturns available label filter fields and their distinct values for the given application. Use these values to build filter parameters (runtime[],…
Deployment
- GETGet an environment's deployment information
/projects/:projectId/environments/:environmentId/deploymentsRetrieve the read-only configuration of an environment's deployment. The returned information is everything required to recreate a project's current… - GETGet a single environment deployment
/projects/:projectId/environments/:environmentId/deployments/:deploymentIdRetrieve a single deployment configuration with an id of current. This may be subject to change in the future. Only current can be queried. - PATCHUpdate the next deployment
/projects/:projectId/environments/:environmentId/deployments/nextUpdate resources for either webapps, services, or workers in the next deployment.
Diff
- GETlist-projects-git-diffs
/projects/:projectId/git/diffs/:diffBaseId/:diffTargetId
Discounts
- GETGet an organization discount
/discounts/:id - GETGet the value of the First Project Incentive discount
/discounts/types/allowance - GETList organization discounts
/organizations/:organization_id/discountsRetrieves all applicable discounts granted to the specified organization.
Entrypoint
- GETGet observability entrypoint
/projects/:projectId/environments/:environmentId/observabilityReturns API entrypoint with hypermedia links to all observability endpoints (resources, logs, HTTP traffic, continuous profiling, server metrics) following…
Environment Activity
- GETGet environment activity log
/projects/:projectId/environments/:environmentId/activitiesRetrieve an environment's activity log. This returns a list of object with records of actions such as: Commits being pushed to the repository A new… - GETGet an environment activity log entry
/projects/:projectId/environments/:environmentId/activities/:activityIdRetrieve a single environment activity entry as specified by an id returned by the Get environment activities list endpoint. See the documentation on that… - POSTCancel an environment activity
/projects/:projectId/environments/:environmentId/activities/:activityId/cancelCancel a single activity as specified by an id returned by the Get environment activities list endpoint. Please note that not all activities are cancelable.
Grants
- GETList extended access of a user
/users/:user_id/extended-accessList extended access of the given user, which includes both individual and team access to project and organization. - GETGet access document by access ID
/access/:access_idReturns the full access document referenced by token claim access_id.
Http Traffic
- GETGet HTTP traffic timeline by URL
/projects/:projectId/environments/:environmentId/observability/http/breakdown/urls?from=1704067200&to=1704153600Returns HTTP traffic analytics with URLs ranked by impact (response time × request count), aggregated metrics (average, median, p96 response times in… - GETGet HTTP traffic timeline by IP
/projects/:projectId/environments/:environmentId/observability/http/breakdown/ips?from=1704067200&to=1704153600Returns HTTP traffic analytics grouped by IP address with IPs ranked by impact (response time × request count). Use limit parameter to control total items… - GETGet HTTP traffic timeline by user agent
/projects/:projectId/environments/:environmentId/observability/http/breakdown/user-agents?from=1704067200&to=1704153600Returns HTTP traffic analytics grouped by User Agent with User Agents ranked by impact (response time × request count). Use limit parameter to control total…
Mfa
- GETGet information about TOTP enrollment
/users/:user_id/totpRetrieves TOTP enrollment information. - POSTConfirm TOTP enrollment
/users/:user_id/totpConfirms the given TOTP enrollment. - DELETEWithdraw TOTP enrollment
/users/:user_id/totpWithdraws from the TOTP enrollment. - POSTRe-create recovery codes
/users/:user_id/codesRe-creates recovery codes for the MFA enrollment. - GETGet organization MFA settings
/organizations/:organization_id/mfa-enforcementRetrieves MFA settings for the specified organization. - POSTEnable organization MFA enforcement
/organizations/:organization_id/mfa-enforcement/enableEnables MFA enforcement for the specified organization. - POSTDisable organization MFA enforcement
/organizations/:organization_id/mfa-enforcement/disableDisables MFA enforcement for the specified organization. - POSTSend MFA reminders to organization members
/organizations/:organization_id/mfa/remindSends a reminder about setting up MFA to the specified organization members.
Organization Invitations
- GETList invitations to an organization
/organizations/:organization_id/invitationsReturns a list of invitations to an organization. - POSTInvite user to an organization by email
/organizations/:organization_id/invitationsCreates an invitation to an organization for a user with the specified email address. - DELETECancel a pending invitation to an organization
/organizations/:organization_id/invitations/:invitation_idCancels the specified invitation.
Organization Management
- GETEstimate total spend
/organizations/:organization_id/estimateEstimates the total spend for the specified organization. - GETGet billing alert configuration
/organizations/:organization_id/alerts/billingRetrieves billing alert configuration for the specified organization. - PATCHUpdate billing alert configuration
/organizations/:organization_id/alerts/billingUpdates billing alert configuration for the specified organization. - GETGet organization prepayment information
/organizations/:organization_id/prepaymentRetrieves prepayment information for the specified organization, if applicable. - GETList organization prepayment transactions
/organizations/:organization_id/prepayment/transactionsRetrieves a list of prepayment transactions for the specified organization, if applicable.
Organization Members
- GETList organization members
/organizations/:organization_id/membersAccessible to organization owners and members with the "manage members" permission. - POSTCreate organization member
/organizations/:organization_id/membersCreates a new organization member. - GETGet organization member
/organizations/:organization_id/members/:user_idRetrieves the specified organization member. - DELETEDelete organization member
/organizations/:organization_id/members/:user_idDeletes the specified organization member. - PATCHUpdate organization member
/organizations/:organization_id/members/:user_idUpdates the specified organization member.
Organization Projects
- GETList projects
/organizations/:organization_id/projectsRetrieves a list of projects for the specified organization. - POSTCreate project
/organizations/:organization_id/projectsCreates a new project in the specified organization. - GETStream provisioning progress
/organizations/:organization_id/projects/provisioningStreams real-time provisioning progress for projects being created in the specified organization. The response is an NDJSON stream where each line is a JSON… - GETGet project
/organizations/:organization_id/projects/:project_idRetrieves the specified project. - DELETEDelete project
/organizations/:organization_id/projects/:project_idDeletes the specified project. - PATCHUpdate project
/organizations/:organization_id/projects/:project_idUpdates the specified project. - GETQuery project carbon emissions metrics
/organizations/:organization_id/projects/:project_id/metrics/carbonQueries the carbon emission data for the specified project using the supplied parameters.
Organizations
- GETUser organizations
/users/:user_id/organizationsRetrieves organizations that the specified user is a member of. - GETList organizations
/organizationsNon-admin users will only see organizations they are members of. - POSTCreate organization
/organizationsCreates a new organization. - GETGet organization
/organizations/:organization_idRetrieves the specified organization. - DELETEDelete organization
/organizations/:organization_idDeletes the specified organization. - PATCHUpdate organization
/organizations/:organization_idUpdates the specified organization.
PhoneNumber
- POSTVerify phone number
/users/:user_id/phonenumberStarts a phone number verification session. - POSTConfirm phone number
/users/:user_id/phonenumber/:sidConfirms phone number using a verification code.
Profiles
- GETGet address
/organizations/:organization_id/addressRetrieves the address for the specified organization. - PATCHUpdate address
/organizations/:organization_id/addressUpdates the address for the specified organization. - GETGet profile
/organizations/:organization_id/profileRetrieves the profile for the specified organization. - PATCHUpdate profile
/organizations/:organization_id/profileUpdates the profile for the specified organization.
Project Activity
- GETGet project activity log
/projects/:projectId/activitiesRetrieve a project's activity log including logging actions in all environments within a project. This returns a list of objects with records of actions such… - GETGet a project activity log entry
/projects/:projectId/activities/:activityIdRetrieve a single activity log entry as specified by an id returned by the Get project activity log endpoint. See the documentation on that endpoint for… - POSTCancel a project activity
/projects/:projectId/activities/:activityId/cancelCancel a single activity as specified by an id returned by the Get project activity log endpoint. Please note that not all activities are cancelable.
Project Invitations
- GETList invitations to a project
/projects/:project_id/invitationsReturns a list of invitations to a project. - POSTInvite user to a project by email
/projects/:project_id/invitationsCreates an invitation to a project for a user with the specified email address. - DELETECancel a pending invitation to a project
/projects/:project_id/invitations/:invitation_idCancels the specified invitation.
Projects
- GETList project history
/organizations/:organization_id/projects/:project_id/historyRetrieves history records for the specified project, oldest first.
References
- GETList referenced users
/ref/users?in=string&sig=stringRetrieves a list of users referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of… - GETList referenced teams
/ref/teams?in=string&sig=stringRetrieves a list of teams referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of… - GETList referenced organizations
/ref/organizations?in=string&sig=stringRetrieves a list of organizations referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL… - GETList referenced projects
/ref/projects?in=string&sig=stringRetrieves a list of projects referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links… - GETList referenced regions
/ref/regions?in=string&sig=stringRetrieves a list of regions referenced by a trusted service. Clients cannot construct the URL themselves. The correct URL will be provided in the HAL links of…
Regions
- GETList regions
/regionsRetrieves a list of available regions. - GETGet region
/regions/:region_idRetrieves the specified region.
RegistryCredential
- GETlist-projects-oci-registries
/projects/:projectId/oci-registries - POSTcreate-projects-oci-registries
/projects/:projectId/oci-registries - GETget-projects-oci-registries
/projects/:projectId/oci-registries/:registryCredentialId - DELETEdelete-projects-oci-registries
/projects/:projectId/oci-registries/:registryCredentialId - PATCHupdate-projects-oci-registries
/projects/:projectId/oci-registries/:registryCredentialId
Resources
- GETGet resource metrics overview
/projects/:projectId/environments/:environmentId/observability/resources/overview?from=1704067200&to=1704153600Returns time-series resource utilization data for all services. Each timestamp includes per-service metrics: CPU (cores), memory (bytes), swap (bytes),… - GETGet resource metrics summary
/projects/:projectId/environments/:environmentId/observability/resources/summary?from=1704067200&to=1704153600Returns per-instance resource statistics aggregated over the time range. Filter results using aggs[] (min, max, avg, stddev, p50, p95-p99) and types[] (cpu,… - GETGet resource metrics by service
/projects/:projectId/environments/:environmentId/observability/resources/service/:service?from=1704067200&to=1704153600Returns time-series resource data for one service. Each timestamp contains per-instance metrics. Filter results using aggs[] (min, max, avg, stddev, p50,…
Runtime Operations
- POSTExecute a runtime operation
/projects/:projectId/environments/:environmentId/deployments/:deploymentId/operationsExecute a runtime operation on a currently deployed environment. This allows you to run one-off commands, such as rebuilding static assets on demand, by…
Sbom
- GETlist-projects-environments-deployments-sboms
/projects/:projectId/environments/:environmentId/deployments/:deploymentId/sboms - GETget-projects-environments-deployments-sboms
/projects/:projectId/environments/:environmentId/deployments/:deploymentId/sboms/:sbomServiceId
Ssh Keys
- GETGet an SSH key
/ssh_keys/:key_id - DELETEDelete an SSH key
/ssh_keys/:key_id - POSTAdd a new public SSH key to a user
/ssh_keys
Team Access
- GETList team access for a project
/projects/:project_id/team-accessReturns a list of items representing the project access. - POSTGrant team access to a project
/projects/:project_id/team-accessGrants one or more team access to a specific project. - GETGet team access for a project
/projects/:project_id/team-access/:team_idRetrieves the team's permissions for the current project. - DELETERemove team access for a project
/projects/:project_id/team-access/:team_idRemoves the team from the current project. - GETList project access for a team
/teams/:team_id/project-accessReturns a list of items representing the team's project access. - POSTGrant project access to a team
/teams/:team_id/project-accessAdds the team to one or more specified projects. - GETGet project access for a team
/teams/:team_id/project-access/:project_idRetrieves the team's permissions for the current project. - DELETERemove project access for a team
/teams/:team_id/project-access/:project_idRemoves the team from the current project.
Teams
- GETList teams
/teamsRetrieves a list of teams. - POSTCreate team
/teamsCreates a new team. - GETGet team
/teams/:team_idRetrieves the specified team. - DELETEDelete team
/teams/:team_idDeletes the specified team. - PATCHUpdate team
/teams/:team_idUpdates the specified team. - GETList team members
/teams/:team_id/membersRetrieves a list of users associated with a single team. - POSTCreate team member
/teams/:team_id/membersCreates a new team member. - GETGet team member
/teams/:team_id/members/:user_idRetrieves the specified team member. - DELETEDelete team member
/teams/:team_id/members/:user_idDeletes the specified team member. - GETUser teams
/users/:user_id/teamsRetrieves teams that the specified user is a member of.
User Access
- GETList user access for a project
/projects/:project_id/user-accessReturns a list of items representing the project access. - POSTGrant user access to a project
/projects/:project_id/user-accessGrants one or more users access to a specific project. - GETGet user access for a project
/projects/:project_id/user-access/:user_idRetrieves the user's permissions for the current project. - DELETERemove user access for a project
/projects/:project_id/user-access/:user_idRemoves the user from the current project. - PATCHUpdate user access for a project
/projects/:project_id/user-access/:user_idUpdates the user's permissions for the current project. - GETList project access for a user
/users/:user_id/project-accessReturns a list of items representing the user's project access. - POSTGrant project access to a user
/users/:user_id/project-accessAdds the user to one or more specified projects. - GETGet project access for a user
/users/:user_id/project-access/:project_idRetrieves the user's permissions for the current project. - DELETERemove project access for a user
/users/:user_id/project-access/:project_idRemoves the user from the current project. - PATCHUpdate project access for a user
/users/:user_id/project-access/:project_idUpdates the user's permissions for the current project.
User Profiles
- GETList user profiles
/profiles - GETGet a single user profile
/profiles/:userId - PATCHUpdate a user profile
/profiles/:userIdUpdate a user profile, supplying one or more key/value pairs to to change. - GETGet a user address
/profiles/:userId/address - PATCHUpdate a user address
/profiles/:userId/addressUpdate a user address, supplying one or more key/value pairs to to change. - POSTCreate a user profile picture
/profile/:uuid/picture - DELETEDelete a user profile picture
/profile/:uuid/picture
Users
- GETGet current logged-in user info
/meRetrieve information about the currently logged-in user (the user associated with the access token). - POSTCheck if phone verification is required
/me/phoneFind out if the current logged in user requires phone verification to create projects. - POSTCheck if verification is required
/me/verificationFind out if the current logged in user requires verification (phone or staff) to create projects. - GETGet the current user
/users/meRetrieves the current user, determined from the used access token. - GETGet a user by email
/users/email=:emailRetrieves a user matching the specified email address. - GETGet a user by username
/users/username=:usernameRetrieves a user matching the specified username. - GETGet a user
/users/:user_idRetrieves the specified user. - PATCHUpdate a user
/users/:user_idUpdates the specified user. - POSTReset email address
/users/:user_id/emailaddressRequests a reset of the user's email address. A confirmation email will be sent to the new address when the request is accepted. - POSTReset user password
/users/:user_id/resetpasswordRequests a reset of the user's password. A password reset email will be sent to the user when the request is accepted.
- GETQuery project carbon emissions metrics for an entire organization
/organizations/:organization_id/metrics/carbonQueries the carbon emission data for all projects owned by the specified organiation. - GETList support tickets
/tickets
API details
- Authentication
- A bearer token in the Authorization header
- Operations
- 272 operations on 192 pathsGET 152POST 61PATCH 31DELETE 28
- Main resources
- Environment 15Subscriptions 14Domain Management 10Teams 10User Access 10Users 10Cert Management 8Mfa 8Team Access 8Organization Projects 7
- Response formats
application/jsonapplication/problem+jsonapplication/octet-streamapplication/pdf- Description format
- OpenAPI 3.0.1, API version
1.0 - Links
- OpenAPI document · Terms of service · Support
- Listed from
- Upsun's published OpenAPI description (upsun/upsun-sdk-php) (Apache-2.0)
How to test the Upsun REST API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Upsun REST API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get list of SSL certificates” (GET /projects/:projectId/certificates), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Upsun REST API?
Introduction Upsun, formerly Platform.sh, is a container-based Platform-as-a-Service. Our main API is simply Git. With a single git push and a couple of YAML… It is listed under Developer tools and has 272 endpoints.
Who publishes the Upsun REST API?
It is listed from Upsun's public API description (an OpenAPI document), not published by Upsun on Swastik Codes. Anyone who controls upsun.com can claim the profile by adding a DNS TXT record.
How do I authenticate with the Upsun REST API?
With A bearer token in the Authorization header.
How many endpoints does the Upsun REST API have?
272 operations on 192 paths (152 GET, 61 POST, 31 PATCH, 28 DELETE). The largest groups are Environment, Subscriptions, Domain Management, Teams.
Is forking the Upsun REST API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.