Hlix Audit Log 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 Audit Log API
  version: 1.0.0
servers:
- url: https://server.hlix.ai
  description: API server
security:
- apiKey: []
- sessionCookie: []
tags:
- name: Audit Log
paths:
  /v1/api/audit-log:
    get:
      operationId: listAuditLog
      parameters:
      - description: Page size, clamped to 1–200. Defaults to 50.
        in: query
        name: limit
        required: false
        schema:
          type: string
      - description: The previous page's `nextCursor`, verbatim. Opaque — never construct one.
        in: query
        name: cursor
        required: false
        schema:
          type: string
      - description: '`user` | `api_key` | `agent` | `system`.'
        in: query
        name: actorType
        required: false
        schema:
          type: string
      - description: Exact id of the actor.
        in: query
        name: actorId
        required: false
        schema:
          type: string
      - description: Exact action name, such as `project.create`. Unknown actions are ignored and leave the results unfiltered.
        in: query
        name: action
        required: false
        schema:
          type: string
      - description: '`create` | `read` | `update` | `delete` | `execute` | `auth` | `export`.'
        in: query
        name: category
        required: false
        schema:
          type: string
      - description: Exact resource type, such as `project`.
        in: query
        name: resourceType
        required: false
        schema:
          type: string
      - description: Exact resource id.
        in: query
        name: resourceId
        required: false
        schema:
          type: string
      - description: '`success` | `failure` | `denied`.'
        in: query
        name: outcome
        required: false
        schema:
          type: string
      - description: '`info` | `notice` | `warning` | `critical`.'
        in: query
        name: severity
        required: false
        schema:
          type: string
      - description: 'Where the action came in: `web` | `api` | `cli` | `telegram` | `linear` | `github` | `webhook` | `internal` | `system`.'
        in: query
        name: source
        required: false
        schema:
          type: string
      - description: Correlation id of one request.
        in: query
        name: requestId
        required: false
        schema:
          type: string
      - description: Correlation id shared with the other planes.
        in: query
        name: traceId
        required: false
        schema:
          type: string
      - description: Inclusive lower bound on `occurredAt`, as an ISO timestamp. Unparseable values are ignored.
        in: query
        name: from
        required: false
        schema:
          type: string
      - description: Inclusive upper bound on `occurredAt`, ISO.
        in: query
        name: to
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditPage'
          description: One keyset page of audit rows, newest first.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named 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: The caller is not an owner or admin of this workspace — or is not a member of it at all.
        '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 the workspace's audit trail
      tags:
      - Audit Log
  /v1/api/audit-log/projects/{projectId}:
    get:
      operationId: listProjectAuditLog
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - description: Page size, clamped to 1–200. Defaults to 50.
        in: query
        name: limit
        required: false
        schema:
          type: string
      - description: The previous page's `nextCursor`, verbatim. Opaque — never construct one.
        in: query
        name: cursor
        required: false
        schema:
          type: string
      - description: Exact action name.
        in: query
        name: action
        required: false
        schema:
          type: string
      - description: '`user` | `api_key` | `agent` | `system`.'
        in: query
        name: actorType
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditPage'
          description: Rows where the project is the resource, the parent resource, or the value of `metadata.projectId`.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named 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: The caller is not an owner or admin of this workspace — or is not a member of it at all.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such project in this workspace.
      summary: List one project's audit trail
      tags:
      - Audit Log
  /v1/api/audit-log/verify:
    get:
      operationId: verifyAuditChain
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditChainVerification'
          description: Hash-chain verification result. Check `ok`; HTTP 200 alone does not confirm chain integrity.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named 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: The caller is not an owner or admin of this workspace — or is not a member of it at all.
        '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: Verify the tamper-evidence hash chain
      tags:
      - Audit Log
  /v1/api/audit-log/{id}:
    get:
      operationId: getAuditEntry
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEntryDetail'
          description: The entry, plus the events, agent runs and log lines sharing its trace id.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named 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: The caller is not an owner or admin of this workspace — or is not a member of it at all.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such audit entry in this workspace.
      summary: Get one audit entry and its correlated rows
      tags:
      - Audit Log
