System

Service discovery, health, diagnostics and updates.

14 endpoints · Plakar Control Plane v0.18 · Base URL, authentication and errors

Describe the deployment

GET /api/v1/
No authentication
Returns the version and, to a caller who may read the control plane, the deployment quota and usage.

Response 200 OK application/json

  • enrolled boolean
  • license object nullable
    • expires_at string<date-time>
    • identity_id string<uuid>
    • issued_at string<date-time>
    • mode string nullable
    • organization_id string<uuid>
    • plan string
    • quota_hard integer<int64>
    • quota_soft integer<int64>
  • name string
  • stored_bytes integer nullable
    Max: 1.8446744073709552e+19
  • version string

Errors

  • 400 Bad Request (validation or deserialization error)
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/'

Response 200

{
  "enrolled": true,
  "license": {
    "expires_at": "2026-01-01T00:00:00Z",
    "identity_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "issued_at": "2026-01-01T00:00:00Z",
    "mode": "string",
    "organization_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "plan": "string",
    "quota_hard": 0,
    "quota_soft": 0
  },
  "name": "string",
  "stored_bytes": 0,
  "version": "string"
}

Get the appliance hardware specs

GET /api/v1/appliance/specs
No authentication
Returns the CPU, memory, disks and data filesystem of the host, as reported by the orkestrator. Anonymous until the instance is enrolled, then a badge is required. The CPU, memory and disks are only returned to a caller who may read the control plane. Answers 501 when the orkestrator does not provide them.

Response 200 OK application/json

  • cpu object nullable
    • count integer
    • model string nullable
  • data object
    • free_bytes integer
      Max: 1.8446744073709552e+19
    • fs_type string
    • persistent boolean
    • size_bytes integer
      Max: 1.8446744073709552e+19
  • disks array[object] nullable
    • model string nullable
    • name string
    • size_bytes integer
      Max: 1.8446744073709552e+19
  • memory object nullable
    • available_bytes integer
      Max: 1.8446744073709552e+19
    • total_bytes integer
      Max: 1.8446744073709552e+19
  • warnings array[string]

Errors

  • 400 Bad Request (validation or deserialization error)
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/appliance/specs'

Response 200

{
  "cpu": {
    "count": 0,
    "model": "string"
  },
  "data": {
    "free_bytes": 0,
    "fs_type": "string",
    "persistent": true,
    "size_bytes": 0
  },
  "disks": [
    {
      "model": "string",
      "name": "string",
      "size_bytes": 0
    }
  ],
  "memory": {
    "available_bytes": 0,
    "total_bytes": 0
  },
  "warnings": [
    "string"
  ]
}

Download a database dump

GET /api/v1/database/dump
Badge

Query parameters

  • format string
    Dump encoding.
    Allowed: sql, gzip, gz, zip Default: "sql"

Response 200 The database dump application/gzip

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/database/dump' \
  -H 'Authorization: Bearer <badge>'

Get the debug log state

GET /api/v1/debuglog
Badge

Response 200 OK application/json

  • enabled boolean

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/debuglog' \
  -H 'Authorization: Bearer <badge>'

Response 200

{
  "enabled": true
}

Turn the debug log on or off

PUT /api/v1/debuglog
Badge

Request body application/json required

  • enabled boolean
  • revert_after_seconds integer

Response 200 OK application/json

  • enabled boolean

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl -X PUT 'https://pcp.example.com/api/v1/debuglog' \
  -H 'Authorization: Bearer <badge>' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true,
  "revert_after_seconds": 0
}'

Response 200

{
  "enabled": true
}

Check whether an update is available

GET /api/v1/has-update
Badge

Response 200 OK application/json

  • current_version string
  • description string
  • has_update boolean
  • next_version string

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/has-update' \
  -H 'Authorization: Bearer <badge>'

Response 200

{
  "current_version": "string",
  "description": "string",
  "has_update": true,
  "next_version": "string"
}

Ping the control plane

POST /api/v1/janitor/ping
No authentication
Always answers. The janitor’s ping task polls it.

Response 200 OK application/json

  • pong boolean

Errors

  • 400 Bad Request (validation or deserialization error)
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl -X POST 'https://pcp.example.com/api/v1/janitor/ping'

Response 200

{
  "pong": true
}

Replace the instance license

PUT /api/v1/license
Badge
Installs a freshly issued offline license. It must verify against the builtin offline keys and be minted for the enrolled organization. Owner only.

Request body application/json required

  • license string required

Response 200 OK application/json

  • expires_at string<date-time>
  • identity_id string<uuid>
  • issued_at string<date-time>
  • mode string nullable
  • organization_id string<uuid>
  • plan string
  • quota_hard integer<int64>
  • quota_soft integer<int64>

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl -X PUT 'https://pcp.example.com/api/v1/license' \
  -H 'Authorization: Bearer <badge>' \
  -H 'Content-Type: application/json' \
  -d '{
  "license": "string"
}'

Response 200

{
  "expires_at": "2026-01-01T00:00:00Z",
  "identity_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "issued_at": "2026-01-01T00:00:00Z",
  "mode": "string",
  "organization_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "plan": "string",
  "quota_hard": 0,
  "quota_soft": 0
}

Download the daemon log for a day

GET /api/v1/logs
Badge

Query parameters

  • date string<date-time>
    Day whose log to return. Defaults to today.

Response 200 The gzipped daemon log application/gzip

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/logs' \
  -H 'Authorization: Bearer <badge>'

Get the safe mode state

GET /api/v1/safe-mode
Badge

Response 200 OK application/json

  • by string nullable
  • enabled boolean
  • reason string nullable
  • since string<date-time> nullable

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/api/v1/safe-mode' \
  -H 'Authorization: Bearer <badge>'

Response 200

{
  "by": "string",
  "enabled": true,
  "reason": "string",
  "since": "2026-01-01T00:00:00Z"
}

Turn safe mode on or off

PUT /api/v1/safe-mode
Badge

Request body application/json required

  • enabled boolean
  • reason string
    Max length: 512

Response 200 OK application/json

  • by string nullable
  • enabled boolean
  • reason string nullable
  • since string<date-time> nullable

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl -X PUT 'https://pcp.example.com/api/v1/safe-mode' \
  -H 'Authorization: Bearer <badge>' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true,
  "reason": "string"
}'

Response 200

{
  "by": "string",
  "enabled": true,
  "reason": "string",
  "since": "2026-01-01T00:00:00Z"
}

Update the control plane to the latest version

POST /api/v1/update
Badge

Request body application/json required

  • next_version string

Response 200 OK application/json

  • task_id string<uuid>

Errors

  • 400 Bad Request (validation or deserialization error)
  • 401 Missing, invalid or expired credentials
  • 403 The caller may not do this
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl -X POST 'https://pcp.example.com/api/v1/update' \
  -H 'Authorization: Bearer <badge>' \
  -H 'Content-Type: application/json' \
  -d '{
  "next_version": "string"
}'

Response 200

{
  "task_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
}

Check liveness

GET /health
No authentication

Response 200 OK

No response body.

Errors

  • 400 Bad Request (validation or deserialization error)
  • 500 Internal Server Error (panics)

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/health'

Check readiness

GET /health/ready
No authentication
Answers 503 while the database does not.

Response 200 Ready application/json

  • status string

Errors

  • 400 Bad Request (validation or deserialization error)
  • 500 Internal Server Error (panics)
  • 503 Not ready

Every error returns the standard error body.

Request

curl 'https://pcp.example.com/health/ready'

Response 200

{
  "status": "string"
}

Product

Integrations

Resources

Company

Newsletter