ReferenceAPICategories

Settings

Instance-wide configuration — artifact storage, key storage preferences. Build retention and cleanup — automatic cleanup of old builds and artifacts based on age, count, or size policies. Outbound notification channel configuration — webhook, Mattermost. Daemon runtime and metrics.

Get Prometheus metrics

Returns the daemon's Prometheus exposition payload without session authentication.

Response Body

`text/plain`

curl -X GET "https://example.com/metrics"

"string"

Get project retention (effective policy merged with overrides)

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Path Parameters

project_id*string

Project ID

Response Body

`application/json`

curl -X GET "https://example.com/v1/projects/string/retention"

{  "effective": {    "artifact_ttl_days": 0,    "cleanup_interval_secs": 0,    "cleanup_target": "artifacts_only",    "dry_run": true,    "enabled": true,    "keep_statuses": [      "string"    ],    "max_age_days": 0,    "max_artifact_size_bytes": 0,    "max_builds_per_project": 0,    "updated_at": 0  },  "has_override": true,  "override_fields": null}

Delete project retention override (revert to global)

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Path Parameters

project_id*string

Project ID

Response Body

`application/json`

curl -X DELETE "https://example.com/v1/projects/string/retention"

{  "effective": {    "artifact_ttl_days": 0,    "cleanup_interval_secs": 0,    "cleanup_target": "artifacts_only",    "dry_run": true,    "enabled": true,    "keep_statuses": [      "string"    ],    "max_age_days": 0,    "max_artifact_size_bytes": 0,    "max_builds_per_project": 0,    "updated_at": 0  },  "has_override": true,  "override_fields": null}

Update project retention override

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Path Parameters

project_id*string

Project ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X PUT "https://example.com/v1/projects/string/retention" \  -H "Content-Type: application/json" \  -d '{}'

{  "effective": {    "artifact_ttl_days": 0,    "cleanup_interval_secs": 0,    "cleanup_target": "artifacts_only",    "dry_run": true,    "enabled": true,    "keep_statuses": [      "string"    ],    "max_age_days": 0,    "max_artifact_size_bytes": 0,    "max_builds_per_project": 0,    "updated_at": 0  },  "has_override": true,  "override_fields": null}

Get artifact storage settings

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/v1/settings/artifact-storage"

{  "settings": {    "has_access_key_id": true,    "has_secret_access_key": true,    "local_base_dir": "string",    "provider": "disabled",    "s3_bucket": "string",    "s3_endpoint": "string",    "s3_region": "string",    "source": "database",    "updated_at": 0  }}

Update artifact storage settings

Configure the storage backend for build artifacts (local, S3, or R2).

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

`application/json`

curl -X PUT "https://example.com/v1/settings/artifact-storage" \  -H "Content-Type: application/json" \  -d '{    "provider": "disabled"  }'

{  "settings": {    "has_access_key_id": true,    "has_secret_access_key": true,    "local_base_dir": "string",    "provider": "disabled",    "s3_bucket": "string",    "s3_endpoint": "string",    "s3_region": "string",    "source": "database",    "updated_at": 0  }}

Get External Access network settings

Returns effective public URL and allowed frontend origins used by External Access checks.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/v1/settings/external-access/network"

{  "settings": {    "allowed_origins": [      "string"    ],    "artifact_delivery_url": "string",    "public_url": "string",    "source": "database",    "updated_at": 0  }}

Update External Access network settings

Owner-only update for public URL and allowed frontend origins.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

`application/json`

`application/json`

curl -X PUT "https://example.com/v1/settings/external-access/network" \  -H "Content-Type: application/json" \  -d '{    "allowed_origins": [      "string"    ]  }'

{  "settings": {    "allowed_origins": [      "string"    ],    "artifact_delivery_url": "string",    "public_url": "string",    "source": "database",    "updated_at": 0  }}

Get current OIDC configuration for External Access

Returns the current runtime OIDC provider configuration (issuer, client ID, discovered endpoints). Never exposes the client secret.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

`application/json`

`application/json`

curl -X GET "https://example.com/v1/settings/external-access/oidc"

