Hlix Client Billing 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 Client Billing API
  version: 1.0.0
servers:
- url: https://server.hlix.ai
  description: API server
security:
- apiKey: []
- sessionCookie: []
tags:
- name: client-billing
paths:
  /v1/api/client-billing/billables:
    get:
      operationId: listClientBillables
      parameters:
      - description: Only this customer's rows.
        in: query
        name: clientAccountId
        required: false
        schema:
          type: string
      - description: Limit results to this project. A client collaborator without project access receives an access error rather than an empty ledger.
        in: query
        name: projectId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/ClientBillableView'
                type: array
          description: The matching rows, each with the derived `netAmountMicros` and any void that reverses it.
        '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: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller cannot access the requested `projectId`. Project-filtered reads return an access error rather than an empty ledger; unfiltered reads omit inaccessible rows.
      summary: List the ledger
      tags:
      - client-billing
    post:
      operationId: createClientBillable
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBillable'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientBillable'
          description: The saved billable with its price fixed at creation. For `agent_usage`, token counts and model are taken from the recorded run rather than the request.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '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 a client collaborator; the billable ledger is managed by the agency.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such client account or project in this workspace. Never a 403 — that would confirm it exists somewhere.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: This source was already billed. A retried request is the usual cause.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: A database constraint prevented the row from being saved. The response identifies the constraint.
      summary: Record a billable
      tags:
      - client-billing
  /v1/api/client-billing/billables/{id}:
    get:
      operationId: getClientBillable
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientBillableView'
          description: The row, with its derived net and void.
        '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: Authenticated, but not a member of the named organization — or a client collaborator without the required access on this project.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such billable this caller may read.
      summary: Get one ledger row
      tags:
      - client-billing
  /v1/api/client-billing/billables/{id}/adjust:
    post:
      operationId: adjustClientBillable
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustBillable'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientBillable'
          description: A new correction row referencing the original charge. The original charge is unchanged.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed validation, or 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 a client collaborator; the billable ledger is managed by the agency.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such billable this caller may reach.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: A correction cannot target another correction or a voided charge. The response identifies the violated rule.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: A database constraint prevented the row from being saved. The response identifies the constraint.
      summary: Append a correction to a charge
      tags:
      - client-billing
  /v1/api/client-billing/billables/{id}/void:
    post:
      operationId: voidClientBillable
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoidBillable'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientBillable'
          description: A new reversal row covering the charge and all its corrections, so the complete net amount is reversed.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed validation, or 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 a client collaborator; the billable ledger is managed by the agency.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No such billable this caller may reach.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The charge was already voided or cannot be voided for the rule identified in the response. A charge can be voided only once.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: A database constraint prevented the row from being saved. The response identifies the constraint.
      summary: Reverse a charge
      tags:
      - client-billing
