Skip to content
hlix docs

Events

Generated from contract version 1.0.0 — the same document /v1/api/openapi.json serves.

Prerequisites

Section titled “Prerequisites”
  • An API key in x-api-key, or a browser session cookie
  • X-Organization-Id naming the workspace to act in, unless the session already has an active one
  • The base URL for your deployment, https://server.hlix.ai by default

Operations

Section titled “Operations”
Method Path Operation
GET /v1/api/events List activity events

List activity events

Section titled “List activity events”

GET /v1/api/events · operation ID listEvents

Parameters

Name In Required Type Description
cycleId query no string The cycle’s own events plus its child tasks’. Checked FIRST — it overrides every other selector.
traceId query no string Every event of one trace. Checked second, ahead of eventType and the entity pair.
eventType query no string Exact event name, such as task.merged. Checked third.
entityType query no string cycle | task | project | agent_run | pending_request. Only read together with entityId.
entityId query no string The entity’s id. Required with entityType.
limit query no string Recent-activity page size, clamped to 1–500 (default 100). Supplying it (or before) is what selects the org-wide feed.
before query no string ISO timestamp — the org-wide feed’s keyset cursor. Rows strictly older than this, newest first.
X-Organization-Id header no string The workspace (organization) to act in. Omitted, the session’s active organization is used.

Responses

Status Body Description
200 ActivityEvent[] The matching events, newest first — except the cycleId timeline, which is oldest first.
400 ApiError No selector was supplied, or the request named no active organization.
401 ApiError No valid session or API key.
403 ApiError Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
404 ApiError The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.

If a request fails

Section titled “If a request fails”

These apply to every operation on this page.

  • 400 — the body failed schema validation, or the request named no active organization. A ValidationError body carries the failing fields; an ApiError body carries only error.
  • 401 — no valid session or API key.
  • 403 — authenticated, but not a member of the named organization, or a client collaborator without the required access.
  • 404 — no such resource in this workspace. Absent and not-visible are deliberately the same answer; do not infer cross-tenant existence from it.
  • 409 — the expected revision or state is stale, or another operation currently owns the transition.
  • 500 — the operation failed server-side. Retry only where an idempotency key makes that safe.

Next steps

Section titled “Next steps”
API referenceEvery resource in the published contract, and what is deliberately not in it.
API & OpenAPIDownload the contract, generate a client, and read the compatibility policy.
TypeScript SDKAuth, retries, typed errors, uploads and streaming, already built.
CLI referenceThe same operations from a terminal, with a stable JSON envelope.