API Reference

Web hosting

PHP websites on Apache. Each site runs in its own container, with its own disk, and answers on its own address under `cosmoner.com` as well as on the domains attached to it. The [Web Hosting guide](/docs/guides/web-hosting) explains the folder layout, SFTP and how PHP runs. A site's tier — `STARTER`, `GROWTH` or `SCALE` — sets its PHP workers, memory, CPU, disk, and how many domains and databases it can have. The limits are recorded on the site when it is created, so List sites shows what each one was given, and retuning a tier later does not change an existing site. Extra disk is bought in blocks on top of the tier when the site is created. Creating a site charges the project's payment method straight away; there is no checkout step. **Files.** A site's files are reached over SFTP, or over SSH where the site gives a shell, at the host, port and username Get connection details returns. The file calls here act on the same folder an SFTP login lands in and run as the site's own user, so what they create is owned by that login. Paths are relative to the home folder, with no leading slash, and an empty path is the home folder itself. They list folders, write text files of up to 1 MB, and create, move and delete files and folders; reading a file's contents, uploading and downloading are done in the control panel or over SFTP. **Domains.** Each domain attached to a site, other than its own address, is a domain you own or a subdomain of one, and it serves a folder, redirects, or is parked. The site's own address takes no subdomains. Attaching a domain is done in the control panel for now; the calls here list a site's domains, change what one does and detach it. **Databases.** A site can have MySQL databases, reached from the site only — not from outside, and not from other resources in the project. How many it can have, and how many connections each gets, depend on its tier. The SFTP password and each database's password are shown in the control panel, and changing a site's tier is done there too. Every call that changes a site, its domains, files or databases is refused to members with the viewer role, and to a project blocked over an unpaid invoice (`403 ACCOUNT_BLOCKED`).

List sites

Every site in the project, newest first, with the limits it was provisioned with and its addresses. Deleted sites are left out.

Auth: a project API key carrying hosting:read.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/hosting/shared"

{  "success": true,  "data": [    {      "id": "string",      "siteName": "string",      "phpVersion": "string",      "unixUser": "string",      "documentRoot": "string",      "internalHostname": "string",      "url": "string",      "tier": "STARTER",      "storageLimitMb": -9007199254740991,      "extraStorageGb": -9007199254740991,      "backupRetentionDays": -9007199254740991,      "bandwidthLimitGb": -9007199254740991,      "cpuQuotaPercent": -9007199254740991,      "memoryMaxMb": -9007199254740991,      "maxDatabases": -9007199254740991,      "maxDomains": -9007199254740991,      "sshEnabled": true,      "status": "PROVISIONING",      "routingStatus": "PENDING",      "sftpHost": "string",      "sftpPort": -9007199254740991,      "createdAt": "2019-08-24T14:15:22Z"    }  ]}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Create a site

Creates a site and provisions it before answering. siteName is 3–40 characters: a lowercase letter, then lowercase letters, numbers or underscores. tier defaults to STARTER and phpVersion to 8.4; 8.3 is the other choice. extraStorageGb buys disk on top of the tier, in whole blocks. List available features gives the block size and the most a site can have.

Every site is backed up nightly. backupRetentionDays is how many days of backups it keeps: 7 (the default, included) or a longer option from List available features, billed per 10 GB of the site's disk.

The site is added to the project's subscription and the prorated amount is charged to the project's payment method; there is no checkout step. A project that cannot be billed is refused with 402 before anything is created — see Billing for the codes.

Send database to create a MySQL database with the site. It is created after the site, and a database that cannot be created does not undo the site: the response then carries databaseError instead of database, and the database can be created again with Create a database.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

siteName*string

Match^[a-z][a-z0-9_]*$

Length3 <= length <= 40

tier?string

Default"STARTER"

Value in

"STARTER"
"GROWTH"
"SCALE"

phpVersion?string

The PHP version: 8.3 or 8.4.

Default"8.4"

Value in

"8.3"
"8.4"

database?

extraStorageGb?integer

Range0 <= value <= 50

Default0

backupRetentionDays?number

Days of nightly backups kept. 7 is included; 30 and 90 are billed per 10 GB of the site's disk.

