Route a control-plane action

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

action*string

Known action id advertised by GET /capabilities.

Length1 <= length

origin?string

Optional caller identifier echoed for correlation. Grants no authority.

Length1 <= length

args?

Action-specific arguments. May be empty.

intentId?string

Optional caller-supplied correlation id echoed in the event. On coven.automations.create, .update, and .delete it is also an idempotency key: a repeat returns the first result, and a different request with the same value is rejected.

Length1 <= length

id?string

Definition, run, occurrence, or receipt id. Required by get, delete, runs, run, health, unquarantine, the definition get, health, activate, pause, disable, and tombstone commands, run.get.v1, occurrence.get.v1, and receipt.get.v1.

Length1 <= length

limit?integer

Optional page size. coven.automations.runs defaults to 20; history and occurrence reads accept 1 to 100 (default 20); events.read.v1 accepts 1 to 1000 (default 100).

definition?

Required routine definition for create, update, and the versioned create and revise commands.

adoptionKey?string

Idempotency key required by versioned automation mutations. The same request with the same key returns the first outcome; a different request with a used key is rejected.

Match^[A-Za-z0-9][A-Za-z0-9._:-]*$

Length8 <= length <= 200

expectedRevision?integer

Required by revise, activate, pause, disable, and tombstone; forbidden on create. A stale value returns REVISION_CONFLICT.

Range1 <= value

reason?string

Optional reason for activate, pause, and disable (at most 500 bytes). Required by run.cancel.v1.

automationId?string

Required by run.history.v1 and occurrence.history.v1; optional filter for occurrence.list.v1.

Length1 <= length

cursor?string

Opaque cursor.next value from a previous history page.

[key: string]?any

Response Body

`application/json`

curl -X POST "https://example.com/actions" \  -H "Content-Type: application/json" \  -d '{    "action": "coven.capabilities.refresh",    "origin": "coven-client",    "intentId": "refresh-1"  }'

{
  "ok": true,
  "accepted": true,
  "action": "coven.automations.health",
  "status": "completed",
  "event": {
    "kind": "automations.changed",
    "action": "coven.automations.health",
    "origin": "local-maintainer-tool",
    "intentId": "inspect-daily-notes-1",
    "payload": {
      "health": {
        "automationId": "daily-notes"
      }
    }
  }
}

{
  "ok": false,
  "accepted": false,
  "action": "coven.automations.definition.activate.v1",
  "status": "rejected",
  "reason": "Automation mutations require owner-local IPC.",
  "error": {
    "code": "AUTHORITY_REQUIRED",
    "httpStatus": 403,
    "message": "Automation mutations require owner-local IPC.",
    "retryable": false
  }
}

{
  "ok": false,
  "accepted": false,
  "action": "coven.automations.definition.activate.v1",
  "status": "rejected",
  "reason": "Automation mutations require owner-local IPC.",
  "error": {
    "code": "AUTHORITY_REQUIRED",
    "httpStatus": 403,
    "message": "Automation mutations require owner-local IPC.",
    "retryable": false
  }
}

{
  "ok": false,
  "accepted": false,
  "action": "coven.automations.definition.activate.v1",
  "status": "rejected",
  "reason": "Automation mutations require owner-local IPC.",
  "error": {
    "code": "AUTHORITY_REQUIRED",
    "httpStatus": 403,
    "message": "Automation mutations require owner-local IPC.",
    "retryable": false
  }
}

{
  "ok": false,
  "accepted": false,
  "action": "coven.automations.definition.activate.v1",
  "status": "rejected",
  "reason": "Automation mutations require owner-local IPC.",
  "error": {
    "code": "AUTHORITY_REQUIRED",
    "httpStatus": 403,
    "message": "Automation mutations require owner-local IPC.",
    "retryable": false
  }
}

{
  "ok": false,
  "accepted": false,
  "action": "coven.automations.definition.activate.v1",
  "status": "rejected",
  "reason": "Automation mutations require owner-local IPC.",
  "error": {
    "code": "AUTHORITY_REQUIRED",
    "httpStatus": 403,
    "message": "Automation mutations require owner-local IPC.",
    "retryable": false
  }
}

{
  "ok": false,
  "accepted": false,
  "action": "coven.automations.definition.activate.v1",
  "status": "rejected",
  "reason": "Automation mutations require owner-local IPC.",
  "error": {
    "code": "AUTHORITY_REQUIRED",
    "httpStatus": 403,
    "message": "Automation mutations require owner-local IPC.",
    "retryable": false
  }
}

{
  "ok": false,
  "accepted": false,
  "action": "coven.automations.definition.activate.v1",
  "status": "rejected",
  "reason": "Automation mutations require owner-local IPC.",
  "error": {
    "code": "AUTHORITY_REQUIRED",
    "httpStatus": 403,
    "message": "Automation mutations require owner-local IPC.",
    "retryable": false
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Unexpected internal daemon error.",
    "details": {}
  }
}

Request Body

Response Body

200application/json

400application/json

403application/json

404application/json

409application/json

410application/json

422application/json

500application/json

defaultapplication/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`