Matrix logo

Chronos API

The centralized agent scheduler — agent DID authentication plus create, list, get, and cancel alarms that wake an agent at a scheduled time.

Chronos is the centralized agent scheduler / wake-up system. Agents authenticate with their DID, then create alarms that fire a wake at a scheduled time.

Routes

MethodPathPurpose
GET/healthzLiveness.
GET/Service root / info.
POST/v1/agent/auth/challengeRequest a nonce for the agent DID.
POST/v1/agent/auth/verifyVerify the signed nonce → session token.
POST/v1/alarmsCreate an alarm.
GET/v1/alarmsList the agent's alarms.
GET/v1/alarms/{id}Get one alarm.
DELETE/v1/alarms/{id}Cancel an alarm.

Authentication

See the shared agent DID handshake: POST /v1/agent/auth/challenge → sign the nonce → POST /v1/agent/auth/verify.

Create an alarm

fire_atstring (ISO 8601)required

When the alarm should fire.

payloadobject

Opaque data delivered to the agent on wake.

curl -X POST https://chronos.example/v1/alarms \
  -H "Authorization: Bearer $CHRONOS_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"fire_at": "2026-06-20T09:00:00Z", "payload": {"task": "daily-digest"}}'
idstringrequired

The alarm identifier (used for get/cancel).

statusstring

scheduled, fired, or cancelled.