FruxonDocs
Agent NetworkTriggers

Starts one work item by hand.

For an automation whose work shape declares an `onDemand` block: admits one item at its first stage, from `data` checked against the block's declared inputs. The item key is `itemKey`, or composed from `data` at the block's `keyPaths`; when both are given they must agree. A credential-named key anywhere in `data` is refused — store the value in Secrets. <b>Idempotent on the key.</b> 201 with `created: true` for a new item; 200 with `created: false` and the item that already holds the key, unchanged, whatever its status and whatever this call's data says — never a 409. Corrections go through `:setData`; a finished item is not restarted. A repeatable operation needs its occurrence (an invoice number, a cycle) among the key paths. A paused automation still admits; `paused: true` says nothing will work the item until it is resumed. `stageId` is refused: an item starts at the first stage. Needs `triggers:fire`.

POST
/v1/tenants/{tenant}/triggers/{trigger}/ledger/items:admit

Authorization

Bearer
AuthorizationBearer <token>

JWT Authorization header using the Bearer scheme. Enter 'Bearer' [space] and then your token.

In: header

Path Parameters

trigger*string

The trigger identifier.

Formatuuid
tenant*string

The tenant identifier

Request Body

The data, and optionally the key, label and reason.

itemKey?string|null

The item key. Optional when the automation's onDemand.keyPaths composes one from AdmitLedgerItemRequest.Data, and then it must equal the composed key: one occurrence of the work has one key.

Lengthlength <= 150
data*unknown

The item's data: an object, checked against the automation's declared inputs.

label?string|null

What a person recognises the item by. Optional; else composed from the label paths.

Lengthlength <= 150
reason?string|null

Why it was started. Optional; recorded on the item's first transition.

Lengthlength <= 4000
stageId?string|null

Not accepted. An item starts at the first stage; this is declared only so a caller that names a stage is told so rather than having the field silently dropped.

[key: string]?never

Response Body

curl -X POST "https://api.fruxon.com/v1/tenants/string/triggers/497f6eca-6276-4993-bfeb-53cbbbba6f08/ledger/items:admit" \  -H "Content-Type: application/json" \  -d '{    "data": null  }'
{
  "created": false,
  "paused": false,
  "item": {
    "id": "00000000-0000-0000-0000-000000000000",
    "ledgerId": "00000000-0000-0000-0000-000000000000",
    "itemKey": "string",
    "label": "string",
    "stageId": "string",
    "status": "READY",
    "stageAttempts": 0,
    "nextAttemptAt": 0,
    "lastError": "string",
    "admittedAt": 0,
    "terminalAt": 0,
    "lastExecutionRecordId": "00000000-0000-0000-0000-000000000000",
    "batchRunId": "00000000-0000-0000-0000-000000000000",
    "batchId": "00000000-0000-0000-0000-000000000000",
    "lastBatchId": "00000000-0000-0000-0000-000000000000",
    "data": null,
    "admittedVia": "API",
    "admittedBy": "string",
    "admittedByExecutionRecordId": "00000000-0000-0000-0000-000000000000",
    "wakeAt": 0,
    "waitingFor": "PERSON",
    "cost": 0,
    "runs": 0
  }
}
{
  "created": false,
  "paused": false,
  "item": {
    "id": "00000000-0000-0000-0000-000000000000",
    "ledgerId": "00000000-0000-0000-0000-000000000000",
    "itemKey": "string",
    "label": "string",
    "stageId": "string",
    "status": "READY",
    "stageAttempts": 0,
    "nextAttemptAt": 0,
    "lastError": "string",
    "admittedAt": 0,
    "terminalAt": 0,
    "lastExecutionRecordId": "00000000-0000-0000-0000-000000000000",
    "batchRunId": "00000000-0000-0000-0000-000000000000",
    "batchId": "00000000-0000-0000-0000-000000000000",
    "lastBatchId": "00000000-0000-0000-0000-000000000000",
    "data": null,
    "admittedVia": "API",
    "admittedBy": "string",
    "admittedByExecutionRecordId": "00000000-0000-0000-0000-000000000000",
    "wakeAt": 0,
    "waitingFor": "PERSON",
    "cost": 0,
    "runs": 0
  }
}
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}
Empty
Empty
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}

Lists the automation's work items.

The Work view's item grid. Filter by stage and status; the UI defaults to DEAD + FAILED first, because the dead-letter queue is the reason this view exists. `ignoreReason` narrows to the items one exclusion reason set aside, matched whole and case-sensitively, and is the filter that makes `totalCount` the number `items:redrive` will confirm for the same selection. Without it the client could see "1,204 IGNORED" and the 29 rows its current page happens to hold, and nothing in between.

One item's durable side effects, and how sure the platform is about each.

External effects recorded for this item. UNKNOWN means an earlier attempt has an unresolved result: the platform refuses to repeat it, including after re-drive, and the item cannot advance. canSettle identifies effects an operator can settle after verifying the external result.