ts.rtr.update

Update a ritual run (status, results, effects, error).

Update a ritual run (status, results, effects, error).

Requires authentication

Description

Updates a ritual run to record its outcome. This is how you complete a run.

Status transitions:

  • running -> succeeded (work completed successfully)
  • running -> failed (work encountered an error)
  • running -> skipped (run was skipped, e.g., nothing to do)

When transitioning to a terminal status, finished_at is set automatically.

The effects field records what the run produced (tasks created, updated, etc.). The error field captures failure details when status=failed.

Parameters

NameTypeRequiredDefaultDescription
idstringYesRitual run ID
statusstringNew status: succeeded, failed, skipped
result_summarystringFree-form summary of what happened
effectsobjectEffects of the run: {“tasks_created”:[], “tasks_updated”:[], …}
errorobjectError details if failed: {“code”:"…", “message”:"…"}
metadataobjectMetadata to set (replaces existing)

Response

Returns the run ID and list of fields that were updated.

{
  "id": "rtr_x1y2z3a4b5c6...",
  "updated_at": "2026-02-09T10:05:00Z",
  "updated_fields": [
    "status",
    "result_summary",
    "effects"
  ]
}

Errors

CodeDescription
not_authenticatedNo active login for this session
not_foundRitual run with this ID does not exist
invalid_inputNo fields to update or invalid status transition

Examples

Complete a successful run

Mark a ritual run as succeeded with results.

Request:

{
  "effects": {
    "tasks_created": [
      "tsk_new1...",
      "tsk_new2..."
    ],
    "tasks_updated": [
      "tsk_existing..."
    ]
  },
  "id": "rtr_x1y2z3a4b5c6...",
  "result_summary": "Created 2 tasks, updated 1 task status.",
  "status": "succeeded"
}

Response:

{
  "id": "rtr_x1y2z3a4b5c6...",
  "updated_at": "2026-02-09T10:05:00Z",
  "updated_fields": [
    "status",
    "result_summary",
    "effects"
  ]
}

Record a failed run

Mark a ritual run as failed with error details.

Request:

{
  "error": {
    "code": "timeout",
    "message": "Ritual execution timed out after 5 minutes."
  },
  "id": "rtr_x1y2z3a4b5c6...",
  "status": "failed"
}

Response:

{
  "id": "rtr_x1y2z3a4b5c6...",
  "updated_at": "2026-02-09T10:05:00Z",
  "updated_fields": [
    "status",
    "error"
  ]
}