API reference

Everything in the dashboard is available over plain HTTPS with JSON. Most things take one request, and every response tells you what the infrastructure has confirmed.

Authentication

Create a key in Settings → API keys and send it as a bearer token. Keys start with dk_, are shown once, can expire, and are limited to the access you choose: read, write or admin.

The base URL is https://api.dekka.cloud/v1. Send JSON bodies; curl --json sets the right headers for you.

Authenticate

curl https://api.dekka.cloud/v1/me \
  -H "Authorization: Bearer $DEKKA_API_KEY"

Response

{
  "user": { "email": "ama@example.com" },
  "organizations": [{ "id": "…", "name": "Acme" }]
}

Errors

Every error has the same shape: a stable code you can branch on, a message you can show a person, and a request_id to quote if you contact us.

An error

curl https://api.dekka.cloud/v1/projects/$PROJECT/resources \
  -H "Authorization: Bearer $DEKKA_API_KEY" \
  --json '{ "kind": "postgres", "name": "db", "spec": { "storage_mib": 99999 } }'

Response

{
  "error": {
    "code": "entitlement_exceeded",
    "message": "Your plan includes 100 MiB of PostgreSQL storage.",
    "request_id": "9c1e4b7a2f…"
  }
}

Projects

A project holds the services that make up one application, in one region.

Create a project

POST/v1/orgs/{org_id}/projects

Creates a project with a production environment. The region defaults to the first one available.

namestringrequired: A name for the project.
descriptionstring: What the project is for.

Create a project

curl https://api.dekka.cloud/v1/orgs/$ORG/projects \
  -H "Authorization: Bearer $DEKKA_API_KEY" \
  --json '{ "name": "orders" }'

Response

{
  "id": "3f6c1d2e-8a4b-4f0e-9c71-5b2d8e4a6f10",
  "name": "orders",
  "slug": "orders",
  "service_count": 0,
  "environments": [{ "name": "production", "is_default": true }]
}

List projects

GET/v1/orgs/{org_id}/projects

Returns every project in an organisation, newest first, with a summary of its services and last deployment.

List projects

curl https://api.dekka.cloud/v1/orgs/$ORG/projects \
  -H "Authorization: Bearer $DEKKA_API_KEY"

Response

[
  {
    "id": "3f6c1d2e-8a4b-4f0e-9c71-5b2d8e4a6f10",
    "name": "orders",
    "service_count": 2,
    "status": "running"
  }
]

Services

Applications, PostgreSQL databases and object storage buckets. Every change is applied by the infrastructure engine, and status shows what it has confirmed.

Deploy an application

POST/v1/projects/{project_id}/resources

Creates an application from a GitHub repository and starts its first deploy. Give the repository name and branch; Dekka finds the installation itself.

kindstringrequired: application, postgres or object_storage.
namestringrequired: Lowercase letters, numbers and hyphens.
spec.source.repo_full_namestringrequired: The repository, as owner/name.
spec.source.branchstringrequired: Pushes to this branch deploy automatically.
spec.runtime.portinteger: The port your app listens on. Defaults to 3000.

Deploy an application

curl https://api.dekka.cloud/v1/projects/3f6c1d2e-8a4b-4f0e-9c71-5b2d8e4a6f10/resources \
  -H "Authorization: Bearer $DEKKA_API_KEY" \
  --json '{
    "kind": "application",
    "name": "storefront",
    "spec": { "source": { "repo_full_name": "acme/storefront", "branch": "main" } }
  }'

Response

{
  "id": "8b0f3e52-6c1d-4f7a-9a8e-2d5b7c1e9f04",
  "kind": "application",
  "name": "storefront",
  "status": "pending",
  "active_operation": { "type": "application.deploy", "state": "queued" }
}

Add a database

POST/v1/projects/{project_id}/resources

Creates a PostgreSQL database. It is never reachable from the internet; connect an application to it to use it.

spec.versionstring: 16 or 17. Defaults to 16.
spec.storage_mibinteger: Storage to allocate, within your plan.

Add a database

