Servers
Dedicated machines in a project. The keys that can log into a server are fixed when it is created — they are written to the machine at first boot — so decide them before provisioning, not after.
Every server in the project, newest first. Terminated servers are omitted.
Each server's status and public address are reconciled with the platform as part of this
read, so a machine that has finished starting reports RUNNING here first.
Auth: a project API key carrying servers:read.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= lengthResponse Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/projects/string/servers"{ "success": true, "data": [ { "id": "string", "organizationId": "string", "name": "string", "type": "LAMP", "region": "string", "instanceType": "string", "image": "string", "status": "PROVISIONING", "ipAddress": "string", "hostname": "string", "sshUser": "string", "phpVersion": "string", "pgVersion": "string", "pgDatabase": "string", "pgUsername": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "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" }}Provisions a server and adds it to the project's subscription.
sshKeyIds is the only chance to decide who can log in: the keys are written to the machine
when it first boots, and none can be added afterwards. A server created without any cannot
be reached at all, short of rebuilding it.
Billing is charged to the project's saved card. A project with no usable card returns 402.
Provisioning is transactional — a failure part-way rolls back what it created.
Auth: a project API key carrying all of servers:read and servers:write.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= lengthRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/projects/string/servers" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "slug": "string", "provider": "digitalocean", "region": "string" }'{ "success": true, "data": { "deployed": 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" }}The server, with the keys authorised on it — enough to build the connect instructions, naming the right user and key.
Auth: a project API key carrying servers:read.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= length1 <= lengthResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/projects/string/servers/string"{ "success": true, "data": { "id": "string", "organizationId": "string", "name": "string", "type": "LAMP", "region": "string", "instanceType": "string", "image": "string", "status": "PROVISIONING", "ipAddress": "string", "hostname": "string", "sshUser": "string", "phpVersion": "string", "pgVersion": "string", "pgDatabase": "string", "pgUsername": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "sshKeys": [ { "id": "string", "name": "string", "fingerprint": "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" }}Renames the machine upstream first, so a failure leaves both sides on the old name rather than disagreeing.
Auth: a project API key carrying all of servers:read and servers:write.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= length1 <= lengthRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/v1/projects/string/servers/string" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "success": true, "data": { "id": "string", "organizationId": "string", "name": "string", "type": "LAMP", "region": "string", "instanceType": "string", "image": "string", "status": "PROVISIONING", "ipAddress": "string", "hostname": "string", "sshUser": "string", "phpVersion": "string", "pgVersion": "string", "pgDatabase": "string", "pgUsername": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "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" }}Destroys the machine and stops billing for it. The data on it is not recoverable.
If the call fails part-way the server stays visible and the call can be retried — it is never left billing invisibly.
Auth: a project API key carrying all of servers:read and servers:write.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= length1 <= lengthResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/v1/projects/string/servers/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" }}Power actions are applied asynchronously, so the server comes back as PROVISIONING — the
state it sits in while the action settles. Read the server again to see where it lands.
Returns 409 if the action does not fit the current state: powering on a running server,
or stopping one that is not running.
Auth: a project API key carrying all of servers:read and servers:write.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= length1 <= lengthRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/projects/string/servers/string/actions" \ -H "Content-Type: application/json" \ -d '{ "action": "power_on" }'{ "success": true, "data": { "id": "string", "organizationId": "string", "name": "string", "type": "LAMP", "region": "string", "instanceType": "string", "image": "string", "status": "PROVISIONING", "ipAddress": "string", "hostname": "string", "sshUser": "string", "phpVersion": "string", "pgVersion": "string", "pgDatabase": "string", "pgUsername": "string", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "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" }}What provisioning a given size would be charged today and each month after, before committing to it.
Auth: a project API key carrying servers:read.
Authorization
apiKey A project API key. X-API-Key: <key> is accepted as an alternative to the Authorization header.
In: header
Path Parameters
1 <= lengthQuery Parameters
Value in
- "digitalocean"
The size to price, as listed by the catalogue.
^[A-Za-z0-9][A-Za-z0-9._-]*$1 <= length <= 64Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/v1/projects/string/servers/preview?provider=digitalocean&slug=string"{ "success": true, "data": { "subtotal": -9007199254740991, "tax": -9007199254740991, "creditApplied": -9007199254740991, "dueToday": -9007199254740991, "monthly": -9007199254740991, "currency": "string", "nextBillingDate": "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" }}Apps
Managed app hosting. An app is either built from a git repository or runs a container image, and is created in two steps: save its configuration as a draft, then create the app from the draft, which charges the project's payment method and starts the first deployment. For an app running an image from one of the project's registries, `imageDeployPolicy` decides what a push to its repository does: `TAG` (the default) redeploys the app when the tag it uses is pushed again, and leaves other tags and an app pinned to a digest alone; `NEWEST` deploys whatever tag was pushed and switches the app to it; `MANUAL` does nothing, and the app moves only through Deploy image. **Environment variables at build time.** An app built from a repository gets its environment variables in the build as well as in the running container, so a value a framework inlines while building — `NEXT_PUBLIC_*`, `VITE_*` — is there. A plain variable is a build argument: a Dockerfile reads it with `ARG NAME`, and an auto-detected build or a static site's build command sees it in its environment without declaring anything. A variable marked secret is a BuildKit secret: it is mounted for the command that reads it and never written to an image layer, the image history or the build cache. A Dockerfile opts in per step with `RUN --mount=type=secret,id=NAME,env=NAME <command>`; auto-detected and static builds see it in the command's environment like a plain one. Names must be identifiers (`[A-Za-z_][A-Za-z0-9_]*`) — a variable named otherwise still reaches the container but is left out of the build. A changed variable is picked up by the next build: a push to the tracked branch, or Redeploy. Variables prefixed `RAILPACK_` also configure an auto-detected build; see the [Railpack reference](https://railpack.com/config/environment-variables). **Configuration file.** An app created from a repository's [configuration file](/docs/guides/app-templates) remembers which file and service it came from, and what the file applied. That is what lets Check configuration file tell the repository moving on apart from a setting changed in the control panel since; whether the file is then ignored, watched or applied on every push is the app's configuration file mode. Every call that changes an app is refused to members with the viewer role, and to a project blocked over an unpaid invoice (`403 ACCOUNT_BLOCKED`). Reading an app's network settings and its recent activity currently sits behind the same gate, and needs `apps:write` as well as `apps:read`. Four calls work with an API key but are not described operation by operation yet, because they answer with the app's full internal record, which is not a stable contract: listing apps (`GET /v1/projects/{projectId}/apps`, `apps:read`), reading one (`GET /v1/projects/{projectId}/apps/{appId}`, `apps:read`), updating its settings and environment variables (`PATCH /v1/projects/{projectId}/apps/{appId}`, `apps:write`) and changing its domain (`PATCH /v1/projects/{projectId}/apps/{appId}/domain`, `apps:write`). Rely only on the fields you also see in the control panel — `id`, `name`, `status`, `url`, the source and build settings, `envVars` — and expect the rest to change. Secret environment variable values come back masked, and a registry credential comes back without its password. Following an app's logs live and opening a console are available in the control panel; the latest log lines are available here.
SSH keys
Public keys that authorise access to the servers in a project. A key is written to a server by cloud-init at first boot, so it must be registered *before* the server that should trust it is created.