Hlix Events API

openapi: 3.2.0
info:
  description: Explore the Hlix API for projects, agent teams, and delivery workflows. Authenticate with `x-api-key` and select a Workspace with `X-Organization-Id`. Session-only operations require a signed-in user session. Authentication setup.
  title: reference Events API
  version: 1.0.0
servers:
- url: https://server.hlix.ai
  description: API server
security:
- apiKey: []
- sessionCookie: []
tags:
- name: Events
paths:
  /v1/api/events:
    get:
      operationId: listEvents
      parameters:
      - description: 'UTC calendar-day window: 7, 30, 90 or 365, including today. Summary defaults to 30; omitted on the recent feed means all retained events.'
        in: query
        name: days
        required: false
        schema:
          type: string
      - description: Only events owned by this project, through its cycle/task/run or explicitly recorded project context. Always workspace-fenced.
        in: query
        name: projectId
        required: false
        schema:
          type: string
      - description: Only events recorded as user, agent or system.
        in: query
        name: actorType
        required: false
        schema:
          type: string
      - description: Only events with this exact recorded actor id.
        in: query
        name: actorId
        required: false
        schema:
          type: string
      - description: The cycle's events and its tasks' events. This selector takes precedence over all others.
        in: query
        name: cycleId
        required: false
        schema:
          type: string
      - description: Every event of one trace. Checked second, ahead of `eventType` and the entity pair.
        in: query
        name: traceId
        required: false
        schema:
          type: string
      - description: Exact event name, such as `task.merged`. Checked third.
        in: query
        name: eventType
        required: false
        schema:
          type: string
      - description: '`cycle` | `task` | `project` | `agent_run` | `pending_request`. Only read together with `entityId`.'
        in: query
        name: entityType
        required: false
        schema:
          type: string
      - description: The entity's id. Required with `entityType`.
        in: query
        name: entityId
        required: false
        schema:
          type: string
      - description: Recent-activity page size, integer 1–500 (default 100). Supplying it, before or an activity filter selects the recent feed.
        in: query
        name: limit
        required: false
        schema:
          type: string
      - description: ISO timestamp from the last event. Include beforeId for complete pagination when events share a timestamp. Without beforeId, preserves the legacy strictly-older behavior.
        in: query
        name: before
        required: false
        schema:
          type: string
      - description: The last event id from the previous page, together with before. Results are ordered by timestamp and id descending; the database cursor retains full timestamp precision.
        in: query
        name: beforeId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ActivityEvent'
                type: array
          description: The matching events, newest first — except the `cycleId` timeline, which is oldest first.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Invalid activity filters, no selector, or no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency membership required.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: List activity events
      tags:
      - Events
  /v1/api/events/summary:
    get:
      operationId: getActivitySummary
      parameters:
      - description: 'UTC calendar-day window: 7, 30, 90 or 365, including today. Summary defaults to 30; omitted on the recent feed means all retained events.'
        in: query
        name: days
        required: false
        schema:
          type: string
      - description: Only events owned by this project, through its cycle/task/run or explicitly recorded project context. Always workspace-fenced.
        in: query
        name: projectId
        required: false
        schema:
          type: string
      - description: Only events recorded as user, agent or system.
        in: query
        name: actorType
        required: false
        schema:
          type: string
      - description: Only events with this exact recorded actor id.
        in: query
        name: actorId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivitySummary'
          description: Agency-only. Counts all matching retained events in the period, independently of feed pagination. Daily counts are zero-filled UTC dates; actor breakdown is the top 50 and event types the top 20. This is best-effort activity, not the audit log or a guarantee of completed work.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Invalid filters or no active workspace.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Agency membership required.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: Summarize recorded workspace activity
      tags:
      - Events
components:
  schemas:
    ApiError:
      additionalProperties: {}
      properties:
        error:
          type: string
      required:
      - error
      type: object
    ActivitySummary:
      properties:
        actors:
          items:
            properties:
              actorId:
                type:
                - string
                - 'null'
              actorType:
                enum:
                - system
                - user
                - agent
                type: string
              count:
                maximum: 9007199254740991
                minimum: 0
                type: integer
            required:
            - actorType
            - actorId
            - count
            type: object
          type: array
        daily:
          items:
            properties:
              count:
                maximum: 9007199254740991
                minimum: 0
                type: integer
              date:
                type: string
            required:
            - date
            - count
            type: object
          type: array
        eventTypes:
          items:
            properties:
              count:
                maximum: 9007199254740991
                minimum: 0
                type: integer
              eventType:
                type: string
            required:
            - eventType
            - count
            type: object
          type: array
        period:
          properties:
            days:
              anyOf:
              - const: 7
                type: number
              - const: 30
                type: number
              - const: 90
                type: number
              - const: 365
                type: number
            from:
              format: date-time
              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
              type: string
            to:
              format: date-time
              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
              type: string
          required:
          - days
          - from
          - to
          type: object
        total:
          maximum: 9007199254740991
          minimum: 0
          type: integer
      required:
      - period
      - total
      - daily
      - actors
      - eventTypes
      type: object
    ActivityEvent:
      properties:
        actorId:
          type:
          - string
          - 'null'
        actorType:
          enum:
          - system
          - user
          - agent
          type: string
        entityId:
          type: string
        entityType:
          enum:
          - cycle
          - task
          - project
          - agent_run
          - pending_request
          type: string
        eventType:
          type: string
        id:
          type: string
        organizationId:
          type: string
        payload: {}
        spanId:
          type:
          - string
          - 'null'
        timestamp:
          type: string
        traceId:
          type:
          - string
          - 'null'
      required:
      - id
      - organizationId
      - entityType
      - entityId
      - eventType
      - payload
      - actorType
      - actorId
      - traceId
      - spanId
      - timestamp
      type: object
  parameters:
    OrganizationId:
      description: The workspace (organization) to act in. Omitted, the session's active organization is used.
      in: header
      name: X-Organization-Id
      required: false
      schema:
        type: string
      example: YOUR_WORKSPACE_ID
  securitySchemes:
    apiKey:
      description: An API key issued through `/v1/api/auth/api-key/*`. Browser clients can use their session cookie instead.
      in: header
      name: x-api-key
      type: apiKey
    sessionCookie:
      description: The complete session Cookie header issued by sign-in at the selected API host. Cookie names vary by hosting region and environment; preserve the issued name and value. Browsers send these HTTP-only cookies automatically. Session-only operations require this user session and do not accept an API key.
      in: header
      name: Cookie
      type: apiKey