components:
  schemas:
    ApiError:
      additionalProperties: {}
      properties:
        error:
          type: string
      required:
      - error
      type: object
    AuditEntryDetail:
      properties:
        correlated:
          properties:
            agentRuns:
              items:
                properties:
                  accountingSource:
                    anyOf:
                    - enum:
                      - proxy
                      - driver
                      type: string
                    - type: 'null'
                  billedTo:
                    anyOf:
                    - enum:
                      - workspace_key
                      - hlix
                      type: string
                    - type: 'null'
                  billingMarkupBps:
                    anyOf:
                    - maximum: 9007199254740991
                      minimum: -9007199254740991
                      type: integer
                    - type: 'null'
                  billingProjectKind:
                    type:
                    - string
                    - 'null'
                  coderAccountId:
                    type:
                    - string
                    - 'null'
                  completedAt:
                    type:
                    - string
                    - 'null'
                  costMicros:
                    anyOf:
                    - format: int64
                      maximum: 9007199254740991
                      minimum: -9007199254740991
                      type: integer
                    - type: 'null'
                  credentialKind:
                    anyOf:
                    - enum:
                      - api_key
                      - subscription
                      type: string
                    - type: 'null'
                  cycleId:
                    type:
                    - string
                    - 'null'
                  cycleRunId:
                    type:
                    - string
                    - 'null'
                  durableRunId:
                    type:
                    - string
                    - 'null'
                  fundingMode:
                    anyOf:
                    - enum:
                      - managed
                      - api_key
                      - subscription
                      type: string
                    - type: 'null'
                  id:
                    type: string
                  inputSnapshot:
                    type:
                    - string
                    - 'null'
                  iteration:
                    anyOf:
                    - maximum: 9007199254740991
                      minimum: -9007199254740991
                      type: integer
                    - type: 'null'
                  model:
                    type: string
                  organizationId:
                    type: string
                  outputSnapshot:
                    type:
                    - string
                    - 'null'
                  parentRunId:
                    type:
                    - string
                    - 'null'
                  persona:
                    type:
                    - string
                    - 'null'
                  projectId:
                    type:
                    - string
                    - 'null'
                  role:
                    enum:
                    - planner
                    - builder
                    - tester
                    - reviewer
                    - intake
                    type: string
                  spanId:
                    type:
                    - string
                    - 'null'
                  startedAt:
                    type: string
                  status:
                    enum:
                    - running
                    - completed
                    - failed
                    type: string
                  taskId:
                    type:
                    - string
                    - 'null'
                  tokensIn:
                    anyOf:
                    - maximum: 9007199254740991
                      minimum: -9007199254740991
                      type: integer
                    - type: 'null'
                  tokensOut:
                    anyOf:
                    - maximum: 9007199254740991
                      minimum: -9007199254740991
                      type: integer
                    - type: 'null'
                  traceId:
                    type:
                    - string
                    - 'null'
                  usageCompleteness:
                    anyOf:
                    - enum:
                      - unknown
                      - partial
                      - complete
                      type: string
                    - type: 'null'
                  usageSequence:
                    anyOf:
                    - maximum: 9007199254740991
                      minimum: -9007199254740991
                      type: integer
                    - type: 'null'
                required:
                - id
                - organizationId
                - taskId
                - projectId
                - billingProjectKind
                - billingMarkupBps
                - cycleId
                - role
                - model
                - status
                - tokensIn
                - tokensOut
                - costMicros
                - inputSnapshot
                - outputSnapshot
                - parentRunId
                - persona
                - iteration
                - traceId
                - spanId
                - durableRunId
                - cycleRunId
                - billedTo
                - fundingMode
                - coderAccountId
                - credentialKind
                - accountingSource
                - usageCompleteness
                - usageSequence
                - startedAt
                - completedAt
                type: object
              type: array
            events:
              items:
                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
              type: array
            logs:
              items:
                properties:
                  agentRunId:
                    type:
                    - string
                    - 'null'
                  createdAt:
                    type: string
                  cycleId:
                    type:
                    - string
                    - 'null'
                  id:
                    type: string
                  level:
                    enum:
                    - debug
                    - info
                    - warn
                    - error
                    type: string
                  message:
                    type: string
                  organizationId:
                    type: string
                  spanId:
                    type:
                    - string
                    - 'null'
                  taskId:
                    type:
                    - string
                    - 'null'
                  traceId:
                    type:
                    - string
                    - 'null'
                required:
                - id
                - organizationId
                - taskId
                - cycleId
                - agentRunId
                - traceId
                - spanId
                - level
                - message
                - createdAt
                type: object
              type: array
          required:
          - events
          - agentRuns
          - logs
          type: object
        entry:
          properties:
            action:
              type: string
            actorId:
              type:
              - string
              - 'null'
            actorLabel:
              type:
              - string
              - 'null'
            actorType:
              enum:
              - user
              - api_key
              - agent
              - system
              type: string
            agentId:
              type:
              - string
              - 'null'
            attributedUserId:
              type:
              - string
              - 'null'
            category:
              enum:
              - create
              - read
              - update
              - delete
              - execute
              - auth
              - export
              type: string
            changes: {}
            id:
              type: string
            ipAddress:
              type:
              - string
              - 'null'
            metadata: {}
            occurredAt:
              type: string
            onBehalfOfId:
              type:
              - string
              - 'null'
            organizationId:
              type: string
            outcome:
              enum:
              - success
              - failure
              - denied
              type: string
            parentResourceId:
              type:
              - string
              - 'null'
            parentResourceType:
              type:
              - string
              - 'null'
            prevHash:
              type:
              - string
              - 'null'
            reason:
              type:
              - string
              - 'null'
            recordedAt:
              type: string
            requestId:
              type:
              - string
              - 'null'
            resourceId:
              type:
              - string
              - 'null'
            resourceLabel:
              type:
              - string
              - 'null'
            resourceType:
              type: string
            rowHash:
              type:
              - string
              - 'null'
            severity:
              enum:
              - info
              - notice
              - warning
              - critical
              type: string
            source:
              enum:
              - web
              - api
              - cli
              - telegram
              - linear
              - github
              - webhook
              - internal
              - system
              type: string
            spanId:
              type:
              - string
              - 'null'
            traceId:
              type:
              - string
              - 'null'
            userAgent:
              type:
              - string
              - 'null'
          required:
          - id
          - organizationId
          - actorType
          - actorId
          - actorLabel
          - onBehalfOfId
          - action
          - category
          - resourceType
          - resourceId
          - resourceLabel
          - parentResourceType
          - parentResourceId
          - changes
          - metadata
          - source
          - ipAddress
          - userAgent
          - requestId
          - traceId
          - spanId
          - outcome
          - severity
          - reason
          - agentId
          - attributedUserId
          - prevHash
          - rowHash
          - occurredAt
          - recordedAt
          type: object
      required:
      - entry
      - correlated
      type: object
    AuditPage:
      properties:
        items:
          items:
            properties:
              action:
                type: string
              actorId:
                type:
                - string
                - 'null'
              actorLabel:
                type:
                - string
                - 'null'
              actorType:
                enum:
                - user
                - api_key
                - agent
                - system
                type: string
              agentId:
                type:
                - string
                - 'null'
              attributedUserId:
                type:
                - string
                - 'null'
              category:
                enum:
                - create
                - read
                - update
                - delete
                - execute
                - auth
                - export
                type: string
              changes: {}
              id:
                type: string
              ipAddress:
                type:
                - string
                - 'null'
              metadata: {}
              occurredAt:
                type: string
              onBehalfOfId:
                type:
                - string
                - 'null'
              organizationId:
                type: string
              outcome:
                enum:
                - success
                - failure
                - denied
                type: string
              parentResourceId:
                type:
                - string
                - 'null'
              parentResourceType:
                type:
                - string
                - 'null'
              prevHash:
                type:
                - string
                - 'null'
              reason:
                type:
                - string
                - 'null'
              recordedAt:
                type: string
              requestId:
                type:
                - string
                - 'null'
              resourceId:
                type:
                - string
                - 'null'
              resourceLabel:
                type:
                - string
                - 'null'
              resourceType:
                type: string
              rowHash:
                type:
                - string
                - 'null'
              severity:
                enum:
                - info
                - notice
                - warning
                - critical
                type: string
              source:
                enum:
                - web
                - api
                - cli
                - telegram
                - linear
                - github
                - webhook
                - internal
                - system
                type: string
              spanId:
                type:
                - string
                - 'null'
              traceId:
                type:
                - string
                - 'null'
              userAgent:
                type:
                - string
                - 'null'
            required:
            - id
            - organizationId
            - actorType
            - actorId
            - actorLabel
            - onBehalfOfId
            - action
            - category
            - resourceType
            - resourceId
            - resourceLabel
            - parentResourceType
            - parentResourceId
            - changes
            - metadata
            - source
            - ipAddress
            - userAgent
            - requestId
            - traceId
            - spanId
            - outcome
            - severity
            - reason
            - agentId
            - attributedUserId
            - prevHash
            - rowHash
            - occurredAt
            - recordedAt
            type: object
          type: array
        nextCursor:
          type:
          - string
          - 'null'
      required:
      - items
      - nextCursor
      type: object
    AuditChainVerification:
      properties:
        checked:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        firstBadId:
          type:
          - string
          - 'null'
        ok:
          type: boolean
        total:
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
      required:
      - ok
      - checked
      - total
      - firstBadId
      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