Agent

Endpoints agents call to claim and report on work.

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

List the pending one-off tasks

GET /api/v1/agent/at/tasks
Agent token

Query parameters

  • from integer<int64> required
    Only tasks due from this time, in unix seconds.
  • offset integer
    Number of items to skip.
    Default: 0
  • limit integer
    Maximum number of items to return.
    Default: 100 Min: 1 Max: 100

Response 200 OK application/json

  • created_id string<date-time>
  • id string<uuid>
  • schedule_at string<date-time>
  • scheduler_id string<uuid>
  • 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 'https://pcp.example.com/api/v1/agent/at/tasks' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

[
  {
    "created_id": "2026-01-01T00:00:00Z",
    "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "schedule_at": "2026-01-01T00:00:00Z",
    "scheduler_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "task_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
  }
]

Get a connector configuration

GET /api/v1/agent/configurations/{configuration_id}
Agent token

Path parameters

  • configuration_id string required

Response 200 OK application/json

  • data_classes array[string] nullable
  • environment string nullable
  • fields array[object]
    • key string
    • provider object recursive
    • val string
  • id string<uuid>
  • integration object
    • id string<uuid>
    • name string
    • version string
  • name string
  • revision integer
  • type string
  • urn string
  • urnid 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 'https://pcp.example.com/api/v1/agent/configurations/{configuration_id}' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "data_classes": [
    "string"
  ],
  "environment": "string",
  "fields": [
    {
      "key": "string",
      "provider": {},
      "val": "string"
    }
  ],
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "integration": {
    "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "name": "string",
    "version": "string"
  },
  "name": "string",
  "revision": 0,
  "type": "string",
  "urn": "string",
  "urnid": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
}

Check the quotas

POST /api/v1/agent/janitor/check-quotas
Agent token

Response 200 OK application/json

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/agent/janitor/check-quotas' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{}

Convert configurations stored as rows

POST /api/v1/agent/janitor/configurations/convert
Agent token
Converts a batch of rows-only connectors and secret providers to documents at their current revision.

Request body application/json required

  • connectors_after string<uuid>
  • providers_after string<uuid>

Response 200 OK application/json

  • connectors_after string<uuid>
  • converted integer
  • more boolean
  • providers_after string<uuid>
  • skipped integer

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/agent/janitor/configurations/convert' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "connectors_after": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "providers_after": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
}'

Response 200

{
  "connectors_after": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "converted": 0,
  "more": true,
  "providers_after": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "skipped": 0
}

Deliver the pending mails

POST /api/v1/agent/janitor/mails/deliver
Agent token

Response 200 OK application/json

  • failed integer
  • organizations integer
  • sent integer

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/agent/janitor/mails/deliver' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "failed": 0,
  "organizations": 0,
  "sent": 0
}

Delete the expired OAuth tokens and codes, and the ended grants

POST /api/v1/agent/janitor/oauth/purge
Agent token

Response 200 OK application/json

  • access_tokens integer<int64>
  • codes integer<int64>
  • grants 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 POST 'https://pcp.example.com/api/v1/agent/janitor/oauth/purge' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "access_tokens": 0,
  "codes": 0,
  "grants": 0
}

Apply the SLA schedule plan

POST /api/v1/agent/janitor/sla-schedule-plan/apply
Agent token

Response 200 OK application/json

  • tasks_applied integer

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/agent/janitor/sla-schedule-plan/apply' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "tasks_applied": 0
}

Rebuild the SLA schedule plan

POST /api/v1/agent/janitor/sla-schedule-plan/rebuild
Agent token

Response 200 OK application/json

  • rows_created integer

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/agent/janitor/sla-schedule-plan/rebuild' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "rows_created": 0
}

List the janitor tasks

GET /api/v1/agent/janitor/tasks
Agent token

Response 200 OK application/json

  • id string<uuid>
  • interval integer<int64>
  • key string
  • name string
  • status string
  • ttl 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 'https://pcp.example.com/api/v1/agent/janitor/tasks' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

[
  {
    "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "interval": 0,
    "key": "string",
    "name": "string",
    "status": "string",
    "ttl": 0
  }
]

Register a janitor task

POST /api/v1/agent/janitor/tasks
Agent token

Request body application/json required

  • interval integer<int64>
  • key string
  • name string
  • ttl integer<int64>

