Services

Last updated 05 November 2026

A service is one app: a one-click app, or an app built from a GitHub repo. It has a project and a name, and its id is project/service. dudbox picks the project for you: your organization has one, made when you add your first app.

The examples use API=https://dudbox.com/api/v1 and AUTH="Authorization: Bearer $DUDBOX_TOKEN".

The service object

{
  "id": "o3k9x2a/uptime-kuma",
  "project": "o3k9x2a",
  "name": "uptime-kuma",
  "region": "eu",
  "status": "live",
  "url": "https://uptime-kuma-o3k9x2a.dudbox.app",
  "domains": ["uptime-kuma-o3k9x2a.dudbox.app"],
  "source": "template",
  "template": "uptime-kuma",
  "repo": null,
  "branch": null,
  "live_deployment": { "id": 42, "service": "o3k9x2a/uptime-kuma", "status": "live", "done": true, "…": "…" },
  "pending_deployment": null,
  "login": { "user": "admin", "password_env": "ADMIN_PASSWORD" },
  "usage": { "cpu_percent": 0.4, "memory_bytes": 104857600 }
}

• status: live (it runs), deploying (a deployment is queued, building or starting), failed (the newest deployment failed and nothing runs), down (it should run, but its container stopped), new (never deployed).
• url: the https address. null for a private app, such as a database: other services in the same project reach it by its name.
• source: template (a one-click app or a database), github (built from repo and branch) or upload.
• live_deployment: what runs now. pending_deployment: a deployment in progress. See Deployments.
• login: the first admin login that dudbox made for a one-click app. The password is the env var password_env: GET .../env/{password_env}.

GET /api/v1/templates

The one-click apps and the databases. kind is app or database (Postgres, MySQL, Redis; see Databases for the URL your apps connect with). Only the ones with "deployable": true can be added with POST /api/v1/services; the others still ask questions in the dashboard.

{
  "templates": [
    {
      "name": "uptime-kuma",
      "title": "Uptime Kuma",
      "tagline": "…",
      "about": "…",
      "public": true,
      "login": true,
      "volume": true,
      "deployable": true,
      "kind": "app"
    }
  ]
}

GET /api/v1/services

All your services, in all your projects: {"services": [Service, …]}.

POST /api/v1/services

Adds a one-click app or a database and deploys it. The name is the template's name (then -2, -3, …); the address is made from it. A database gets no address. An app that comes with more (Umami, Libredesk, opendesk; see One-click apps) makes those services too, named after it (umami-db); GET /api/v1/services lists them. An app that makes an owner account (opendesk) makes it with your account's email. The answer is the app itself.

curl -s $API/services -H "$AUTH" -H 'content-type: application/json' -d '{"template": "uptime-kuma"}'

Answer: 201 with the service. Its pending_deployment.id is the first deploy: wait for it with GET /api/v1/deployments/{id}?wait=300.

GET /api/v1/repos

The GitHub repos you can import: the ones where you installed the dudbox GitHub App, as your GitHub login sees them. Newest push first.

{
  "installed": true,
  "install_url": "https://github.com/apps/dudbox-com/installations/new/permissions?target_id=123",
  "repos": [{ "full_name": "acme/shop", "private": true, "default_branch": "main", "pushed_at": "2026-11-04T08:12:00Z" }]
}

To give dudbox more repos, open install_url in a browser. If it answers 409 ("code": "conflict"), log out of dudbox.com and in again with GitHub.

POST /api/v1/services/import

Makes a service from a GitHub repo and deploys the newest commit of the branch. After that, every push to the branch deploys.

curl -s $API/services/import -H "$AUTH" -H 'content-type: application/json' -d '{
  "repo": "acme/shop",
  "branch": "main",
  "dir": "apps/web",
  "name": "shop",
  "env": {"DATABASE_URL": "postgres://…"}
}'

• repo (needed): one of GET /api/v1/repos.
• branch: default, the repo's default branch.
• dir: the folder to build, for a monorepo. Default, the repo root.
• name: default, made from the repo name.
• env: env vars, set as secrets before the first deploy. At most 200.

dudbox builds with Railpack ↗, so most apps need no config. The app must listen on the port in $PORT.

Answer: 201 with the service. A repo that is not in your list gets 403 ("code": "forbidden"), with the install link in hint.

GET /api/v1/services/{project}/{service}

One service, with more fields than in the list:

• port: the port the app listens on.
• health_path: the path of the HTTP health check, or null (then the port must answer).
• release_command: the shell command that runs once per deploy, in the new version, before it starts (like npx prisma migrate deploy), or null. Set it in the dashboard's Settings. See Release command.
• root_dir: the folder that is built, for a GitHub service.
• volumes: its saved folders, [{"name": "data", "path": "/app/data"}]. dudbox backs them up every night.
• deployments: the newest 20, newest first.

DELETE /api/v1/services/{project}/{service}

Stops the app and deletes it. This cannot be undone from the API. Send the service name again:

curl -s -X DELETE $API/services/o3k9x2a/uptime-kuma -H "$AUTH" -H 'content-type: application/json' \
  -d '{"confirm": "uptime-kuma"}'

Answer: 204, no body. A wrong confirm gets 400.