curl https://api.dekka.cloud/v1/projects/3f6c1d2e-8a4b-4f0e-9c71-5b2d8e4a6f10/resources \
  -H "Authorization: Bearer $DEKKA_API_KEY" \
  --json '{ "kind": "postgres", "name": "orders-db", "spec": { "version": "16" } }'

Response

{
  "id": "c41a7d09-3b2e-4e85-b7f1-6a0d9c2e5b31",
  "kind": "postgres",
  "name": "orders-db",
  "status": "pending"
}

Retrieve a service

GET/v1/resources/{resource_id}

Returns a service with the state the engine last confirmed and any operation in progress.

Retrieve a service

curl https://api.dekka.cloud/v1/resources/8b0f3e52-6c1d-4f7a-9a8e-2d5b7c1e9f04 \
  -H "Authorization: Bearer $DEKKA_API_KEY"

Response

{
  "id": "8b0f3e52-6c1d-4f7a-9a8e-2d5b7c1e9f04",
  "status": "running",
  "hostname": "storefront-x2k4.apps.dekka.cloud",
  "active_operation": null
}

Connections

A connection gives one application its own credentials for one database or bucket, and sets the variables it needs.

Connect a service

POST/v1/projects/{project_id}/connections

Connects an application to a database or bucket. The status becomes active once credentials exist, the private path is open and the app has restarted with the new variables.

source_iduuidrequired: The application.
target_iduuidrequired: The database or bucket.

Connect a service

curl https://api.dekka.cloud/v1/projects/3f6c1d2e-8a4b-4f0e-9c71-5b2d8e4a6f10/connections \
  -H "Authorization: Bearer $DEKKA_API_KEY" \
  --json '{ "source_id": "8b0f3e52-6c1d-4f7a-9a8e-2d5b7c1e9f04", "target_id": "c41a7d09-3b2e-4e85-b7f1-6a0d9c2e5b31" }'

Response

{
  "id": "5e9d2b7a-0f4c-4a1e-8d63-b2c7e1f09a48",
  "status": "pending",
  "bindings": []
}

Deployments

Every push to a tracked branch creates a deployment. You can also start one yourself.

Start a deployment

POST/v1/resources/{resource_id}/deployments

Deploys the head of a branch, or a specific commit. A newer deployment replaces any that are still running.

branchstring: Defaults to the application's branch.
commit_shastring: Deploy this commit instead of the branch head.

Start a deployment

curl https://api.dekka.cloud/v1/resources/8b0f3e52-6c1d-4f7a-9a8e-2d5b7c1e9f04/deployments \
  -H "Authorization: Bearer $DEKKA_API_KEY" \
  --json '{}'

Response

{
  "number": 4,
  "status": "queued",
  "branch": "main",
  "commit_sha": "a3f9c21e8d7b6c5a4f3e2d1c0b9a8f7e6d5c4b3a"
}

Read deployment logs

GET/v1/deployments/{deployment_id}/logs

Returns build and deploy log lines in order. Pass after to read only what's new.

afterinteger: Return lines after this sequence number.

Read deployment logs

curl "https://api.dekka.cloud/v1/deployments/$DEPLOYMENT/logs?after=0" \
  -H "Authorization: Bearer $DEKKA_API_KEY"

Response

{
  "lines": [
    { "seq": 1, "stream": "build", "line": "Cloning acme/storefront at a3f9c21" }
  ],
  "next_after": 1
}

Environment variables

Configuration your application reads when it starts. Values are encrypted at rest and secrets are never returned in full.

Set variables

PUT/v1/resources/{resource_id}/env

Creates or updates variables. They reach the application on its next deploy or restart.

varsarrayrequired: Each with key, value and secret.

Set variables

curl -X PUT https://api.dekka.cloud/v1/resources/8b0f3e52-6c1d-4f7a-9a8e-2d5b7c1e9f04/env \
  -H "Authorization: Bearer $DEKKA_API_KEY" \
  --json '{ "vars": [{ "key": "STRIPE_KEY", "value": "sk_live_…", "secret": true }] }'

Response

[
  { "key": "DATABASE_URL", "value": null, "secret": true, "source": "connection" },
  { "key": "STRIPE_KEY", "value": null, "secret": true, "source": "user" }
]