Response 200 OK application/json

  • id string<uuid>
  • interval integer<int64>
  • key string
  • name string
  • status string
  • ttl 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 POST 'https://pcp.example.com/api/v1/agent/janitor/tasks' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "interval": 0,
  "key": "string",
  "name": "string",
  "ttl": 0
}'

Response 200

{
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "interval": 0,
  "key": "string",
  "name": "string",
  "status": "string",
  "ttl": 0
}

Start a janitor run

POST /api/v1/agent/janitor/tasks/{task_id}/runs/start
Agent token

Path parameters

  • task_id string required

Response 200 OK application/json

  • run_id string<uuid>
  • started_at string<date-time>
  • state

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/agent/janitor/tasks/{task_id}/runs/start' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "run_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "started_at": "2026-01-01T00:00:00Z",
  "state": {}
}

Finish a janitor run

POST /api/v1/agent/janitor/tasks/{task_id}/runs/{run_id}/finish
Agent token

Path parameters

  • task_id string required
  • run_id string required

Request body application/json required

  • duration integer<int64>
  • outcome string
  • state

Response 200 OK application/json

  • id string<uuid>
  • interval integer<int64>
  • key string
  • name string
  • status string
  • ttl 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 POST 'https://pcp.example.com/api/v1/agent/janitor/tasks/{task_id}/runs/{run_id}/finish' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "duration": 0,
  "outcome": "string",
  "state": {}
}'

Response 200

{
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "interval": 0,
  "key": "string",
  "name": "string",
  "status": "string",
  "ttl": 0
}

Fold the usage rollup

POST /api/v1/agent/janitor/usage-rollup/fold
Agent token

Response 200 OK application/json

  • entries_folded integer
  • more 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 POST 'https://pcp.example.com/api/v1/agent/janitor/usage-rollup/fold' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "entries_folded": 0,
  "more": true
}

Synchronise the vector configuration

POST /api/v1/agent/janitor/vector-config/sync
Agent token

Response 200 OK application/json

  • changed boolean
  • 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 POST 'https://pcp.example.com/api/v1/agent/janitor/vector-config/sync' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "changed": true,
  "enabled": true
}

Deliver the pending webhooks

POST /api/v1/agent/janitor/webhooks/deliver
Agent token

Response 200 OK application/json

  • delivered integer
  • failed integer
  • organizations integer
  • retired integer

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/agent/janitor/webhooks/deliver' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "delivered": 0,
  "failed": 0,
  "organizations": 0,
  "retired": 0
}

List the running jobs

GET /api/v1/agent/jobs
Agent token

Response 200 OK application/json

  • at_id string<uuid>
  • cron_id string<uuid>
  • id string<uuid>
  • identity_id string<uuid>
  • schedule_at string<date-time>
  • schedule_id string<uuid>
  • scheduler_id string<uuid>
  • started_at string<date-time>
  • status string
  • stopped_at string<date-time>
  • 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 'https://pcp.example.com/api/v1/agent/jobs' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

[
  {
    "at_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "cron_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "identity_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "schedule_at": "2026-01-01T00:00:00Z",
    "schedule_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "scheduler_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "started_at": "2026-01-01T00:00:00Z",
    "status": "string",
    "stopped_at": "2026-01-01T00:00:00Z",
    "task_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
  }
]

Queue a job

POST /api/v1/agent/jobs
Agent token

Request body application/json required

  • at_id string<uuid>
  • cron_id string<uuid>
  • id string<uuid>
  • identity_id string<uuid>
  • schedule_at string<date-time>
  • schedule_id string<uuid>
  • scheduler_id string<uuid>
  • started_at string<date-time>
  • status string
  • stopped_at string<date-time>
  • task_id string<uuid>

Response 200 OK application/json

  • at_id string<uuid>
  • cron_id string<uuid>
  • id string<uuid>
  • identity_id string<uuid>
  • schedule_at string<date-time>
  • schedule_id string<uuid>
  • scheduler_id string<uuid>
  • started_at string<date-time>
  • status string
  • stopped_at string<date-time>
  • 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/agent/jobs' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "at_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "cron_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "identity_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "schedule_at": "2026-01-01T00:00:00Z",
  "schedule_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "scheduler_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "started_at": "2026-01-01T00:00:00Z",
  "status": "string",
  "stopped_at": "2026-01-01T00:00:00Z",
  "task_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
}'