components:
  schemas:
    ApiError:
      additionalProperties: {}
      properties:
        error:
          type: string
      required:
      - error
      type: object
    ClientBillable:
      properties:
        amountMicros:
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        clientAccountId:
          type: string
        createdAt:
          type: string
        createdBy:
          type: string
        currency:
          type: string
        description:
          type: string
        entryType:
          enum:
          - charge
          - adjustment
          - void
          type: string
        id:
          type: string
        occurredAt:
          type: string
        organizationId:
          type: string
        projectId:
          type:
          - string
          - 'null'
        quantity:
          type: string
        rateSnapshot:
          anyOf:
          - properties:
              basis:
                const: agreed_rate
                type: string
              capturedAt:
                type: string
              note:
                type:
                - string
                - 'null'
            required:
            - basis
            - capturedAt
            - note
            type: object
          - properties:
              basis:
                const: model_pricing
                type: string
              capturedAt:
                type: string
              costMicros:
                format: int64
                maximum: 9007199254740991
                minimum: -9007199254740991
                type: integer
              inputPricePerMTokensMicros:
                format: int64
                maximum: 9007199254740991
                minimum: -9007199254740991
                type: integer
              markupBps:
                type: number
              modelIdentifier:
                type: string
              outputPricePerMTokensMicros:
                format: int64
                maximum: 9007199254740991
                minimum: -9007199254740991
                type: integer
              tokensIn:
                type: number
              tokensOut:
                type: number
            required:
            - basis
            - capturedAt
            - modelIdentifier
            - inputPricePerMTokensMicros
            - outputPricePerMTokensMicros
            - tokensIn
            - tokensOut
            - costMicros
            - markupBps
            type: object
        replacesBillableId:
          type:
          - string
          - 'null'
        source:
          enum:
          - outcome
          - agent_usage
          - manual
          type: string
        sourceEntityId:
          type:
          - string
          - 'null'
        sourceEntityType:
          type:
          - string
          - 'null'
        sourceEvidence:
          additionalProperties: {}
          propertyNames:
            type: string
          type: object
        taxClass:
          enum:
          - standard
          - reduced
          - zero
          - exempt
          - reverse_charge
          type: string
        unit:
          type: string
        unitPriceMicros:
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
      required:
      - id
      - organizationId
      - clientAccountId
      - projectId
      - entryType
      - replacesBillableId
      - source
      - sourceEntityType
      - sourceEntityId
      - sourceEvidence
      - rateSnapshot
      - description
      - quantity
      - unit
      - unitPriceMicros
      - amountMicros
      - currency
      - taxClass
      - occurredAt
      - createdBy
      - createdAt
      type: object
    CreateBillable:
      oneOf:
      - additionalProperties: false
        properties:
          clientAccountId:
            minLength: 1
            type: string
          currency:
            pattern: ^[A-Z]{3}$
            type: string
          description:
            maxLength: 500
            minLength: 1
            type: string
          note:
            anyOf:
            - maxLength: 500
              type: string
            - type: 'null'
          occurredAt:
            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
          projectId:
            anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          quantity:
            type: number
          source:
            const: manual
            type: string
          taxClass:
            enum:
            - standard
            - reduced
            - zero
            - exempt
            - reverse_charge
            type: string
          unit:
            maxLength: 50
            minLength: 1
            type: string
          unitPriceMicros:
            format: int64
            maximum: 1000000000000
            minimum: 0
            type: integer
        required:
        - source
        - clientAccountId
        - currency
        - description
        - unit
        - quantity
        - unitPriceMicros
        type: object
      - additionalProperties: false
        properties:
          currency:
            pattern: ^[A-Z]{3}$
            type: string
          cycleId:
            minLength: 1
            type: string
          description:
            maxLength: 500
            minLength: 1
            type: string
          note:
            anyOf:
            - maxLength: 500
              type: string
            - type: 'null'
          quantity:
            type: number
          source:
            const: outcome
            type: string
          taxClass:
            enum:
            - standard
            - reduced
            - zero
            - exempt
            - reverse_charge
            type: string
          unit:
            maxLength: 50
            minLength: 1
            type: string
          unitPriceMicros:
            format: int64
            maximum: 1000000000000
            minimum: 0
            type: integer
        required:
        - source
        - cycleId
        - currency
        - description
        - unit
        - quantity
        - unitPriceMicros
        type: object
      - additionalProperties: false
        properties:
          agentRunId:
            minLength: 1
            type: string
          currency:
            const: USD
            type: string
          description:
            maxLength: 500
            minLength: 1
            type: string
          markupBps:
            default: 0
            maximum: 100000
            minimum: 0
            type: integer
          source:
            const: agent_usage
            type: string
          taxClass:
            enum:
            - standard
            - reduced
            - zero
            - exempt
            - reverse_charge
            type: string
        required:
        - source
        - agentRunId
        - currency
        - description
        type: object
    AdjustBillable:
      additionalProperties: false
      properties:
        description:
          maxLength: 500
          minLength: 1
          type: string
        note:
          anyOf:
          - maxLength: 500
            type: string
          - type: 'null'
        quantity:
          type: number
        unit:
          maxLength: 50
          minLength: 1
          type: string
        unitPriceMicros:
          format: int64
          maximum: 1000000000000
          minimum: 0
          type: integer
      required:
      - unit
      - quantity
      - unitPriceMicros
      - description
      type: object
    VoidBillable:
      additionalProperties: false
      properties:
        reason:
          maxLength: 500
          minLength: 1
          type: string
      required:
      - reason
      type: object
    ValidationError:
      properties:
        error:
          properties:
            message:
              type: string
            name:
              type: string
          required:
          - name
          - message
          type: object
        success:
          const: false
          type: boolean
      required:
      - success
      - error
      type: object
    ClientBillableView:
      properties:
        amountMicros:
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        clientAccountId:
          type: string
        createdAt:
          type: string
        createdBy:
          type: string
        currency:
          type: string
        description:
          type: string
        entryType:
          enum:
          - charge
          - adjustment
          - void
          type: string
        id:
          type: string
        netAmountMicros:
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        occurredAt:
          type: string
        organizationId:
          type: string
        projectId:
          type:
          - string
          - 'null'
        quantity:
          type: string
        rateSnapshot:
          anyOf:
          - properties:
              basis:
                const: agreed_rate
                type: string
              capturedAt:
                type: string
              note:
                type:
                - string
                - 'null'
            required:
            - basis
            - capturedAt
            - note
            type: object
          - properties:
              basis:
                const: model_pricing
                type: string
              capturedAt:
                type: string
              costMicros:
                format: int64
                maximum: 9007199254740991
                minimum: -9007199254740991
                type: integer
              inputPricePerMTokensMicros:
                format: int64
                maximum: 9007199254740991
                minimum: -9007199254740991
                type: integer
              markupBps:
                type: number
              modelIdentifier:
                type: string
              outputPricePerMTokensMicros:
                format: int64
                maximum: 9007199254740991
                minimum: -9007199254740991
                type: integer
              tokensIn:
                type: number
              tokensOut:
                type: number
            required:
            - basis
            - capturedAt
            - modelIdentifier
            - inputPricePerMTokensMicros
            - outputPricePerMTokensMicros
            - tokensIn
            - tokensOut
            - costMicros
            - markupBps
            type: object
        replacesBillableId:
          type:
          - string
          - 'null'
        source:
          enum:
          - outcome
          - agent_usage
          - manual
          type: string
        sourceEntityId:
          type:
          - string
          - 'null'
        sourceEntityType:
          type:
          - string
          - 'null'
        sourceEvidence:
          additionalProperties: {}
          propertyNames:
            type: string
          type: object
        taxClass:
          enum:
          - standard
          - reduced
          - zero
          - exempt
          - reverse_charge
          type: string
        unit:
          type: string
        unitPriceMicros:
          format: int64
          maximum: 9007199254740991
          minimum: -9007199254740991
          type: integer
        voidedByBillableId:
          type:
          - string
          - 'null'
      required:
      - id
      - organizationId
      - clientAccountId
      - projectId
      - entryType
      - replacesBillableId
      - source
      - sourceEntityType
      - sourceEntityId
      - sourceEvidence
      - rateSnapshot
      - description
      - quantity
      - unit
      - unitPriceMicros
      - amountMicros
      - currency
      - taxClass
      - occurredAt
      - createdBy
      - createdAt
      - voidedByBillableId
      - netAmountMicros
      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