> ## Documentation Index > Fetch the complete documentation index at: https://docs.getcliq.io/llms.txt > Use this file to discover all available pages before exploring further. # 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](/daemon-api/overview#authentication). ## OpenAPI ````yaml /openapi/daemon-by-tag/daemon-runs.yaml post /v1/runs/events openapi: 3.1.0 info: title: cliqd API version: 1.9.48 description: >- HTTP API of `cliqd`, the local Cliq daemon. Generated from the daemon source by `scripts/generate_daemon_openapi.mjs` — do not edit by hand. See the [overview](/daemon-api/overview). servers: - url: http://127.0.0.1:4900 description: Local daemon (default port; `CLIQ_DAEMON_PORT` changes it) security: [] tags: - name: Daemon Runs description: >- Runs on this daemon. Start one with Start a run (Workspaces); everything after that is here: list runs, read a run's log, phases and tree of sub-runs, follow it live, supply the inputs a paused run is waiting for, and rerun a finished run from a phase. Wherever a body takes `run_id` you may also send the run's **name**, except the event endpoints, which need the id. Run ids are UUIDs. A run's life: `running` → (`awaiting_input` ↔ `running`)* → `completed`, `failed`, `cancelled` or `crashed`. paths: /v1/runs/events: post: tags: - Daemon Runs summary: Push a run event description: >- 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](/daemon-api/overview#authentication). operationId: daemon_post_runs_events requestBody: required: true content: application/json: schema: type: object properties: run_id: type: string minLength: 1 description: Run id event_type: type: string minLength: 1 description: Event type, e.g. `phase.completed` phase: description: Phase the event belongs to type: - string - 'null' agent: description: Agent that emitted it type: - string - 'null' payload: description: Event payload (artifacts, error, message …) anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' required: - run_id - event_type additionalProperties: {} examples: phase_done: summary: A phase finished value: run_id: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f event_type: phase.completed phase: review agent: claude-code payload: message: 3 findings custom: summary: A custom event for notification rules value: run_id: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f event_type: custom_event phase: review payload: custom_type: custom.security_finding message: Hard-coded token in config.ts responses: '200': description: Success. content: application/json: schema: type: object required: - ok - data properties: ok: type: boolean const: true data: $ref: '#/components/schemas/RunEventAccepted' example: ok: true data: id: 1842 run_id: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f '400': description: >- `PAYLOAD_INVALID` — The body (query string for `GET`) fails the request schema. `details` lists each issue. `BAD_REQUEST` — The body is not valid JSON or is larger than the route allows (10 MB; artifact uploads more). content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: PAYLOAD_INVALID: summary: PAYLOAD_INVALID value: ok: false error: code: PAYLOAD_INVALID message: >- run_id: Invalid input: expected string, received undefined; event_type: Invalid input: expected string, received undefined details: - path: run_id message: 'Invalid input: expected string, received undefined' - path: event_type message: 'Invalid input: expected string, received undefined' BAD_REQUEST: summary: BAD_REQUEST value: ok: false error: code: BAD_REQUEST message: >- Request body could not be read: Unexpected token } in JSON at position 12 '401': description: >- `UNAUTHORIZED` — A caller on another host sent no `Authorization: Bearer` token, or one that does not verify (expired, wrong audience). content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: UNAUTHORIZED: summary: UNAUTHORIZED value: ok: false error: code: UNAUTHORIZED message: Missing or invalid Authorization Bearer token '403': description: >- `WEB_REQUEST_REFUSED` — The request carries an `Origin` header (it came from a web page). `HOST_NOT_LOCAL` — A loopback caller addressed a `Host` other than localhost (DNS rebinding guard). `LOCAL_ONLY` — The daemon isn't connected to CliqHub (no dispatch key) and the caller is on another host. `FORBIDDEN` — A `cliq_tok_…` token's user is not in this daemon's realm ACL, or the ACL is not loaded yet. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: WEB_REQUEST_REFUSED: summary: WEB_REQUEST_REFUSED value: ok: false error: code: WEB_REQUEST_REFUSED message: cliqd doesn't accept requests from web pages HOST_NOT_LOCAL: summary: HOST_NOT_LOCAL value: ok: false error: code: HOST_NOT_LOCAL message: cliqd only answers requests addressed to localhost LOCAL_ONLY: summary: LOCAL_ONLY value: ok: false error: code: LOCAL_ONLY message: >- This cliqd isn't connected to CliqHub yet, so from another machine it only accepts a local token (minted by tokens/create on the machine running cliqd) FORBIDDEN: summary: FORBIDDEN value: ok: false error: code: FORBIDDEN message: Access denied — identity not in realm ACL '404': description: >- `RUN_NOT_FOUND` — No run has this id (a run name is not accepted here). content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: RUN_NOT_FOUND: summary: RUN_NOT_FOUND value: ok: false error: code: RUN_NOT_FOUND message: Run '0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f' not found '500': description: >- `INTERNAL_ERROR` — An unexpected daemon fault. The message names the request id; the cause is in the cliqd log. content: application/json: schema: $ref: '#/components/schemas/ErrorReply' examples: INTERNAL_ERROR: summary: INTERNAL_ERROR value: ok: false error: code: INTERNAL_ERROR message: >- cliqd hit an unexpected error (request 7f3a…). Details are in the cliqd log. security: - {} - DaemonBearer: [] components: schemas: RunEventAccepted: type: object required: - id - run_id properties: id: type: integer description: >- Sequence number of the event on this daemon (increases across all runs). example: 1842 run_id: type: string format: uuid example: 0c8d7e6f-5a4b-4c3d-9e2f-1a0b9c8d7e6f ErrorReply: type: object description: >- Every failure. Switch on `error.code` — it is stable; `message` is for people and may change. required: - ok - error properties: ok: type: boolean const: false error: type: object required: - code - message properties: code: type: string description: Stable error code. See [Errors](/daemon-api/errors). example: TEAM_NOT_FOUND message: type: string description: What went wrong and, where possible, what to do. example: Team 'acme/code-review' not found details: description: >- Structured detail when there is some: the list of schema issues for `PAYLOAD_INVALID`, the agent problems for `TEAM_AGENT_CONFIG_REQUIRED`, … securitySchemes: DaemonBearer: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.