REST API

The pipedash-web server exposes every Pipedash operation under /api/v1 and streams events on /api/v1/ws. The web UI calls the same routes. This page lists all of them.

All paths below are relative to /api/v1. The router registers paths that end in / as written, so they keep the slash, for example /api/v1/providers/. Request and response bodies are JSON.

AuthenticationCopy Anchor Link

The server compares the Authorization header with the current value of PIPEDASH_VAULT_PASSWORD. If the variable is not set, every request passes. If it is set, protected routes need this header:

Authorization: Bearer <vault-password>

The comparison runs in constant time. A missing or wrong header returns status 401. The server reads the variable on every request, so opening or closing the vault changes the rule at once.

These paths skip the check:

• Outside the API: any path that does not start with /api/v1/, such as the embedded frontend.
• Prefixes: /api/v1/health, /api/v1/setup and /api/v1/vault.
• Exact paths: /api/v1/ws and /api/v1/plugins. The subpath /api/v1/plugins/metadata needs the header.

/api/v1/factory-reset needs the header like every other route.

ErrorsCopy Anchor Link

Handled errors return a JSON body with code, message and an optional details.

A 401 from the auth check has no body.

Health and setupCopy Anchor Link

Both groups skip authentication.

POST /setup/config takes { "config": { ... }, "vault_password": "<optional>" }. It returns 409 when the instance is already configured.

ProvidersCopy Anchor Link

POST /providers/ takes these fields:

PUT /providers/{id} takes the same body without provider_type.

curl -X POST http://localhost:8080/api/v1/providers/ \
  -H "Authorization: Bearer <vault-password>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub OSS",
    "provider_type": "github",
    "token": "<github-token>",
    "config": { "selected_items": "hcavarsan/pipedash" }
  }'

{
  "id": 1,
  "name": "GitHub OSS",
  "provider_type": "github",
  "config": { "selected_items": "hcavarsan/pipedash" },
  "refresh_interval": 60
}

The response never includes the token. The validate, organizations, permissions and field-options routes take provider_type and config. The preview route also takes org, search, page and page_size. See the provider pages for each config key.

PipelinesCopy Anchor Link

The list routes take an optional provider_id query. /pipelines/lazy also takes page (default 1) and page_size (default 20). /pipelines/{id}/runs takes the same page and page_size.

POST /pipelines/{id}/trigger takes workflow_id (required) and inputs (optional JSON). The server reads the target from workflow_id and ignores the {id} in the path, so the pipeline ID goes in both places. The response holds run_id, a string the provider returns.

curl -X POST "http://localhost:8080/api/v1/pipelines/<pipeline-id>/trigger" \
  -H "Authorization: Bearer <vault-password>" \
  -H "Content-Type: application/json" \
  -d '{ "workflow_id": "<pipeline-id>", "inputs": { "ref": "main" } }'

{ "run_id": "<run-id>" }

GET /pipelines/{id}/workflow-params lists the inputs a pipeline accepts. See trigger and cancel for the UI flow.

PluginsCopy Anchor Link

CacheCopy Anchor Link

MetricsCopy Anchor Link

PUT /metrics/config takes enabled and default_retention_days. The pipeline route takes enabled and retention_days. POST /metrics/flush takes an optional pipeline_id. See metrics.

PreferencesCopy Anchor Link

RefreshCopy Anchor Link

See refresh for the modes and intervals.

StorageCopy Anchor Link

See storage backends for what a migration moves.

VaultCopy Anchor Link

The vault routes skip authentication.

GET /vault/status returns is_unlocked, password_source (env_var, session or none), backend, requires_password and is_first_time.

POST /vault/unlock takes password and returns success and message.

curl -X POST http://localhost:8080/api/v1/vault/unlock \
  -H "Content-Type: application/json" \
  -d '{ "password": "<vault-password>" }'

{ "success": true, "message": "Vault unlocked successfully" }

A failed attempt still returns status 200, with "success": false and a message such as Invalid password or storage error: .... If the vault is already open, the message is Vault is already unlocked.

A successful call sets PIPEDASH_VAULT_PASSWORD in the server process, so later requests must send that password as the bearer token. POST /vault/lock removes the variable. Its message says a restart is needed to clear the token cache fully.

SystemCopy Anchor Link

The response holds providers_removed, caches_cleared, tokens_cleared and metrics_cleared.

WebSocketCopy Anchor Link

Live events stream on /api/v1/ws. When PIPEDASH_VAULT_PASSWORD is set, the first message from the client must be:

{ "type": "auth", "token": "<vault-password>" }

The server closes the socket if the first message is missing, is not valid JSON, has another type or carries a wrong token. The server sends no reply on success. Without a password there is no handshake. After that, every event arrives as a text frame with this envelope:

{ "type": "pipeline-status-changed", "payload": {} }

type is the event name and payload is the event data. The server ignores text frames that the client sends after the handshake. The event names are: