The Django Cloud API

Start a browser-approved login

Step 1 of djangocloud login. Show user_code and verification_uri to the user, then poll /auth/token every interval seconds. No token is needed.

Request body (application/json)

Example

curl -X POST https://djangocloud.dev/api/v1/auth/device \
  -H "Content-Type: application/json" \
  -d '{"client_name": "..."}'

Responses

Exchange an approved code for a token

Poll until the user has approved. While waiting it answers 400 with authorization_pending; slow_down means poll less often; expired_token and invalid_grant mean start again. The token is handed over exactly once.

Request body (application/json)

Example

curl -X POST https://djangocloud.dev/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "..."}'

Responses

The signed-in user

Example

curl https://djangocloud.dev/api/v1/me \
  -H "Authorization: Bearer $TOKEN"

Responses

Start putting a card on file

Answers the Stripe Checkout page to open and the session id to confirm with. If a card is already on file it answers {"active": true}.

Example

curl -X POST https://djangocloud.dev/api/v1/billing/checkout \
  -H "Authorization: Bearer $TOKEN"

Responses

Has the checkout put a card on file?

What the CLI polls while the user is on the Stripe page: has this checkout session put a card on file?

Request body (application/json)

Example

curl -X POST https://djangocloud.dev/api/v1/billing/confirm \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "..."}'

Responses

Confirm where apps run

hosted is Fully managed, self is your own AWS account. The plan follows the subscription, so this only confirms the plan the account already has.

Request body (application/json)

Example

curl -X POST https://djangocloud.dev/api/v1/setup/hosting \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hosting": {}}'

Responses

Your AWS connection and how to set up the role

Returns your ExternalId, the role trust policy, a CloudFormation template and the permissions policy. Never returns a secret key.

Example

curl https://djangocloud.dev/api/v1/aws \
  -H "Authorization: Bearer $TOKEN"

Responses

Connect your AWS account

Send role_arn and region. We assume the role with your ExternalId and store no secret; this answers 202 and checks the role in the background, so poll GET /aws until connected is true or error is set. POST does the same.

Request body (application/json)

Example

curl -X PUT https://djangocloud.dev/api/v1/aws \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role_arn": "...", "region": "..."}'

Responses

List your projects

Example

curl https://djangocloud.dev/api/v1/projects \
  -H "Authorization: Bearer $TOKEN"

Responses

Create a project

Request body (application/json)

Example

curl -X POST https://djangocloud.dev/api/v1/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "...", "power": {}, "hosted": true, "region": "..."}'

Responses

The price list

The server sizes and what they cost. No token is needed.

Example

curl https://djangocloud.dev/api/v1/sizes

Responses

Every build setting

Each setting with its default and description. No token is needed.

Example

curl https://djangocloud.dev/api/v1/build-config

Responses

Tear a project down

Deletes the project and everything it left in AWS. This cannot be undone, so the body must repeat the project's slug. A database is deleted after a final snapshot is saved in your AWS account.

Parameters

Example

curl -X DELETE https://djangocloud.dev/api/v1/projects/{project_id} \
  -H "Authorization: Bearer $TOKEN"

Responses

A project, whether it is live, and its latest releases

GET: the project, whether it is live and answering, and its latest releases. DELETE: tear it down.

Parameters

Example

curl https://djangocloud.dev/api/v1/projects/{project_id} \
  -H "Authorization: Bearer $TOKEN"

Responses

Change the server size or the number of instances

Leave a field out to keep its current value. Poll GET /projects/{project_id} and watch resize.status until it is idle or failed.

Parameters

Request body (application/json)

Example

curl -X POST https://djangocloud.dev/api/v1/projects/{project_id}/scale \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"power": "nano", "scale": 1}'

Responses

Start a deploy

Upload the source as a .tar.gz in the multipart field source. Without an upload, the latest commit of the project's connected GitHub repository is deployed. Poll /releases/{release_id} until done.

Parameters

Request body (multipart/form-data)

Example

curl -X POST https://djangocloud.dev/api/v1/projects/{project_id}/releases \
  -H "Authorization: Bearer $TOKEN" \
  -F source=@project.tar.gz

Responses

Go back to an older release

Redeploys that release's image as a new release. Code and environment variables go back; database migrations do not. Poll the returned release like a deploy.

Parameters

Request body (application/json)

Example

curl -X POST https://djangocloud.dev/api/v1/projects/{project_id}/rollback \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1}'

Responses

A release and the log lines since a cursor

Status plus the log lines since ?after=<cursor>; the CLI polls until done.