Response 200

{
  "at_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "cron_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "identity_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "schedule_at": "2026-01-01T00:00:00Z",
  "schedule_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "scheduler_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "started_at": "2026-01-01T00:00:00Z",
  "status": "string",
  "stopped_at": "2026-01-01T00:00:00Z",
  "task_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
}

Mark a job canceled

POST /api/v1/agent/jobs/{job_id}/cancel
Agent token

Path parameters

  • job_id string required

Request body application/json required

  • error string nullable
  • log string

Response 200 OK application/json

  • at_id string<uuid>
  • cron_id string<uuid>
  • id string<uuid>
  • identity_id string<uuid>
  • schedule_at string<date-time>
  • schedule_id string<uuid>
  • scheduler_id string<uuid>
  • started_at string<date-time>
  • status string
  • stopped_at string<date-time>
  • 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/agent/jobs/{job_id}/cancel' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "error": "string",
  "log": "string"
}'

Response 200

{
  "at_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "cron_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "identity_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "schedule_at": "2026-01-01T00:00:00Z",
  "schedule_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "scheduler_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "started_at": "2026-01-01T00:00:00Z",
  "status": "string",
  "stopped_at": "2026-01-01T00:00:00Z",
  "task_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
}

Mark a job failed

POST /api/v1/agent/jobs/{job_id}/fail
Agent token

Path parameters

  • job_id string required

Request body application/json required

  • error string nullable
  • log string

Response 200 OK application/json

  • at_id string<uuid>
  • cron_id string<uuid>
  • id string<uuid>
  • identity_id string<uuid>
  • schedule_at string<date-time>
  • schedule_id string<uuid>
  • scheduler_id string<uuid>
  • started_at string<date-time>
  • status string
  • stopped_at string<date-time>
  • 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/agent/jobs/{job_id}/fail' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "error": "string",
  "log": "string"
}'

Response 200

{
  "at_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "cron_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "identity_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "schedule_at": "2026-01-01T00:00:00Z",
  "schedule_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "scheduler_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "started_at": "2026-01-01T00:00:00Z",
  "status": "string",
  "stopped_at": "2026-01-01T00:00:00Z",
  "task_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
}

Mark a job started

POST /api/v1/agent/jobs/{job_id}/start
Agent token

Path parameters

  • job_id string required

Response 200 OK application/json

  • at_id string<uuid>
  • cron_id string<uuid>
  • id string<uuid>
  • identity_id string<uuid>
  • schedule_at string<date-time>
  • schedule_id string<uuid>
  • scheduler_id string<uuid>
  • started_at string<date-time>
  • status string
  • stopped_at string<date-time>
  • 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/agent/jobs/{job_id}/start' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "at_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "cron_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "identity_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "schedule_at": "2026-01-01T00:00:00Z",
  "schedule_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "scheduler_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "started_at": "2026-01-01T00:00:00Z",
  "status": "string",
  "stopped_at": "2026-01-01T00:00:00Z",
  "task_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
}

Mark a job succeeded

POST /api/v1/agent/jobs/{job_id}/succeed
Agent token

Path parameters

  • job_id string required

Request body application/json required

  • error string nullable
  • log string

Response 200 OK application/json

  • at_id string<uuid>
  • cron_id string<uuid>
  • id string<uuid>
  • identity_id string<uuid>
  • schedule_at string<date-time>
  • schedule_id string<uuid>
  • scheduler_id string<uuid>
  • started_at string<date-time>
  • status string
  • stopped_at string<date-time>
  • 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/agent/jobs/{job_id}/succeed' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "error": "string",
  "log": "string"
}'

Response 200

{
  "at_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "cron_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "identity_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "schedule_at": "2026-01-01T00:00:00Z",
  "schedule_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "scheduler_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "started_at": "2026-01-01T00:00:00Z",
  "status": "string",
  "stopped_at": "2026-01-01T00:00:00Z",
  "task_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
}

Report job progress

POST /api/v1/agent/jobs/{job_id}/update
Agent token

Path parameters

  • job_id string required