{  "authorization_endpoint": "string",  "client_id": "string",  "configured_at": 0,  "has_client_secret": true,  "issuer_url": "string",  "jwks_uri": "string",  "token_endpoint": "string",  "userinfo_endpoint": "string"}

Configure OIDC for External Access

Owner-only endpoint to configure runtime OIDC after setup is complete. Performs provider discovery and stores issuer/client settings.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

curl -X PUT "https://example.com/v1/settings/external-access/oidc" \  -H "Content-Type: application/json" \  -d '{    "client_id": "string",    "issuer_url": "string"  }'

{  "configured_at": 0,  "discovered_issuer": "string",  "has_client_secret": true}

Test OIDC provider connection

Owner-only endpoint to test OIDC provider discovery without committing changes. Validates that the issuer URL is reachable and returns discovered endpoints.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

`application/json`

`application/json`

curl -X POST "https://example.com/v1/settings/external-access/oidc/test-connection" \  -H "Content-Type: application/json" \  -d '{    "issuer_url": "string"  }'

{  "authorization_endpoint": "string",  "discovered_issuer": "string",  "jwks_uri": "string",  "scopes_supported": [    "string"  ],  "success": true,  "token_endpoint": "string",  "userinfo_endpoint": "string"}

Get External Access preflight readiness

Returns check-by-check readiness required before enabling External Access (runtime_mode=remote).

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/v1/settings/external-access/preflight"

{  "checks": [    {      "failure_code": "string",      "id": "string",      "label": "string",      "message": "string",      "ok": true    }  ],  "ready": true}

Get trusted proxy runtime settings

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

`application/json`

curl -X GET "https://example.com/v1/settings/external-access/trusted-proxy"

{  "settings": {    "has_shared_secret": true,    "has_warpgate_ticket": true,    "trusted_proxy_cidrs": [      "string"    ],    "updated_at": 0,    "user_email_header": "string",    "warpgate_ticket_source": null  }}

Update trusted proxy runtime settings

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

`application/json`

`application/json`

curl -X PUT "https://example.com/v1/settings/external-access/trusted-proxy" \  -H "Content-Type: application/json" \  -d '{}'

{  "settings": {    "has_shared_secret": true,    "has_warpgate_ticket": true,    "trusted_proxy_cidrs": [      "string"    ],    "updated_at": 0,    "user_email_header": "string",    "warpgate_ticket_source": null  }}

List notification channels

Returns all configured notification channels.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Query Parameters

q?string

Search notification channels

sort?string

Sort field

direction?string

Sort direction

limit?integer

Page size

Formatint64

offset?integer

Page offset

Formatint64

Response Body

`application/json`

`application/json`

`application/json`

curl -X GET "https://example.com/v1/settings/notification-channels"

{  "channels": [    {      "channel_type": "webhook",      "created_at": 0,      "created_by": "string",      "enabled": true,      "events": [        "string"      ],      "has_secret": true,      "has_smtp_config": true,      "has_url": true,      "id": "string",      "name": "string",      "updated_at": 0    }  ],  "total": 0}

Create notification channel

Creates a new webhook or Mattermost notification channel.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

curl -X POST "https://example.com/v1/settings/notification-channels" \  -H "Content-Type: application/json" \  -d '{    "channel_type": "webhook",    "name": "string"  }'

{  "channel": {    "channel_type": "webhook",    "created_at": 0,    "created_by": "string",    "enabled": true,    "events": [      "string"    ],    "has_secret": true,    "has_smtp_config": true,    "has_url": true,    "id": "string",    "name": "string",    "updated_at": 0  }}

Get notification channel

Returns details for a single notification channel.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Channel ID

Response Body

`application/json`

`application/json`

`application/json`

curl -X GET "https://example.com/v1/settings/notification-channels/string"

{  "channel": {    "channel_type": "webhook",    "created_at": 0,    "created_by": "string",    "enabled": true,    "events": [      "string"    ],    "has_secret": true,    "has_smtp_config": true,    "has_url": true,    "id": "string",    "name": "string",    "updated_at": 0  }}

Delete notification channel