Parameters

Example

curl https://djangocloud.dev/api/v1/releases/{release_id} \
  -H "Authorization: Bearer $TOKEN"

Responses

Remove environment variables by name

Unknown names are ignored. The variables DjangoCloud manages (the database's) are never removed. Applied from the next deploy.

Parameters

Example

curl -X DELETE https://djangocloud.dev/api/v1/projects/{project_id}/env \
  -H "Authorization: Bearer $TOKEN"

Responses

The names of the environment variables

Never returns values.

Parameters

Example

curl https://djangocloud.dev/api/v1/projects/{project_id}/env \
  -H "Authorization: Bearer $TOKEN"

Responses

Set environment variables

Encrypted, all or nothing, and applied from the next deploy. With replace the others are removed, except the ones DjangoCloud manages.

Parameters

Request body (application/json)

Example

curl -X PUT https://djangocloud.dev/api/v1/projects/{project_id}/env \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"variables": {}, "replace": true}'

Responses

Log lines, oldest first

Without after it returns the latest lines. With after=<cursor> it returns everything newer, which is how djangocloud logs -f follows.

Parameters

Example

curl https://djangocloud.dev/api/v1/projects/{project_id}/logs \
  -H "Authorization: Bearer $TOKEN"

Responses

The autoscaling settings

GET the autoscaling settings. PUT {"enabled": true, "min": 2, "max": 6}; turning it off keeps the range.

Parameters

Example

curl https://djangocloud.dev/api/v1/projects/{project_id}/autoscale \
  -H "Authorization: Bearer $TOKEN"

Responses

Turn autoscaling on or off, and set its range

GET the autoscaling settings. PUT {"enabled": true, "min": 2, "max": 6}; turning it off keeps the range.

Parameters

Request body (application/json)

Example

curl -X PUT https://djangocloud.dev/api/v1/projects/{project_id}/autoscale \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "min": 1, "max": 1}'

Responses

The usage alert settings

GET the alert settings. PUT {"enabled": true, "cpu": 80, "memory": 85, "downtime": true}; any may be left out to keep what is there. Limits are percent of the allocated size.

Parameters

Example

curl https://djangocloud.dev/api/v1/projects/{project_id}/alerts \
  -H "Authorization: Bearer $TOKEN"

Responses

Change the usage alert settings

Leave a field out to keep what is there. Limits are percent of the allocated size.

Parameters

Request body (application/json)

Example

curl -X PUT https://djangocloud.dev/api/v1/projects/{project_id}/alerts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "cpu": 1, "memory": 1, "downtime": true}'

Responses

Whether deploys must have passing tests

GET the policy and the latest reported test run. PUT {"require": true} refuses deploys unless the CLI reports that the tests passed. The report is self-reported: this guards against mistakes, not against a person who sends the flag without running anything.

Parameters

Example

curl https://djangocloud.dev/api/v1/projects/{project_id}/tests \
  -H "Authorization: Bearer $TOKEN"

Responses

Require passing tests for deploys, or stop requiring them

The CLI reports the result of the tests it ran; this is self-reported, so it guards against mistakes rather than against someone who sends the flag without running anything.

Parameters

Request body (application/json)

Example

curl -X PUT https://djangocloud.dev/api/v1/projects/{project_id}/tests \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"require": true}'

Responses

CPU and memory, as percent of the server size

CPU and memory (percent of the allocated size) for since (default 1h, e.g. 30m, 6h, 7d; at most 30d), oldest first, thinned to at most 500 points. latest is the newest sample, whatever its age.

Parameters

Example

curl https://djangocloud.dev/api/v1/projects/{project_id}/metrics \
  -H "Authorization: Bearer $TOKEN"

Responses

The project's database

Parameters

Example

curl https://djangocloud.dev/api/v1/projects/{project_id}/database \
  -H "Authorization: Bearer $TOKEN"

Responses

Open or lock the database's public endpoint

{"public": true} opens the database's public endpoint for an hour (it locks again by itself, see projects.tasks.lock_databases); {"public": false} locks it now, which also cuts off the app until it is opened.

Parameters

Request body (application/json)

Example

curl -X POST https://djangocloud.dev/api/v1/projects/{project_id}/database/network \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"public": true}'

Responses

Take a manual snapshot

snapshot_pending is true until it is done, then last_snapshot shows it. One at a time.

Parameters

Example

curl -X POST https://djangocloud.dev/api/v1/projects/{project_id}/database/snapshot \
  -H "Authorization: Bearer $TOKEN"

Responses