Skip to content
Core ConceptsCLI ReferenceAPI Reference
CompozyOS RuntimeAPI Reference

Hooks

Compozy Hooks HTTP endpoints.

Audience
Operators running durable agent work
Focus
API Reference guidance shaped for scanability, day-two clarity, and operator context.

List the resolved hook catalog

GET/api/hooks/catalog

Query Parameters

workspace?string

Workspace id or path

agent?string

Agent name

event?string

Hook event name

Value in

  • "session.pre_create"
  • "session.post_create"
  • "session.pre_resume"
  • "session.post_resume"
  • "session.pre_stop"
  • "session.post_stop"
  • "session.message_persisted"
  • "sandbox.prepare"
  • "sandbox.ready"
  • "sandbox.sync.before"
  • "sandbox.sync.after"
  • "sandbox.stop"
  • "input.pre_submit"
  • "prompt.post_assemble"
  • "event.pre_record"
  • "event.post_record"
  • "automation.job.pre_fire"
  • "automation.job.post_fire"
  • "automation.trigger.pre_fire"
  • "automation.trigger.post_fire"
  • "automation.run.completed"
  • "automation.run.failed"
  • "agent.pre_start"
  • "agent.spawned"
  • "agent.crashed"
  • "agent.stopped"
  • "agent.soul.snapshot.resolved"
  • "agent.soul.mutation.after"
  • "agent.heartbeat.policy.resolved"
  • "agent.heartbeat.wake.before"
  • "agent.heartbeat.wake.after"
  • "session.health.update.after"
  • "turn.start"
  • "turn.end"
  • "message.start"
  • "message.delta"
  • "message.end"
  • "tool.pre_call"
  • "tool.post_call"
  • "tool.post_error"
  • "permission.request"
  • "permission.resolved"
  • "permission.denied"
  • "context.pre_compact"
  • "context.post_compact"
  • "coordinator.pre_spawn"
  • "coordinator.spawned"
  • "coordinator.decision"
  • "coordinator.stopped"
  • "coordinator.failed"
  • "task.blocked"
  • "task.unblocked"
  • "task.needs_attention"
  • "task.recovered"
  • "task.status_changed"
  • "task.run.enqueued"
  • "task.run.pre_claim"
  • "task.run.post_claim"
  • "task.run.lease_extended"
  • "task.run.lease_expired"
  • "task.run.lease_recovered"
  • "task.run.released"
  • "task.run.completed"
  • "task.run.failed"
  • "loop.started"
  • "loop.generation.pre"
  • "loop.generation.post"
  • "loop.gate.pre"
  • "loop.gate.post"
  • "loop.node.terminal"
  • "loop.terminal"
  • "spawn.pre_create"
  • "spawn.created"
  • "spawn.parent_stopped"
  • "spawn.ttl_expired"
  • "spawn.reaped"
  • "network.thread.opened"
  • "network.direct_room.opened"
  • "network.message.persisted"
  • "network.work.opened"
  • "network.work.transitioned"
  • "network.work.closed"
  • "network.peer.joined"
  • "network.peer.left"
  • "network.participation.pre_resolve"
  • "network.participation.resolved"
  • "window_manager.layout.applied"
  • "window_manager.desktop.created"
  • "window_manager.desktop.deleted"
  • "window_manager.window.moved"
source?string

Hook source

Value in

  • "native"
  • "config"
  • "agent_definition"
  • "skill"
mode?string

Hook mode

Value in

  • "sync"
  • "async"

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/hooks/catalog"
{  "hooks": [    {      "event": "string",      "executor_kind": "string",      "matcher": {        "acp_event_type": "string",        "agent_name": "string",        "agent_type": "string",        "autonomy": {          "child_session_id": "string",          "coordinator_session_id": "string",          "loop_name": "string",          "loop_run_id": "string",          "node_id": "string",          "parent_session_id": "string",          "participation_channel": "string",          "release_reason": "string",          "root_session_id": "string",          "run_id": "string",          "spawn_role": "string",          "task_id": "string",          "workflow_id": "string"        },        "channel": "string",        "compaction_reason": "string",        "compaction_strategy": "string",        "decision_class": "string",        "direction": "string",        "input_class": "string",        "kind": "string",        "message_delta_type": "string",        "message_role": "string",        "participation_mode": "string",        "participation_source": "string",        "sandbox_backend": "string",        "sandbox_id": "string",        "sandbox_profile": "string",        "session_type": "string",        "surface": "string",        "sync_direction": "string",        "tool_id": "string",        "tool_name": "string",        "tool_read_only": true,        "turn_id": "string",        "work_state": "string",        "workspace_id": "string",        "workspace_root": "string"      },      "metadata": {        "property1": "string",        "property2": "string"      },      "mode": "string",      "name": "string",      "order": 0,      "priority": 0,      "required": true,      "skill_source": "string",      "source": "string",      "timeout_ms": 0    }  ]}