Request body application/json required

  • log string
  • state object nullable
    • chunks object
      • cached integer
        Max: 1.8446744073709552e+19
      • cached_size integer
        Max: 1.8446744073709552e+19
      • error integer
        Max: 1.8446744073709552e+19
      • ok integer
        Max: 1.8446744073709552e+19
      • size integer
        Max: 1.8446744073709552e+19
      • total integer
        Max: 1.8446744073709552e+19
    • dirs object
      • cached integer
        Max: 1.8446744073709552e+19
      • cached_size integer
        Max: 1.8446744073709552e+19
      • error integer
        Max: 1.8446744073709552e+19
      • ok integer
        Max: 1.8446744073709552e+19
      • size integer
        Max: 1.8446744073709552e+19
      • total integer
        Max: 1.8446744073709552e+19
    • files object
      • cached integer
        Max: 1.8446744073709552e+19
      • cached_size integer
        Max: 1.8446744073709552e+19
      • error integer
        Max: 1.8446744073709552e+19
      • ok integer
        Max: 1.8446744073709552e+19
      • size integer
        Max: 1.8446744073709552e+19
      • total integer
        Max: 1.8446744073709552e+19
    • io map[object]
      • r object
        • latency object
          • avg integer<int64>
          • count integer<int64>
          • max integer<int64>
          • p50 integer<int64>
          • p95 integer<int64>
        • overall number<double>
        • overall_wall number<double>
        • total integer<int64>
      • w object
        • latency object
          • avg integer<int64>
          • count integer<int64>
          • max integer<int64>
          • p50 integer<int64>
          • p95 integer<int64>
        • overall number<double>
        • overall_wall number<double>
        • total integer<int64>
    • latency array[object]
      • at integer<int64>
      • avg integer<int64>
      • count integer<int64>
      • max integer<int64>
      • p50 integer<int64>
      • p95 integer<int64>
    • network array[object]
      • at integer<int64>
      • read_bps number<double>
      • write_bps number<double>
    • num_cpu integer
    • objects object
      • cached integer
        Max: 1.8446744073709552e+19
      • cached_size integer
        Max: 1.8446744073709552e+19
      • error integer
        Max: 1.8446744073709552e+19
      • ok integer
        Max: 1.8446744073709552e+19
      • size integer
        Max: 1.8446744073709552e+19
      • total integer
        Max: 1.8446744073709552e+19
    • paths object
      • cached integer
        Max: 1.8446744073709552e+19
      • cached_size integer
        Max: 1.8446744073709552e+19
      • error integer
        Max: 1.8446744073709552e+19
      • ok integer
        Max: 1.8446744073709552e+19
      • size integer
        Max: 1.8446744073709552e+19
      • total integer
        Max: 1.8446744073709552e+19
    • phase string
    • processed object
      • bytes integer
        Max: 1.8446744073709552e+19
      • items integer
        Max: 1.8446744073709552e+19
    • recent_paths array[object]
      • path string
      • status string
    • resources array[object]
      • at integer<int64>
      • cpu_percent number<double>
      • memory_bytes integer
        Max: 1.8446744073709552e+19
    • result object
      • duration number<double>
      • errors integer
        Max: 1.8446744073709552e+19
      • size integer
        Max: 1.8446744073709552e+19
    • snapshot_id string
    • summary object
      • directories integer
        Max: 1.8446744073709552e+19
      • exists boolean
      • files integer
        Max: 1.8446744073709552e+19
      • paths integer
        Max: 1.8446744073709552e+19
      • size integer
        Max: 1.8446744073709552e+19
      • symlinks integer
        Max: 1.8446744073709552e+19
      • xattrs integer
        Max: 1.8446744073709552e+19
    • symlinks object
      • cached integer
        Max: 1.8446744073709552e+19
      • cached_size integer
        Max: 1.8446744073709552e+19
      • error integer
        Max: 1.8446744073709552e+19
      • ok integer
        Max: 1.8446744073709552e+19
      • size integer
        Max: 1.8446744073709552e+19
      • total integer
        Max: 1.8446744073709552e+19
    • version string
    • xattrs object
      • cached integer
        Max: 1.8446744073709552e+19
      • cached_size integer
        Max: 1.8446744073709552e+19
      • error integer
        Max: 1.8446744073709552e+19
      • ok integer
        Max: 1.8446744073709552e+19
      • size integer
        Max: 1.8446744073709552e+19
      • total integer
        Max: 1.8446744073709552e+19

