Skip to content

API Reference

The PaaS Runtime exposes a REST API at https://runtime.di2amp.com/v1/. The same API is used by:

  • The dashboard (https://ma30.di2amp.com/runtime/dashboard/)
  • The paas CLI
  • Webhooks and CI/CD integrations

OpenAPI spec

The complete OpenAPI 3.1 spec is auto-generated from the Rust handlers via utoipa and served live:

  • JSON — https://runtime.di2amp.com/v1/openapi.json
  • YAML — https://runtime.di2amp.com/v1/openapi.yaml

Interactive API Explorer

The full spec is rendered live below. It pulls the OpenAPI document from the control-plane on page load — so what you see is always in sync with what's deployed.

Loading Swagger UI…

Authentication

All /v1/* endpoints (except /v1/auth/* and /v1/healthz) require a Keycloak-issued JWT in the Authorization header:

Authorization: Bearer <jwt>

Get a token via the CLI:

paas login                          # browser SSO
cat ~/.config/paas/credentials.toml  # access_token = "..."

Or via the auth endpoint directly:

curl -X POST https://runtime.di2amp.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"octave@paas.local","password":"..."}'

Common endpoints

Method Path Purpose
POST /v1/auth/login Issue a JWT
POST /v1/signup Self-service signup (creates Keycloak user + tenant)
GET /v1/apps List apps in the current tenant
POST /v1/apps Create a new app
GET /v1/apps/:id Get an app's details
DELETE /v1/apps/:id Soft-delete an app (restorable 30 days)
GET /v1/apps/:id/deploys List deploys
POST /v1/apps/:id/deploys/:rid/rollback Rollback to a previous release
GET /v1/apps/:id/logs Recent logs (uses SigNoz backend)
GET /v1/apps/:id/metrics?range=1h&kind=cpu Metric time-series
GET /v1/apps/:id/addons List add-ons attached
POST /v1/addons/database Provision a PostgreSQL add-on
GET /v1/apps/:id/processes List process types and pods
POST /v1/apps/:id/restart Rollout-restart all processes

Rate limiting

  • Authenticated: 600 req/min per JWT (rolling)
  • Unauthenticated (/v1/auth/*, /v1/signup): 30 req/min per source IP

Rate-limited responses return 429 Too Many Requests with a Retry-After header.

Errors

All errors use a consistent JSON envelope:

{
  "error": {
    "code": "not_found",
    "message": "App with id <uuid> does not exist or you don't have access.",
    "request_id": "req_01HX...",
    "ts": "2026-05-04T13:42:11Z"
  }
}

Common codes: not_found, forbidden, unauthorized, conflict, validation_failed, rate_limited, internal.

See also