# Services

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

```json
{
  "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](/docs/api/deployments.md).
- `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](/docs/databases.md) 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.

```json
{
  "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](/docs/apps.md)) 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.

```sh
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.

```json
{
  "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.

```sh
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](https://railpack.com), 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](/docs/settings.md#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:

```sh
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`.