Agent metrics ingest endpoint (agent-token authenticated)

POST

/api/metrics/ingest

const url = 'https://example.com/api/metrics/ingest';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"cpuPercent":1,"memoryUsedMb":1,"memoryTotalMb":1,"swapUsedMb":1,"swapTotalMb":1,"diskUsedGb":1,"diskTotalGb":1,"loadAvg1":1,"loadAvg5":1,"loadAvg15":1,"uptime":1,"openFds":1,"maxFds":1,"tcpEstablished":1,"tcpListen":1,"tcpTimeWait":1,"tcpCloseWait":1,"tcpTotal":1,"serverHealthy":true,"agentVersion":"example","services":[{"containerName":"example","cpuPercent":1,"memoryUsedMb":1,"memoryLimitMb":1,"networkRxMb":1,"networkTxMb":1,"blockReadMb":1,"blockWriteMb":1,"restartCount":1,"state":"example","health":"example"}],"serviceHealthChecks":[{"containerName":"example","healthCheckUrl":"example","success":true,"statusCode":1,"durationMs":1,"checkedAt":"2026-04-15T12:00:00Z","error":"example"}],"tcpCheckResults":[{"containerName":"example","host":"example","port":1,"name":"example","success":true,"durationMs":1,"error":"example"}],"certCheckResults":[{"containerName":"example","host":"example","port":1,"name":"example","success":true,"durationMs":1,"expiresAt":"example","daysUntilExpiry":1,"issuer":"example","subject":"example","error":"example"}],"containers":[{"id":"example","name":"example","image":"example","imageId":"example","state":"example","status":"example","created":1,"ports":[{"privatePort":1,"publicPort":1,"type":"example","ip":"example"}],"labels":{"additionalProperty":"example"},"mounts":[{"source":"example","destination":"example","mode":"example","type":"example"}],"networkMode":"example"}],"topProcesses":{"byCpu":[{"pid":1,"name":"example","state":"example","cpuPercent":1,"memoryMb":1,"threads":1}],"byMemory":[{"pid":1,"name":"example","state":"example","cpuPercent":1,"memoryMb":1,"threads":1}],"stats":{"total":1,"running":1,"sleeping":1,"stopped":1,"zombie":1}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/api/metrics/ingest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "cpuPercent": 1, "memoryUsedMb": 1, "memoryTotalMb": 1, "swapUsedMb": 1, "swapTotalMb": 1, "diskUsedGb": 1, "diskTotalGb": 1, "loadAvg1": 1, "loadAvg5": 1, "loadAvg15": 1, "uptime": 1, "openFds": 1, "maxFds": 1, "tcpEstablished": 1, "tcpListen": 1, "tcpTimeWait": 1, "tcpCloseWait": 1, "tcpTotal": 1, "serverHealthy": true, "agentVersion": "example", "services": [ { "containerName": "example", "cpuPercent": 1, "memoryUsedMb": 1, "memoryLimitMb": 1, "networkRxMb": 1, "networkTxMb": 1, "blockReadMb": 1, "blockWriteMb": 1, "restartCount": 1, "state": "example", "health": "example" } ], "serviceHealthChecks": [ { "containerName": "example", "healthCheckUrl": "example", "success": true, "statusCode": 1, "durationMs": 1, "checkedAt": "2026-04-15T12:00:00Z", "error": "example" } ], "tcpCheckResults": [ { "containerName": "example", "host": "example", "port": 1, "name": "example", "success": true, "durationMs": 1, "error": "example" } ], "certCheckResults": [ { "containerName": "example", "host": "example", "port": 1, "name": "example", "success": true, "durationMs": 1, "expiresAt": "example", "daysUntilExpiry": 1, "issuer": "example", "subject": "example", "error": "example" } ], "containers": [ { "id": "example", "name": "example", "image": "example", "imageId": "example", "state": "example", "status": "example", "created": 1, "ports": [ { "privatePort": 1, "publicPort": 1, "type": "example", "ip": "example" } ], "labels": { "additionalProperty": "example" }, "mounts": [ { "source": "example", "destination": "example", "mode": "example", "type": "example" } ], "networkMode": "example" } ], "topProcesses": { "byCpu": [ { "pid": 1, "name": "example", "state": "example", "cpuPercent": 1, "memoryMb": 1, "threads": 1 } ], "byMemory": [ { "pid": 1, "name": "example", "state": "example", "cpuPercent": 1, "memoryMb": 1, "threads": 1 } ], "stats": { "total": 1, "running": 1, "sleeping": 1, "stopped": 1, "zombie": 1 } } }'