List supported hook taxonomy metadata

GET/api/hooks/events

Query Parameters

family?string

Hook event family

Value in

  • "session"
  • "input"
  • "prompt"
  • "event"
  • "agent"
  • "turn"
  • "message"
  • "tool"
  • "permission"
  • "context"
sync_only?boolean

Only return sync-eligible events

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/api/hooks/events"
{  "events": [    {      "event": "string",      "family": "string",      "patch_schema": "string",      "payload_schema": "string",      "sync_eligible": true    }  ]}

List hook run history for one session

GET/api/workspaces/{workspace_id}/hooks/runs

Path Parameters

workspace_id*string

Workspace id

Query Parameters

session*string

Session id

event?string

Hook event name

Value in

  • "session.pre_create"
  • "session.post_create"
  • "session.pre_resume"
  • "session.post_resume"
  • "session.pre_stop"
  • "session.post_stop"
  • "session.message_persisted"
  • "sandbox.prepare"
  • "sandbox.ready"
  • "sandbox.sync.before"
  • "sandbox.sync.after"
  • "sandbox.stop"
  • "input.pre_submit"
  • "prompt.post_assemble"
  • "event.pre_record"
  • "event.post_record"
  • "automation.job.pre_fire"
  • "automation.job.post_fire"
  • "automation.trigger.pre_fire"
  • "automation.trigger.post_fire"
  • "automation.run.completed"
  • "automation.run.failed"
  • "agent.pre_start"
  • "agent.spawned"
  • "agent.crashed"
  • "agent.stopped"
  • "agent.soul.snapshot.resolved"
  • "agent.soul.mutation.after"
  • "agent.heartbeat.policy.resolved"
  • "agent.heartbeat.wake.before"
  • "agent.heartbeat.wake.after"
  • "session.health.update.after"
  • "turn.start"
  • "turn.end"
  • "message.start"
  • "message.delta"
  • "message.end"
  • "tool.pre_call"
  • "tool.post_call"
  • "tool.post_error"
  • "permission.request"
  • "permission.resolved"
  • "permission.denied"
  • "context.pre_compact"
  • "context.post_compact"
  • "coordinator.pre_spawn"
  • "coordinator.spawned"
  • "coordinator.decision"
  • "coordinator.stopped"
  • "coordinator.failed"
  • "task.blocked"
  • "task.unblocked"
  • "task.needs_attention"
  • "task.recovered"
  • "task.status_changed"
  • "task.run.enqueued"
  • "task.run.pre_claim"
  • "task.run.post_claim"
  • "task.run.lease_extended"
  • "task.run.lease_expired"
  • "task.run.lease_recovered"
  • "task.run.released"
  • "task.run.completed"
  • "task.run.failed"
  • "loop.started"
  • "loop.generation.pre"
  • "loop.generation.post"
  • "loop.gate.pre"
  • "loop.gate.post"
  • "loop.node.terminal"
  • "loop.terminal"
  • "spawn.pre_create"
  • "spawn.created"
  • "spawn.parent_stopped"
  • "spawn.ttl_expired"
  • "spawn.reaped"
  • "network.thread.opened"
  • "network.direct_room.opened"
  • "network.message.persisted"
  • "network.work.opened"
  • "network.work.transitioned"
  • "network.work.closed"
  • "network.peer.joined"
  • "network.peer.left"
  • "network.participation.pre_resolve"
  • "network.participation.resolved"
  • "window_manager.layout.applied"
  • "window_manager.desktop.created"
  • "window_manager.desktop.deleted"
  • "window_manager.window.moved"
outcome?string

Hook execution outcome

Value in

  • "applied"
  • "denied"
  • "failed"
  • "skipped"
  • "dropped"
  • "rejected"
since?string

Only runs recorded since this timestamp

Formatdate-time
last?integer

Maximum number of records to return

Formatint32

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/workspaces/string/hooks/runs?session=string"
{  "runs": [    {      "dispatch_depth": 0,      "duration_ms": 0,      "error": "string",      "event": "string",      "hook_name": "string",      "mode": "string",      "outcome": "string",      "patch_applied": null,      "recorded_at": "2019-08-24T14:15:22Z",      "required": true,      "source": "string"    }  ]}

Observe

Compozy Observe HTTP endpoints.

Diagnostics

Compozy Diagnostics HTTP endpoints.