Event catalog
The event stream sends 14 entities. Each event names one entity, the id of what changed and an action; the envelope carries nothing else. Treat an event as a signal to refetch that item, and ignore any entity or action your client does not know: new ones may be added.
You only receive an event you are allowed to see. The Sent to column says who that is.
| Section | entity | Sent to |
|---|---|---|
| Tasks | task | Members who can see that item |
| Features | feature | Members who can see that item |
| Nodes | node | Members who can see that item |
| Node orders | node_order | Your organization's owners and admins |
| Live Cast | live_cast | Your organization's owners and admins |
| Agent accounts | account | Members who can see that item |
| Commands | command | Members who can see that item |
| Worktrees | worktree | Every member of your organization |
| Runners | runner | Every member of your organization |
| Agent sessions | session | Every member of your organization |
| Jaah AI balance | token_wallet | Every member of your organization |
| Schedules | cron | Your organization's owners and admins |
| Node groups | node_group | Your organization's owners and admins |
| Pipeline | pipeline | Members who can see that item |
Tasks
A task or epic changed.
entity:task- Sent to: Members who can see that item.
id: The task's id — the number in its console address (/tasks/{id}).deletedis not sent to you. The task is gone before access is checked. Refetch the list to notice a removal.
{"entity": "task", "id": 4916, "action": "created"}
| Action | When it fires |
|---|---|
created | A task or epic was created — by a person, a schedule or an agent. |
updated | A task's fields were edited (title, body, settings). |
titled | Jaah generated a title for the task. |
tagged | The task's tags changed. |
rated | Someone rated the task's result. |
outcome_judged | An Owner or Admin confirmed, dismissed or added a defect link, so the task's outcome may have changed. |
metered | A running task's usage and cost figures were updated. |
prioritized | The task's priority changed. |
dependency_added | The task was made to wait on another task. |
dependency_removed | A dependency was removed from the task. |
control_message | The control plane queued a message for the task's live runner, or the runner's node typed it in. |
stale | A task this one depends on changed, so its result may be out of date. |
agent_filing_deduped | The agent working on this task asked to file a task that already exists, so the existing one was kept. |
set_state | Someone set the task's state by hand, or a child's new state reactivated its epic. |
run | Someone started or restarted the task, or Jaah reopened it to finish its pull request. |
stop | Someone stopped the task. |
reset | Someone reset the task to run again from the start. |
complete | Someone marked the task complete. |
draft | The task moved to Draft. |
ready | The task moved to Ready — queued to start. |
active | The task moved to Active — an agent is working on it. |
awaiting_response | The task moved to Awaiting response — it asked a question someone must answer. |
paused | The task moved to Paused — its work stopped and is held for a resume. |
system_failed | The task moved to Failed — Jaah used up its attempts. |
done | The task moved to Done. |
Features
A feature changed.
entity:feature- Sent to: Members who can see that item.
id: The feature's id.deletedis not sent to you. The feature is gone before access is checked. Refetch the list to notice a removal.
{"entity": "feature", "id": "0199b3f2-4c1e-7a85-9d2b-6e0f1a7c3b48", "action": "created"}
| Action | When it fires |
|---|---|
created | A feature was created. |
updated | A feature was edited. |
Nodes
A node changed: its settings, its health, or the work it reports.
entity:node- Sent to: Members who can see that item.
id: The node's id, or0when the list of nodes as a whole changed.deletedis not sent to you. The node is gone before access is checked. Refetch the list to notice a removal.
{"entity": "node", "id": "0199a7d0-2e6b-7c14-8f3a-b51d9e04c672", "action": "upserted"}
| Action | When it fires |
|---|---|
upserted | A node was added, edited, or reported new state (health, capacity, agent accounts). |
Node orders
An Add-node order moved to its next step, finished, or failed.
entity:node_order- Sent to: Your organization's owners and admins.
id: The Add-node order's id.
{"entity": "node_order", "id": "0199b410-8a3c-7e29-a6d4-1f72c0b95e3d", "action": "upserted"}
| Action | When it fires |
|---|---|
upserted | An order was placed, moved a step, finished, or failed. Fetch the order to read its step. |
Live Cast
A project's Live Cast settings, publication or a manual override on one of its tasks changed.
entity:live_cast- Sent to: Your organization's owners and admins.
id: The project's id.
{"entity": "live_cast", "id": 42, "action": "updated"}
| Action | When it fires |
|---|---|
updated | The project's Live Cast checkbox, default or rules were saved. |
published | The project's Live Cast was published. |
unpublished | The project's Live Cast was unpublished. |
override | A manual override on one of the project's tasks or attachments was set or cleared. |
Agent accounts
An agent account changed.
entity:account- Sent to: Members who can see that item.
id: The agent account's id, or0when the list of agent accounts as a whole changed.deletedis not sent to you. The account is gone before access is checked. Refetch the list to notice a removal.
{"entity": "account", "id": "0199a812-5f07-7b6e-9c41-d3a08e6f2b17", "action": "upserted"}
| Action | When it fires |
|---|---|
upserted | An agent account was added or edited, or its setup on a node finished. |
Commands
A command was sent to a node, and the command log has a new entry.
entity:command- Sent to: Members who can see that item.
id: The command log entry's id. You receive it when you can see the node the command ran on, or when it ran on no node.
{"entity": "command", "id": 5203, "action": "dispatched"}
| Action | When it fires |
|---|---|
dispatched | The command was sent, but its node did not report back. |
done | The node ran the command. |
failed | The command failed on its node. |
rejected | The node refused to run the command. |
Worktrees
Some worktree in your organization changed.
entity:worktree- Sent to: Every member of your organization.
id: Always0: refetch your worktrees.
{"entity": "worktree", "id": 0, "action": "upserted"}
| Action | When it fires |
|---|---|
upserted | A worktree was claimed, released or changed state. |
deleted | A worktree was removed. |
Runners
An agent run started or ended on a worktree in your organization.
entity:runner- Sent to: Every member of your organization.
id: Always0: refetch your worktrees and their runners.
{"entity": "runner", "id": 0, "action": "upserted"}
| Action | When it fires |
|---|---|
upserted | A node reported that an agent run started, ended or changed. |
Agent sessions
The list of agent sessions in your organization changed.
entity:session- Sent to: Every member of your organization.
id: Always0: refetch the session list.
{"entity": "session", "id": 0, "action": "changed"}
| Action | When it fires |
|---|---|
changed | An agent session started, ended or was deleted. |
Jaah AI balance
Your organization's Jaah AI balance changed.
entity:token_wallet- Sent to: Every member of your organization.
id: Your organization's id.
{"entity": "token_wallet", "id": "01989c55-1b2d-7f40-8e6a-4c93d7a1f025", "action": "changed"}
| Action | When it fires |
|---|---|
changed | Credit was added to or spent from the balance, or its settings changed. |
Schedules
An automation schedule changed.
entity:cron- Sent to: Your organization's owners and admins.
id: The schedule's id.
{"entity": "cron", "id": "0199b0c4-73e8-7d1a-b2f5-08e64a9c1d3b", "action": "upserted"}
| Action | When it fires |
|---|---|
upserted | A schedule was created, edited or moved to another folder. |
deleted | A schedule was deleted. |
Node groups
A node group changed.
entity:node_group- Sent to: Your organization's owners and admins.
id: The node group's id.
{"entity": "node_group", "id": "0199ae31-9d4f-7a62-8b07-e5c21f3d6a90", "action": "upserted"}
| Action | When it fires |
|---|---|
upserted | A node group was created or edited, or it added or removed nodes. |
deleted | A node group was deleted. |
Pipeline
Something moved on a project's pipeline: a task, a merge, a release, a pass, an approval, an archive or a setup save.
entity:pipeline- Sent to: Members who can see that item.
id: The project's id.
{"entity": "pipeline", "id": 42, "action": "changed"}
| Action | When it fires |
|---|---|
changed | Anything a pipeline count, list or step shows changed. Fetch the project's pipeline view again. |
Webhook event types
An outgoing webhook endpoint subscribes to some of these types; each delivery's X-Jaah-Event header and body type name one. They are separate from the event stream above. An example delivery body is in What a delivery looks like.
| Type | Name | When it is sent |
|---|---|---|
ping | Ping | Sent only when you press Send test on an endpoint, to check it receives and verifies deliveries. |
task.created | Task created | A task was created in a project. |
task.started | Task started | A task started running on a node. |
task.awaiting_response | Task awaiting response | A task asked a question and is waiting for an answer. |
task.done | Task done | A task finished. |
task.failed | Task failed | A task failed and stopped running. |
task.stopped | Task stopped | Someone stopped a task. |
pr.opened | Pull request opened | A task opened a pull request. |
pr.merged | Pull request merged | A pull request a task opened was merged. Pull requests opened outside a task don't fire it. |