Authorizations

bearerAuth

Request Body^required

application/json

object

cpuPercent

number

memoryUsedMb

number

memoryTotalMb

number

swapUsedMb

number

swapTotalMb

number

diskUsedGb

number

diskTotalGb

number

loadAvg1

number

loadAvg5

number

loadAvg15

number

uptime

number

openFds

number

maxFds

number

tcpEstablished

number

tcpListen

number

tcpTimeWait

number

tcpCloseWait

number

tcpTotal

number

serverHealthy

boolean

agentVersion

string

services

Array<object>

object

containerName

required

string

cpuPercent

number

memoryUsedMb

number

memoryLimitMb

number

networkRxMb

number

networkTxMb

number

blockReadMb

number

blockWriteMb

number

restartCount

number

state

string

health

string

serviceHealthChecks

Array<object>

object

containerName

required

string

healthCheckUrl

required

string

success

required

boolean

statusCode

number

durationMs

number

checkedAt

string format: date-time

/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$/

error

string

tcpCheckResults

Array<object>

object

containerName

required

string

host

required

string

port

required

number

name

string

success

required

boolean

durationMs

required

number

error

string

certCheckResults

Array<object>

object

containerName

required

string

host

required

string

port

required

number

name

string

success

required

boolean

durationMs

required

number

expiresAt

string

daysUntilExpiry

number

issuer

string

subject

string

error

string

containers

Array<object>

object

required

string

name

required

string

image

required

string

imageId

required

string

state

required

string

status

required

string

created

required

number

ports

Array<object>

object

privatePort

required

number

publicPort

number

type

required

string

labels

object

key

additional properties

string

mounts

Array<object>

object

source

required

string

destination

required

string

mode

required

string

type

required

string

networkMode

string

topProcesses

object

byCpu

required

Array<object>

object

pid

required

number

name

required

string

state

required

string

cpuPercent

required

number

memoryMb

required

number

threads

required

number

byMemory

required

Array<object>

object

pid

required

number

name

required

string

state

required

string

cpuPercent

required

number

memoryMb

required

number

threads

required

number

stats

required

object

total

required

number

running

required

number

sleeping

required

number

stopped

required

number

zombie

required

number

Example^generated