Permanently deletes a notification channel and its delivery history.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Channel ID

Response Body

`application/json`

`application/json`

`application/json`

curl -X DELETE "https://example.com/v1/settings/notification-channels/string"

{  "deleted": true}

Update notification channel

Updates an existing notification channel. Omitted fields are preserved.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Channel ID

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

curl -X PUT "https://example.com/v1/settings/notification-channels/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "channel": {    "channel_type": "webhook",    "created_at": 0,    "created_by": "string",    "enabled": true,    "events": [      "string"    ],    "has_secret": true,    "has_smtp_config": true,    "has_url": true,    "id": "string",    "name": "string",    "updated_at": 0  }}

List notification deliveries

Returns delivery history for a notification channel (most recent 100).

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Channel ID

Response Body

`application/json`

`application/json`

`application/json`

curl -X GET "https://example.com/v1/settings/notification-channels/string/deliveries"

{  "deliveries": [    {      "attempt_count": 0,      "build_id": "string",      "channel_id": "string",      "created_at": 0,      "delivered_at": 0,      "event_type": "string",      "id": "string",      "last_error": "string",      "status": "pending"    }  ],  "total": 0}

Test notification channel

Sends a test notification to verify the channel is configured correctly.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Path Parameters

id*string

Channel ID

Response Body

`application/json`

`application/json`

`application/json`

curl -X POST "https://example.com/v1/settings/notification-channels/string/test"

{  "error": "string",  "success": true}

Get instance preferences

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/v1/settings/preferences"

{  "preferences": {    "direct_macos_runner_paused": true,    "key_storage_mode": "keychain",    "remote_auth_mode": "oidc",    "restart_required": true,    "runtime_mode": "local",    "updated_at": 0  }}

Update instance preferences

Update instance-wide preferences (e.g. key storage mode).

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

`application/json`

`application/json`

curl -X PUT "https://example.com/v1/settings/preferences" \  -H "Content-Type: application/json" \  -d '{    "key_storage_mode": "keychain"  }'

{  "preferences": {    "direct_macos_runner_paused": true,    "key_storage_mode": "keychain",    "remote_auth_mode": "oidc",    "restart_required": true,    "runtime_mode": "local",    "updated_at": 0  }}

Get global retention policy

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/v1/settings/retention"

{  "policy": {    "artifact_ttl_days": 0,    "cleanup_interval_secs": 0,    "cleanup_target": "artifacts_only",    "dry_run": true,    "enabled": true,    "keep_statuses": [      "string"    ],    "max_age_days": 0,    "max_artifact_size_bytes": 0,    "max_builds_per_project": 0,    "updated_at": 0  }}

Update global retention policy

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X PUT "https://example.com/v1/settings/retention" \  -H "Content-Type: application/json" \  -d '{    "cleanup_target": "artifacts_only",    "enabled": true  }'

{  "policy": {    "artifact_ttl_days": 0,    "cleanup_interval_secs": 0,    "cleanup_target": "artifacts_only",    "dry_run": true,    "enabled": true,    "keep_statuses": [      "string"    ],    "max_age_days": 0,    "max_artifact_size_bytes": 0,    "max_builds_per_project": 0,    "updated_at": 0  }}

Get last cleanup summary

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

curl -X GET "https://example.com/v1/settings/retention/last-cleanup"

{  "last_cleanup": null}

Get backend update state

Reports whether the backend is managed by the supported macOS launchd service and whether an update is currently running. Requires owner role.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

`application/json`

`application/json`

curl -X GET "https://example.com/v1/system/update"

{  "error": "string",  "managed_service": true,  "phase": "idle"}

Start a backend update

Runs the installed updater and hands restart control to the managed macOS launchd service. Requires owner role.

Authorization

bearer_auth

AuthorizationBearer <token>

In: header

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

curl -X POST "https://example.com/v1/system/update"

{  "error": "string",  "managed_service": true,  "phase": "idle"}

Logs

Build log ingestion and retrieval — append, paginated fetch, SSE streaming. Read-only audit trail of all user and system actions.

Runners

Build runner management — register, heartbeat, job claim/status.