Push a run event

Reports something that happened in a run. Agents call this through the SDK; you normally do not. The event is sent to everyone following the run (Stream run events) and forwarded to CliqHub for notifications. It is not stored on the daemon.

Some event types change the run: run.completed, run.failed and run.crashed end it (payload.error is recorded as the reason), phase.input_required pauses it (awaiting_input), and phase.inputs_supplied resumes it. Files listed in the payload are uploaded as the run’s artifacts. A custom_event with payload.custom_type is forwarded to CliqHub as a custom event that notification rules can match.

No credential is needed from this machine. From another host, send Authorization: Bearer with a dispatch token CliqHub signed for this daemon or a cliq_tok_… personal token of a user in the daemon’s realm; this only works once the daemon is connected to CliqHub. See Authentication.

POST /v1/runs/events

cURL

phase_done

curl --request POST \ --url http://127.0.0.1:4900/v1/runs/events \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "run_id": "0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f", "event_type": "phase.completed", "phase": "review", "agent": "claude-code", "payload": { "message": "3 findings" } } '

200

Example

{ "ok": true, "data": { "id": 1842, "run_id": "0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f" } }

Authorizations

Authorization · string · header · required

Not needed from the same machine. From another host: a dispatch JWT CliqHub signed for this daemon, or a cliq_tok_… personal token whose user is in the daemon's realm.

Body

application/json

run_id · string · required

Run id

Minimum string length: 1

event_type · string · required

Event type, e.g. phase.completed

Minimum string length: 1

phase · string | null

Phase the event belongs to

agent · string | null

Agent that emitted it

payload · object | null

Event payload (artifacts, error, message …)

Show child attributes

{key} · any

Response

200

application/json

Success.

ok · boolean · required

data · object · required

Show child attributes