{
  "cpuPercent": 1,
  "memoryUsedMb": 1,
  "memoryTotalMb": 1,
  "swapUsedMb": 1,
  "swapTotalMb": 1,
  "diskUsedGb": 1,
  "diskTotalGb": 1,
  "loadAvg1": 1,
  "loadAvg5": 1,
  "loadAvg15": 1,
  "uptime": 1,
  "openFds": 1,
  "maxFds": 1,
  "tcpEstablished": 1,
  "tcpListen": 1,
  "tcpTimeWait": 1,
  "tcpCloseWait": 1,
  "tcpTotal": 1,
  "serverHealthy": true,
  "agentVersion": "example",
  "services": [
    {
      "containerName": "example",
      "cpuPercent": 1,
      "memoryUsedMb": 1,
      "memoryLimitMb": 1,
      "networkRxMb": 1,
      "networkTxMb": 1,
      "blockReadMb": 1,
      "blockWriteMb": 1,
      "restartCount": 1,
      "state": "example",
      "health": "example"
    }
  ],
  "serviceHealthChecks": [
    {
      "containerName": "example",
      "healthCheckUrl": "example",
      "success": true,
      "statusCode": 1,
      "durationMs": 1,
      "checkedAt": "2026-04-15T12:00:00Z",
      "error": "example"
    }
  ],
  "tcpCheckResults": [
    {
      "containerName": "example",
      "host": "example",
      "port": 1,
      "name": "example",
      "success": true,
      "durationMs": 1,
      "error": "example"
    }
  ],
  "certCheckResults": [
    {
      "containerName": "example",
      "host": "example",
      "port": 1,
      "name": "example",
      "success": true,
      "durationMs": 1,
      "expiresAt": "example",
      "daysUntilExpiry": 1,
      "issuer": "example",
      "subject": "example",
      "error": "example"
    }
  ],
  "containers": [
    {
      "id": "example",
      "name": "example",
      "image": "example",
      "imageId": "example",
      "state": "example",
      "status": "example",
      "created": 1,
      "ports": [
        {
          "privatePort": 1,
          "publicPort": 1,
          "type": "example",
          "ip": "example"
        }
      ],
      "labels": {
        "additionalProperty": "example"
      },
      "mounts": [
        {
          "source": "example",
          "destination": "example",
          "mode": "example",
          "type": "example"
        }
      ],
      "networkMode": "example"
    }
  ],
  "topProcesses": {
    "byCpu": [
      {
        "pid": 1,
        "name": "example",
        "state": "example",
        "cpuPercent": 1,
        "memoryMb": 1,
        "threads": 1
      }
    ],
    "byMemory": [
      {
        "pid": 1,
        "name": "example",
        "state": "example",
        "cpuPercent": 1,
        "memoryMb": 1,
        "threads": 1
      }
    ],
    "stats": {
      "total": 1,
      "running": 1,
      "sleeping": 1,
      "stopped": 1,
      "zombie": 1
    }
  }
}

Responses

400

Bad request — malformed input or failed validation.

application/json

object

code

Stable, machine-readable error code. Always present on the wire.

string

Allowed values: VALIDATION_ERROR READONLY_FIELD UNAUTHORIZED FORBIDDEN_SCOPE FORBIDDEN_ROLE NOT_FOUND CONFLICT IDEMPOTENCY_KEY_REUSED RATE_LIMITED SERVICE_UNAVAILABLE INTERNAL

message

Human-readable error message. Always present on the wire.

string

field

Field name when the error is tied to a specific input (e.g. validation).

string

hint

Optional, human-friendly hint for resolving the error.

string

requestId

Server-assigned request ID; quote this when reporting issues.

string

key

additional properties

any

Example

{
  "code": "READONLY_FIELD",
  "message": "Field \"exposedPorts\" is read-only and cannot be set via PATCH.",
  "field": "exposedPorts",
  "hint": "Exposed ports are discovered from the running container. Change the ports mapping in the compose file at composePath and redeploy.",
  "requestId": "req_01H0…"
}

401

Unauthorized — missing or invalid bearer token.

application/json

object

code

Stable, machine-readable error code. Always present on the wire.

string

Allowed values: VALIDATION_ERROR READONLY_FIELD UNAUTHORIZED FORBIDDEN_SCOPE FORBIDDEN_ROLE NOT_FOUND CONFLICT IDEMPOTENCY_KEY_REUSED RATE_LIMITED SERVICE_UNAVAILABLE INTERNAL

message

Human-readable error message. Always present on the wire.

string

field

Field name when the error is tied to a specific input (e.g. validation).

string

hint

Optional, human-friendly hint for resolving the error.

string

requestId

Server-assigned request ID; quote this when reporting issues.

string

key

additional properties

any

Example

{
  "code": "READONLY_FIELD",
  "message": "Field \"exposedPorts\" is read-only and cannot be set via PATCH.",
  "field": "exposedPorts",
  "hint": "Exposed ports are discovered from the running container. Change the ports mapping in the compose file at composePath and redeploy.",
  "requestId": "req_01H0…"
}

Agent metrics ingest endpoint (agent-token authenticated)

Authorizations

Request Bodyrequired

Examplegenerated

Responses

400

Example

401

Example

Request Body^required

Example^generated