Default7

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/string/hosting/shared" \  -H "Content-Type: application/json" \  -d '{    "siteName": "string"  }'

{  "success": true,  "data": {    "tenantId": "string",    "status": "ACTIVE",    "database": {      "id": "string",      "name": "string",      "status": "PROVISIONING"    },    "databaseError": "string"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Delete a site

Deletes the site with its files, its databases and its attached domains, and stops billing for it. This cannot be undone. The site's backups are kept for its backup retention after the site is deleted, then removed.

If billing could not be stopped the answer is 502: the site is already taken down, but it stays listed so the deletion can be retried, and should be.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/string/hosting/shared/string"

{  "success": true,  "data": {}}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Get connection details

Where and how to connect to the site's files. SFTP and SSH share one host and port, the same for every site, and the port is never 22; the username picks the site. Plain FTP and FTPS are not offered.

The password is not part of the response. It is shown in the control panel.

Auth: a project API key carrying hosting:read.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/hosting/shared/string/access"

{  "success": true,  "data": {    "username": "string",    "host": "string",    "sftp": {      "port": -9007199254740991    },    "ssh": {      "port": -9007199254740991,      "enabled": true    }  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

List backups

The site's backup retention, its most recent nightly backups and its latest restore. Every site is backed up once a night; retentionDays decides how many days of backups are kept. A backup with restorable set can be passed to Restore a backup.

Auth: a project API key carrying hosting:read.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/hosting/shared/string/backups"

{  "success": true,  "data": {    "retentionDays": -9007199254740991,    "blocks": -9007199254740991,    "repositoryBytes": -9007199254740991,    "lastSucceededAt": "2019-08-24T14:15:22Z",    "runs": [      {        "id": "string",        "status": "RUNNING",        "startedAt": "2019-08-24T14:15:22Z",        "finishedAt": "2019-08-24T14:15:22Z",        "totalBytes": -9007199254740991,        "bytesAdded": -9007199254740991,        "restorable": true,        "databases": [          {            "id": "string",            "name": "string"          }        ]      }    ],    "restore": {      "id": "string",      "status": "RUNNING",      "backupId": "string",      "files": true,      "databases": [        "string"      ],      "backupStartedAt": "2019-08-24T14:15:22Z",      "startedAt": "2019-08-24T14:15:22Z",      "finishedAt": "2019-08-24T14:15:22Z"    }  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Restore a backup

Puts the site's files, any of its databases, or both back exactly as they were in the backup. Without a body it restores the files alone.

Files: changed files are overwritten and files added since are deleted. The tmp folder is left as it is.
Databases: each chosen database is emptied and loaded from the backup, so tables and rows added since are gone. A backup can restore the databases listed in its databases: those it holds a copy of that the site still has. Databases not chosen are left as they are.

This cannot be undone. Answers 202 once the restore has started; the site keeps serving while it runs. Poll List backups until restore.status is no longer RUNNING. Only one restore of a site runs at a time, and none starts while the site is being backed up.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Rate limit: this endpoint is rate limited; a 429 means back off and retry.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

backupId*string

The backup's id, from List backups.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

files?boolean

Put the site's files back as they were in the backup. Defaults to true.

Defaulttrue

databaseIds?array<>

Databases to put back, by id, from the backup's databases. Each one is emptied and loaded from the backup. Defaults to none.

Itemsitems <= 25

Default[]

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/string/hosting/shared/string/backups/string/restore" \  -H "Content-Type: application/json" \  -d '{}'

{  "success": true,  "data": {    "retentionDays": -9007199254740991,    "blocks": -9007199254740991,    "repositoryBytes": -9007199254740991,    "lastSucceededAt": "2019-08-24T14:15:22Z",    "runs": [      {        "id": "string",        "status": "RUNNING",        "startedAt": "2019-08-24T14:15:22Z",        "finishedAt": "2019-08-24T14:15:22Z",        "totalBytes": -9007199254740991,        "bytesAdded": -9007199254740991,        "restorable": true,        "databases": [          {            "id": "string",            "name": "string"          }        ]      }    ],    "restore": {      "id": "string",      "status": "RUNNING",      "backupId": "string",      "files": true,      "databases": [        "string"      ],      "backupStartedAt": "2019-08-24T14:15:22Z",      "startedAt": "2019-08-24T14:15:22Z",      "finishedAt": "2019-08-24T14:15:22Z"    }  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

List databases

The site's MySQL databases, newest first, with the name and user to connect as. Passwords are not included; they are shown in the control panel.

Auth: a project API key carrying hosting:read.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/hosting/shared/string/databases"

{  "success": true,  "data": [    {      "id": "string",      "tenantId": "string",      "name": "string",      "dbName": "string",      "dbUser": "string",      "host": "string",      "port": -9007199254740991,      "tier": "MICRO",      "maxConnections": -9007199254740991,      "maxStatementSeconds": -9007199254740991,      "includedStorageMb": -9007199254740991,      "maxStorageMb": -9007199254740991,      "status": "PROVISIONING",      "createdAt": "2019-08-24T14:15:22Z"    }  ]}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Create a database

Creates a MySQL database and a user for it. name is 1–16 lowercase letters and numbers, starting with a letter; the real database and user name is the site's unixUser, an underscore and name. How many databases a site can have depends on the site's tier.

Each database is billed from creation, on its own tier (Micro when left out): a monthly price per tier, and each GB it holds above the tier's included storage. List database prices has both. The first charge is taken from the project's payment method straight away.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Match^[a-z][a-z0-9]*$

Length1 <= length <= 16

tier?string

The database's tier: MICRO, STANDARD or PLUS. Each is billed per month.

Default"MICRO"

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/string/hosting/shared/string/databases" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "success": true,  "data": {    "databaseId": "string",    "dbName": "string",    "status": "PROVISIONING"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Delete a database

Deletes the database, its data and its user. This cannot be undone.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

databaseId*string

Length1 <= length

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/string/hosting/shared/string/databases/string"

{  "success": true,  "data": {}}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

List domains

Every domain attached to the site, newest first. A domain's routingStatus is VERIFYING until its DNS records are in place and its certificate is issued, then ACTIVE; it is checked again each time the list is read.

Auth: a project API key carrying hosting:read.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/hosting/shared/string/domains"

{  "success": true,  "data": [    {      "id": "string",      "tenantId": "string",      "hostname": "string",      "kind": "SITE",      "documentRoot": "string",      "redirectTarget": "string",      "redirectStatus": -9007199254740991,      "status": "PROVISIONING",      "routingStatus": "PENDING",      "createdAt": "2019-08-24T14:15:22Z"    }  ]}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Attach a domain

Attaches a hostname to the site: one of the project's domains, or a subdomain of one. The domain has to be in the project and verified first: registered or moved to Cosmoner, or added as a domain you manage elsewhere with its TXT record found. Anything else is refused with 422, so no project can attach a name it does not control.

kind, path, redirectTarget and redirectStatus work as in Change a domain. Without path, a website is served from <hostname>/public_html, or for a subdomain of a domain the site already serves from a folder inside that domain's own, and the folder is created.

When Cosmoner runs the domain's DNS, the records in instructions are added for you (dnsRecordsCreated is true), and the hostname goes live once its certificate is issued. Otherwise add them at your DNS provider. Either way routingStatus in List domains reads VERIFYING until it is live.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

hostname*string

Match^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$

Length4 <= length <= 253

kind?string

Default"SITE"

Value in

"SITE"
"REDIRECT"
"PARKED"

path?string

Match^[a-z0-9][a-z0-9._\-]*(\/[a-z0-9][a-z0-9._\-]*)*$

Length1 <= length <= 120

redirectTarget?string

Match^https?:\/\/[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:\d{1,5})?(\/[A-Za-z0-9._~%+\/-]*)?$

Length10 <= length <= 2048

redirectStatus?|

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/string/hosting/shared/string/domains" \  -H "Content-Type: application/json" \  -d '{    "hostname": "string"  }'

{  "success": true,  "data": {    "domainId": "string",    "hostname": "string",    "instructions": {      "recordType": "CNAME",      "name": "string",      "value": "string",      "ownershipVerification": {        "type": "string",        "name": "string",        "value": "string"      },      "status": "string"    },    "dnsRecordsCreated": true  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Change a domain

Changes what the domain does. The body is the domain's whole behaviour, not a partial update: { "kind": "SITE" } alone moves the domain to its default folder.

SITE (the default) serves a folder. path is the folder, relative to the site's home folder; without it, the domain is served from <hostname>/public_html, and a subdomain of a domain the site already serves from a folder inside that domain's own — shop.example.com from example.com/shop. The folder is created if it does not exist.
REDIRECT sends visitors to redirectTarget, a full http or https address without a query string, with the requested path appended. redirectStatus is 301 (the default) or 302.
PARKED shows a placeholder.

A field that belongs to another kind is refused, not ignored. The hostname stays attached, so its DNS records and certificate are untouched.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

domainId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

kind?string

Default"SITE"

Value in

"SITE"
"REDIRECT"
"PARKED"

path?string

Match^[a-z0-9][a-z0-9._\-]*(\/[a-z0-9][a-z0-9._\-]*)*$

Length1 <= length <= 120

redirectTarget?string

Match^https?:\/\/[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:\d{1,5})?(\/[A-Za-z0-9._~%+\/-]*)?$

Length10 <= length <= 2048

redirectStatus?|

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/projects/string/hosting/shared/string/domains/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "success": true,  "data": {}}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Detach a domain

The hostname stops pointing at the site. A folder it served stays where it is, with its files.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

domainId*string

Length1 <= length

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/string/hosting/shared/string/domains/string"

{  "success": true,  "data": {}}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

List a folder

What a folder of the site holds. Omit path, or leave it empty, for the home folder.

Paths are relative to the site's home folder — the folder an SFTP login lands in — with no leading slash. .. is refused, and so is a path that leads out of the home folder through a symbolic link.

Auth: a project API key carrying hosting:read.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Query Parameters

path?string

Lengthlength <= 1024

Default""

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/hosting/shared/string/files"

{  "success": true,  "data": {    "path": "string",    "entries": [      {        "name": "string",        "type": "file",        "size": -9007199254740991,        "modifiedAt": "2019-08-24T14:15:22Z"      }    ]  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Delete a file or folder

Deletes the file at path, or the folder and everything in it. The home folder itself cannot be deleted. This cannot be undone.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Query Parameters

path?string

Lengthlength <= 1024

Default""

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/string/hosting/shared/string/files"

{  "success": true,  "data": {}}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Write a text file

Writes content, up to 1 MB of text, to the file at path, replacing what was there. A file that does not exist is created; the folder it goes in must already exist. The file is written beside its destination and moved into place, so a write that fails leaves the old file as it was.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

path*string

Lengthlength <= 1024

content*string

Lengthlength <= 1048576

Response Body

`application/json`

curl -X PUT "https://example.com/v1/projects/string/hosting/shared/string/files/content" \  -H "Content-Type: application/json" \  -d '{    "path": "string",    "content": "string"  }'

{  "success": true,  "data": {    "path": "string",    "size": -9007199254740991  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Create a folder

Creates the folder at path, and any missing folders above it.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

path*string

Lengthlength <= 1024

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/string/hosting/shared/string/files/folders" \  -H "Content-Type: application/json" \  -d '{    "path": "string"  }'

{  "success": true,  "data": {    "path": "string"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Rename or move a file or folder

Moves the file or folder at from to to, which must not exist yet. The folder to goes in must already exist.

Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

from*string

Lengthlength <= 1024

to*string

Lengthlength <= 1024

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/string/hosting/shared/string/files/rename" \  -H "Content-Type: application/json" \  -d '{    "from": "string",    "to": "string"  }'

{  "success": true,  "data": {    "path": "string"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Get image status

Which build of the site image the site runs, whether a newer patched build of its PHP version is available, whether that update will be applied automatically and when, and what the site can be rolled back to. Also says when security support for the site's PHP version ends.

A site runs one exact build and never changes build on its own, except for an update that fixes a critical or known-exploited vulnerability, which is applied during the night after forcedUpdate.deadline when one is set. A site is never stopped because of a vulnerability.

Auth: a project API key carrying hosting:read.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/hosting/shared/string/image"

{  "success": true,  "data": {    "current": {      "phpVersion": "string",      "tag": "string",      "digest": "string"    },    "updatedAt": "2019-08-24T14:15:22Z",    "update": {      "phpVersion": "string",      "tag": "string",      "digest": "string",      "builtAt": "2019-08-24T14:15:22Z",      "critical": true,      "knownExploited": true,      "cves": [        "string"      ],      "phpPatch": "string",      "phpRelease": true    },    "forcedUpdate": {      "deadline": "2019-08-24T14:15:22Z"    },    "rollback": {      "phpVersion": "string",      "tag": "string",      "digest": "string",      "until": "2019-08-24T14:15:22Z"    },    "rollout": {      "state": "ready",      "reason": "image-pull"    },    "php": {      "version": "string",      "securitySupportEnds": "string",      "deprecated": true,      "offered": [        "string"      ]    }  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Roll back the image

Returns the site to the build it ran before its last update or PHP version change, PHP version included. Accepted until rollback.until in Get image status, 7 days after the change. A rollback cannot itself be rolled back; move forward again with Update the image.

Rolling back an automatic security update postpones it: it gets a new deadline and is applied again after that.

The site restarts onto the new build, which interrupts it for a few seconds. This answers once the restart has started, with rollout.state updating; Get image status says when it is ready, or failed if the site cannot start on the new build. If the restart cannot be started, nothing changes and the error is returned.

Members with the viewer role are refused. A project blocked over an unpaid invoice may still make this change: it costs nothing and keeps the site patched.

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/string/hosting/shared/string/image/rollback"

{  "success": true,  "data": {    "current": {      "phpVersion": "string",      "tag": "string",      "digest": "string"    },    "updatedAt": "2019-08-24T14:15:22Z",    "update": {      "phpVersion": "string",      "tag": "string",      "digest": "string",      "builtAt": "2019-08-24T14:15:22Z",      "critical": true,      "knownExploited": true,      "cves": [        "string"      ],      "phpPatch": "string",      "phpRelease": true    },    "forcedUpdate": {      "deadline": "2019-08-24T14:15:22Z"    },    "rollback": {      "phpVersion": "string",      "tag": "string",      "digest": "string",      "until": "2019-08-24T14:15:22Z"    },    "rollout": {      "state": "ready",      "reason": "image-pull"    },    "php": {      "version": "string",      "securitySupportEnds": "string",      "deprecated": true,      "offered": [        "string"      ]    }  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Update the image

Moves the site to the newest patched build of its PHP version, the update in Get image status. The build it ran before can be restored with Roll back the image for 7 days.

Members with the viewer role are refused. A project blocked over an unpaid invoice may still make this change: it costs nothing and keeps the site patched.

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Response Body

`application/json`

curl -X POST "https://example.com/v1/projects/string/hosting/shared/string/image/update"

{  "success": true,  "data": {    "current": {      "phpVersion": "string",      "tag": "string",      "digest": "string"    },    "updatedAt": "2019-08-24T14:15:22Z",    "update": {      "phpVersion": "string",      "tag": "string",      "digest": "string",      "builtAt": "2019-08-24T14:15:22Z",      "critical": true,      "knownExploited": true,      "cves": [        "string"      ],      "phpPatch": "string",      "phpRelease": true    },    "forcedUpdate": {      "deadline": "2019-08-24T14:15:22Z"    },    "rollback": {      "phpVersion": "string",      "tag": "string",      "digest": "string",      "until": "2019-08-24T14:15:22Z"    },    "rollout": {      "state": "ready",      "reason": "image-pull"    },    "php": {      "version": "string",      "securitySupportEnds": "string",      "deprecated": true,      "offered": [        "string"      ]    }  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Get email status

Whether the site's PHP mail() can send, the address it sends as, and the project's verified email domains it could send from. Until email is turned on, mail() returns false and logs why.

Auth: a project API key carrying hosting:read.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/hosting/shared/string/mail"

{  "success": true,  "data": {    "available": true,    "enabled": true,    "fromAddress": "string",    "credentialId": "string",    "emailDomainId": "string",    "domains": [      {        "id": "string",        "name": "string"      }    ]  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Turn off email

Stops the site sending email and deletes its SMTP credential. Afterwards mail() returns false. Members with the viewer role are refused.

Auth: a project API key carrying all of hosting:read, hosting:write and email:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/string/hosting/shared/string/mail"

{  "success": true,  "data": {    "available": true,    "enabled": true,    "fromAddress": "string",    "credentialId": "string",    "emailDomainId": "string",    "domains": [      {        "id": "string",        "name": "string"      }    ]  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Turn on email

Lets the site's PHP mail() send as <localPart>@<domain>, through a new SMTP credential on the project's verified email domain emailDomainId. The credential is listed with the domain's other credentials. Every email the site sends is billed on the project's email plan, like any other. Sent again with another address, it replaces the site's credential. The site does not restart.

Needs email write access as well as hosting write access, and a key with email:write. Members with the viewer role are refused, as is a project blocked over an unpaid invoice (403 ACCOUNT_BLOCKED).

Auth: a project API key carrying all of hosting:read, hosting:write and email:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

emailDomainId*string

A verified email domain of the project, from List email domains.

Length1 <= length

localPart*string

The part before the @ of the address the site sends as, e.g. wordpress.

Match^[a-z0-9](?:[a-z0-9._+-]*[a-z0-9])?$

Length1 <= length <= 64

Response Body

`application/json`

curl -X PUT "https://example.com/v1/projects/string/hosting/shared/string/mail" \  -H "Content-Type: application/json" \  -d '{    "emailDomainId": "string",    "localPart": "string"  }'

{  "success": true,  "data": {    "available": true,    "enabled": true,    "fromAddress": "string",    "credentialId": "string",    "emailDomainId": "string",    "domains": [      {        "id": "string",        "name": "string"      }    ]  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Change the PHP version

Moves the site to another PHP version, onto the newest patched build of it. Only the versions in php.offered from Get image status are accepted. Test the site afterwards: a new PHP version can break an application. The previous version can be restored with Roll back the image for 7 days.

Members with the viewer role are refused. A project blocked over an unpaid invoice may still make this change: it costs nothing and keeps the site patched.

Auth: a project API key carrying all of hosting:read and hosting:write.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

tenantId*string

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

phpVersion*string

The PHP version: 8.3 or 8.4.

Value in

"8.3"
"8.4"

Response Body

`application/json`

curl -X PATCH "https://example.com/v1/projects/string/hosting/shared/string/php-version" \  -H "Content-Type: application/json" \  -d '{    "phpVersion": "8.3"  }'

{  "success": true,  "data": {    "current": {      "phpVersion": "string",      "tag": "string",      "digest": "string"    },    "updatedAt": "2019-08-24T14:15:22Z",    "update": {      "phpVersion": "string",      "tag": "string",      "digest": "string",      "builtAt": "2019-08-24T14:15:22Z",      "critical": true,      "knownExploited": true,      "cves": [        "string"      ],      "phpPatch": "string",      "phpRelease": true    },    "forcedUpdate": {      "deadline": "2019-08-24T14:15:22Z"    },    "rollback": {      "phpVersion": "string",      "tag": "string",      "digest": "string",      "until": "2019-08-24T14:15:22Z"    },    "rollout": {      "state": "ready",      "reason": "image-pull"    },    "php": {      "version": "string",      "securitySupportEnds": "string",      "deprecated": true,      "offered": [        "string"      ]    }  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

List database prices

What a MySQL database costs: the monthly price of each database tier, and of each GB a database holds above its tier's included storage. No site tier includes a database.

Auth: a project API key carrying hosting:read.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/hosting/shared/database-prices"

{  "success": true,  "data": {    "tiers": [      {        "tier": "MICRO",        "monthly": -9007199254740991,        "currency": "string"      }    ],    "storagePerGbMonthly": -9007199254740991,    "currency": "string"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

List available features

What can be added to a site here beyond the site itself: MySQL databases, and extra disk with its price. Check it before sending database or extraStorageGb to Create a site.

Auth: a project API key carrying hosting:read.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/hosting/shared/features"

{  "success": true,  "data": {    "databases": true,    "extraStorage": {      "blockGb": -9007199254740991,      "maxExtraGb": -9007199254740991,      "monthly": -9007199254740991,      "currency": "string"    },    "backupRetention": [      {        "retentionDays": -9007199254740991,        "blockGb": -9007199254740991,        "monthly": -9007199254740991,        "currency": "string"      }    ],    "restores": true  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

List tier prices

The monthly list price of each tier. See Web Hosting → Tiers for what each tier includes.

Auth: a project API key carrying hosting:read.

Authorization

apiKey

AuthorizationBearer <token>

A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.

In: header

Path Parameters

projectId*string

Length1 <= length

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/hosting/shared/prices"

{  "success": true,  "data": [    {      "tier": "STARTER",      "monthly": -9007199254740991,      "currency": "string"    }  ]}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

{  "success": false,  "error": {    "code": "string",    "message": "string",    "details": {      "property1": null,      "property2": null    },    "issues": null,    "docsUrl": "http://example.com"  }}

Support tickets

Conversations with the support team. A ticket belongs to one project, and an API key reaches only the tickets of the project it was issued for. Each ticket carries its whole conversation as a timeline of events, oldest first; when support replies, the ticket moves to `PENDING` and the member who opened it is emailed. Your own reply moves it back to `OPEN`.

Shared databases

A shared database is a PostgreSQL database of its own, with its own user, on a server it shares with other databases. Only its user can reach it: connecting to the database, and using its `public` schema, are revoked from every other user on the server. **No new shared databases can be created.** Existing ones keep working and stay manageable. For a new database, create a dedicated PostgreSQL database instead; see the [Databases guide](/docs/guides/databases). **Connecting.** Use any PostgreSQL client or ORM. TLS is required: `postgresql://<dbUser>:<password>@<host>:<port>/<dbName>?sslmode=require`. A database with a connection pooler — `poolName` and `poolPort` are set — can also be reached through it, which lets more clients share the database's few connections: `postgresql://<dbUser>:<password>@<host>:<poolPort>/<poolName>?sslmode=require`. `poolMode` says when the pooler takes a server connection back: `TRANSACTION` at the end of each transaction, so session state such as `SET` and advisory locks does not carry over from one transaction to the next; `SESSION` when the client disconnects; `STATEMENT` after every statement, so a transaction spanning several statements is refused. **Tiers.** A database's tier — `MICRO`, `STARTER`, `GROWTH` or `SCALE` — sets `maxConnections`, the most connections its user can hold open on the server at once. The pooler's own connections to the server count towards it, so going through the pooler is how to serve more clients than that. **Password.** The password is returned once — when the database was created, and each time its password is rotated — and only a hash of it is kept, so it cannot be read back. Rotating it is done in the control panel for now. New connections need the new password at once; connections already open are not closed. Listing the project's shared databases (`GET /v1/projects/{projectId}/databases/shared`) and reading one (`GET /v1/projects/{projectId}/databases/shared/{tenantId}`) work with an API key and `databases:read`, but are not described operation by operation yet: alongside the connection details, their responses describe the server the database is placed on, which is not a stable contract. The `id` they return is the `tenantId` below. A deleted database is no longer listed.

Web hosting

200application/json

401application/json

403application/json

422application/json

500application/json

201application/json

401application/json

402application/json

403application/json

422application/json

500application/json

200application/json

401application/json

403application/json

404application/json

422application/json

500application/json

502application/json

200application/json

401application/json

403application/json

404application/json

422application/json

500application/json

200application/json

401application/json

403application/json

404application/json

422application/json

500application/json

202application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

503application/json

200application/json

401application/json

403application/json

404application/json

422application/json

500application/json

201application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

422application/json

500application/json

502application/json

200application/json

401application/json

403application/json

404application/json

422application/json

500application/json

200application/json

401application/json

403application/json

404application/json

422application/json

500application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

422application/json

500application/json

200application/json

400application/json

401application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`