CovenDocs

Route a control-plane action

1 min read

POST
/actions

Request Body

application/json
  1. body
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

Action was accepted and completed.

application/json
  1. response
ok*boolean
accepted*boolean

Whether the action was accepted. A failed operation returns false.

action*string

Echo of the action id that was routed.

status*string

Lifecycle status of the action. Only completed is returned for immediately-completed safe actions in coven.daemon.v1.

Value in"completed""rejected"
event?|null
reason?string

Why the action was rejected, or a replay note.

result?

Result of versioned automation commands, event pages, receipt reads, and coven.automations.command.v1.

error?

Typed Coven Automations error returned by versioned automation actions and the owner-local transport check.

curl -X POST 'http://localhost:3000/api/v1/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"      }    }  }}
Was this page helpful?No

Last updated on