Response 200 OK application/json

  • at_id string<uuid>
  • cron_id string<uuid>
  • id string<uuid>
  • identity_id string<uuid>
  • schedule_at string<date-time>
  • schedule_id string<uuid>
  • scheduler_id string<uuid>
  • started_at string<date-time>
  • status string
  • stopped_at string<date-time>
  • 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/agent/jobs/{job_id}/update' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "log": "string",
  "state": {
    "chunks": {
      "cached": 0,
      "cached_size": 0,
      "error": 0,
      "ok": 0,
      "size": 0,
      "total": 0
    },
    "dirs": {
      "cached": 0,
      "cached_size": 0,
      "error": 0,
      "ok": 0,
      "size": 0,
      "total": 0
    },
    "files": {
      "cached": 0,
      "cached_size": 0,
      "error": 0,
      "ok": 0,
      "size": 0,
      "total": 0
    },
    "io": {
      "key": {
        "r": {
          "latency": {
            "avg": 0,
            "count": 0,
            "max": 0,
            "p50": 0,
            "p95": 0
          },
          "overall": 0,
          "overall_wall": 0,
          "total": 0
        },
        "w": {
          "latency": {
            "avg": 0,
            "count": 0,
            "max": 0,
            "p50": 0,
            "p95": 0
          },
          "overall": 0,
          "overall_wall": 0,
          "total": 0
        }
      }
    },
    "latency": [
      {
        "at": 0,
        "avg": 0,
        "count": 0,
        "max": 0,
        "p50": 0,
        "p95": 0
      }
    ],
    "network": [
      {
        "at": 0,
        "read_bps": 0,
        "write_bps": 0
      }
    ],
    "num_cpu": 0,
    "objects": {
      "cached": 0,
      "cached_size": 0,
      "error": 0,
      "ok": 0,
      "size": 0,
      "total": 0
    },
    "paths": {
      "cached": 0,
      "cached_size": 0,
      "error": 0,
      "ok": 0,
      "size": 0,
      "total": 0
    },
    "phase": "string",
    "processed": {
      "bytes": 0,
      "items": 0
    },
    "recent_paths": [
      {
        "path": "string",
        "status": "string"
      }
    ],
    "resources": [
      {
        "at": 0,
        "cpu_percent": 0,
        "memory_bytes": 0
      }
    ],
    "result": {
      "duration": 0,
      "errors": 0,
      "size": 0
    },
    "snapshot_id": "string",
    "summary": {
      "directories": 0,
      "exists": true,
      "files": 0,
      "paths": 0,
      "size": 0,
      "symlinks": 0,
      "xattrs": 0
    },
    "symlinks": {
      "cached": 0,
      "cached_size": 0,
      "error": 0,
      "ok": 0,
      "size": 0,
      "total": 0
    },
    "version": "string",
    "xattrs": {
      "cached": 0,
      "cached_size": 0,
      "error": 0,
      "ok": 0,
      "size": 0,
      "total": 0
    }
  }
}'

Response 200

{
  "at_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "cron_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "identity_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "schedule_at": "2026-01-01T00:00:00Z",
  "schedule_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "scheduler_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "started_at": "2026-01-01T00:00:00Z",
  "status": "string",
  "stopped_at": "2026-01-01T00:00:00Z",
  "task_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
}

List the schedulers

GET /api/v1/agent/schedulers
Agent token

Query parameters

  • offset integer
    Number of items to skip.
    Default: 0
  • limit integer
    Maximum number of items to return.
    Default: 100 Min: 1 Max: 100

Response 200 OK application/json

  • items array[object]
    • actor string
    • enabled boolean
    • id string<uuid>
    • revision integer
  • total integer

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/agent/schedulers' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "items": [
    {
      "actor": "string",
      "enabled": true,
      "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
      "revision": 0
    }
  ],
  "total": 0
}

Get a scheduler

GET /api/v1/agent/schedulers/{scheduler_id}
Agent token

Path parameters

  • scheduler_id string required

Query parameters

  • revision integer required
    Scheduler revision to return the tasks of.

Response 200 OK application/json

  • concurrency integer
  • cron_id string<uuid>
  • enabled boolean
  • id string<uuid>
  • miss_strategy string
  • priority integer
  • rules array[object]
    • enabled boolean
    • id string<uuid>
    • jitter integer<int64>
    • journalized boolean
    • last_run string<date-time>
    • period integer<int64>
    • start string<date-time>
  • scheduler_id string<uuid>
  • tracking_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 'https://pcp.example.com/api/v1/agent/schedulers/{scheduler_id}' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

[
  {
    "concurrency": 0,
    "cron_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "enabled": true,
    "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "miss_strategy": "string",
    "priority": 0,
    "rules": [
      {
        "enabled": true,
        "id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
        "jitter": 0,
        "journalized": true,
        "last_run": "2026-01-01T00:00:00Z",
        "period": 0,
        "start": "2026-01-01T00:00:00Z"
      }
    ],
    "scheduler_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
    "tracking_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90"
  }
]

Record a snapshot of a source

POST /api/v1/agent/snapshots/source/{source_id}/snapshot
Agent token

Path parameters

  • source_id string required

Request body application/json required

  • category string nullable
  • creation_time string<date-time> required
  • data_classes array[string] nullable
  • dataset string nullable
  • environment string nullable
  • items integer nullable
  • name string nullable
  • origin string nullable
  • root string nullable
  • size integer nullable
  • snapshot_id string required
  • tags array[string] nullable

Response 200 OK

No response body.

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/agent/snapshots/source/{source_id}/snapshot' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "category": "string",
  "creation_time": "2026-01-01T00:00:00Z",
  "data_classes": [
    "string"
  ],
  "dataset": "string",
  "environment": "string",
  "items": 0,
  "name": "string",
  "origin": "string",
  "root": "string",
  "size": 0,
  "snapshot_id": "string",
  "tags": [
    "string"
  ]
}'

Record a prune of a store

POST /api/v1/agent/snapshots/store/{store_id}/prune
Agent token

Path parameters

  • store_id string required

Request body application/json required

  • snapshot_ids array[string] required

Response 200 OK

No response body.

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/agent/snapshots/store/{store_id}/prune' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "snapshot_ids": [
    "string"
  ]
}'

Record snapshots removed from a store

POST /api/v1/agent/snapshots/store/{store_id}/rm
Agent token

Path parameters

  • store_id string required

Request body application/json required

  • snapshot_ids array[string] required

Response 200 OK

No response body.

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/agent/snapshots/store/{store_id}/rm' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "snapshot_ids": [
    "string"
  ]
}'

Record the snapshots of a store

POST /api/v1/agent/snapshots/store/{store_id}/snapshots
Agent token

Path parameters

  • store_id string required

Request body application/json required

  • snapshots array[object] required
    • category string nullable
    • creation_time string<date-time> required
    • data_classes array[string] nullable
    • dataset string nullable
    • environment string nullable
    • items integer nullable
    • name string nullable
    • origin string nullable
    • root string nullable
    • size integer nullable
    • snapshot_id string required
    • tags array[string] nullable

Response 200 OK

No response body.

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/agent/snapshots/store/{store_id}/snapshots' \
  -H 'Plakman-Agent-Token: <agent-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "snapshots": [
    {
      "category": "string",
      "creation_time": "2026-01-01T00:00:00Z",
      "data_classes": [
        "string"
      ],
      "dataset": "string",
      "environment": "string",
      "items": 0,
      "name": "string",
      "origin": "string",
      "root": "string",
      "size": 0,
      "snapshot_id": "string",
      "tags": [
        "string"
      ]
    }
  ]
}'

Get a task

GET /api/v1/agent/tasks/{task_id}
Agent token

Path parameters

  • task_id string required

Response 200 OK application/json

  • config map[string]
  • edge_id string<uuid>
  • edge_tags array[string]
  • organization_id string<uuid>
  • origin_id string<uuid>
  • orphan boolean
  • target_id string<uuid>
  • type 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/agent/tasks/{task_id}' \
  -H 'Plakman-Agent-Token: <agent-token>'

Response 200

{
  "config": {
    "key": "string"
  },
  "edge_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "edge_tags": [
    "string"
  ],
  "organization_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "origin_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "orphan": true,
  "target_id": "3f1e4a2c-9b7d-4e0f-8a11-2c5d6e7f8a90",
  "type": "string"
}

Product

Integrations

Resources

Company

Newsletter