Paid value-models API

openapi: 3.1.0
info:
  title: API Reference agents value-models API
  version: 1.0.0
servers:
- url: https://api.agentpaid.io/api/v1
  description: Production
tags:
- name: value-models
paths:
  /value-models/:
    get:
      operationId: get-current-value-model
      summary: Get current value model
      description: Returns the current (latest active) value model for the organization.
      tags:
      - value-models
      parameters:
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueModelDetail'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: update-value-model
      summary: Upload value model
      description: Uploads a new value model version. Validates the content, creates a new version, archives the previous active version, syncs to ClickHouse, and triggers a backfill of all historical signals.
      tags:
      - value-models
      parameters:
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueModelDetail'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValueModelUploadRequest'
  /value-models/versions:
    get:
      operationId: list-value-model-versions
      summary: List version history
      description: Returns all value model versions sorted by version descending. Does not include the full content.
      tags:
      - value-models
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
      - name: offset
        in: query
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueModelVersionListResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /value-models/versions/{version}:
    get:
      operationId: get-value-model-version
      summary: Get specific version
      description: Returns a specific historical value model version by version number, including full content.
      tags:
      - value-models
      parameters:
      - name: version
        in: path
        required: true
        schema:
          type: integer
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValueModelDetail'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /value-models/backfill:
    post:
      operationId: refresh-value-model-backfill
      summary: Trigger backfill
      description: Manually triggers a recalculation of all ClickHouse rows against the current value model.
      tags:
      - value-models
      parameters:
      - name: Authorization
        in: header
        description: API Key authentication using Bearer token
        required: true
        schema:
          type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackfillResponse'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties: {}
components:
  schemas:
    ValueModelContentOverridesItemsSignalOverridesDefaults:
      oneOf:
      - type: number
        format: double
      - type: string
      title: ValueModelContentOverridesItemsSignalOverridesDefaults
    ValueModelContentOverridesItemsAdditionalSignalsItemsDefaults:
      oneOf:
      - type: number
        format: double
      - type: string
      title: ValueModelContentOverridesItemsAdditionalSignalsItemsDefaults
    ValueModelContentFormulasItemsConditionsItemsResultType:
      type: string
      enum:
      - constant
      - expression
      title: ValueModelContentFormulasItemsConditionsItemsResultType
    ValueModelContentOverridesItems:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        scope:
          $ref: '#/components/schemas/ValueModelContentOverridesItemsScope'
        currency:
          type: string
        signalOverrides:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ValueModelContentOverridesItemsSignalOverrides'
        additionalSignals:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentOverridesItemsAdditionalSignalsItems'
        monetaryConversionOverrides:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ValueModelContentOverridesItemsMonetaryConversionOverrides'
      required:
      - id
      - label
      - scope
      title: ValueModelContentOverridesItems
    ValueModelContentFormulasItemsVariablesItemsDerivedFromTargetUnit:
      type: string
      enum:
      - seconds
      - minutes
      - hours
      - days
      title: ValueModelContentFormulasItemsVariablesItemsDerivedFromTargetUnit
    ValueModelUploadRequest:
      type: object
      properties:
        content:
          $ref: '#/components/schemas/ValueModelContent'
        effectiveFrom:
          type: string
          format: date-time
        effectiveTo:
          type: string
          format: date-time
      required:
      - content
      title: ValueModelUploadRequest
    ValueModelContentSegmentTablesItemsColumnsItems:
      type: object
      properties:
        variableId:
          type: string
        label:
          type: string
        type:
          $ref: '#/components/schemas/ValueModelContentSegmentTablesItemsColumnsItemsType'
      required:
      - variableId
      - label
      - type
      title: ValueModelContentSegmentTablesItemsColumnsItems
    ValueModelContentFormulasItemsConditionsItemsResult:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ValueModelContentFormulasItemsConditionsItemsResultType'
        value:
          type: number
          format: double
        expression:
          type: string
      required:
      - type
      title: ValueModelContentFormulasItemsConditionsItemsResult
    ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsResultType:
      type: string
      enum:
      - constant
      - expression
      title: ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsResultType
    ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsOperator:
      type: string
      enum:
      - gte
      - gt
      - lt
      - lte
      - eq
      - neq
      - contains
      - eq_string
      - eq_bool
      title: ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsOperator
    ValueModelContentOverridesItemsMonetaryConversionOverrides:
      type: object
      properties:
        variables:
          type: object
          additionalProperties:
            type: number
            format: double
      title: ValueModelContentOverridesItemsMonetaryConversionOverrides
    ValueModelContentFormulasItemsDefaultResult:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ValueModelContentFormulasItemsDefaultResultType'
        value:
          type: number
          format: double
        expression:
          type: string
      required:
      - type
      title: ValueModelContentFormulasItemsDefaultResult
    ValueModelVersionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelSummary'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - data
      - pagination
      title: ValueModelVersionListResponse
    ValueModelContentValueTypesItemsMonetaryConversion:
      type: object
      properties:
        expression:
          type: string
        variables:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentValueTypesItemsMonetaryConversionVariablesItems'
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentValueTypesItemsMonetaryConversionConditionsItems'
      required:
      - expression
      title: ValueModelContentValueTypesItemsMonetaryConversion
    ValueModelContentSegmentTablesItems:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        segmentKeys:
          type: array
          items:
            type: string
        columns:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentSegmentTablesItemsColumnsItems'
        rows:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentSegmentTablesItemsRowsItems'
        defaultRow:
          type: object
          additionalProperties:
            type: number
            format: double
      required:
      - id
      - label
      - segmentKeys
      - columns
      - rows
      title: ValueModelContentSegmentTablesItems
    ValueModelContentSegmentTablesItemsColumnsItemsType:
      type: string
      enum:
      - number
      title: ValueModelContentSegmentTablesItemsColumnsItemsType
    ValueModelContentSignalsItems:
      type: object
      properties:
        eventName:
          type: string
        label:
          type: string
        formulaId:
          type: string
        variableMapping:
          type: object
          additionalProperties:
            type: string
        defaults:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ValueModelContentSignalsItemsDefaults'
        segmentTableIds:
          type: array
          items:
            type: string
        description:
          type: string
        labels:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
      required:
      - eventName
      - label
      title: ValueModelContentSignalsItems
    ValueModelContentOverridesItemsAdditionalSignalsItems:
      type: object
      properties:
        eventName:
          type: string
        label:
          type: string
        formulaId:
          type: string
        variableMapping:
          type: object
          additionalProperties:
            type: string
        defaults:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ValueModelContentOverridesItemsAdditionalSignalsItemsDefaults'
        segmentTableIds:
          type: array
          items:
            type: string
        description:
          type: string
        labels:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
      required:
      - eventName
      - label
      title: ValueModelContentOverridesItemsAdditionalSignalsItems
    Pagination:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        total:
          type: integer
        hasMore:
          type: boolean
      required:
      - limit
      - offset
      - total
      - hasMore
      title: Pagination
    ValueModelSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        version:
          type: integer
        status:
          $ref: '#/components/schemas/ValueModelSummaryStatus'
        createdAt:
          type: string
          format: date-time
        activatedAt:
          type:
          - string
          - 'null'
          format: date-time
        archivedAt:
          type:
          - string
          - 'null'
          format: date-time
        effectiveFrom:
          type:
          - string
          - 'null'
          format: date-time
        effectiveTo:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - id
      - version
      - status
      - createdAt
      - activatedAt
      - archivedAt
      - effectiveFrom
      - effectiveTo
      title: ValueModelSummary
    ValueModelContentSignalsItemsDefaults:
      oneOf:
      - type: number
        format: double
      - type: string
      title: ValueModelContentSignalsItemsDefaults
    ValueModelContent:
      type: object
      properties:
        currency:
          type: string
        valueTypes:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentValueTypesItems'
        formulas:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentFormulasItems'
        signals:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentSignalsItems'
        segmentTables:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentSegmentTablesItems'
        overrides:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentOverridesItems'
      required:
      - currency
      - valueTypes
      - formulas
      - signals
      description: 'Full value model configuration: value types, formulas, signals, and overrides.'
      title: ValueModelContent
    ValueModelContentValueTypesItems:
      type: object
      properties:
        slug:
          type: string
        name:
          type: string
        unit:
          $ref: '#/components/schemas/ValueModelContentValueTypesItemsUnit'
        monetaryConversion:
          $ref: '#/components/schemas/ValueModelContentValueTypesItemsMonetaryConversion'
        description:
          type:
          - string
          - 'null'
        displayOrder:
          type:
          - integer
          - 'null'
        color:
          type:
          - string
          - 'null'
        icon:
          type:
          - string
          - 'null'
      required:
      - slug
      - name
      - unit
      title: ValueModelContentValueTypesItems
    ValueModelContentOverridesItemsScope:
      type: object
      properties:
        customerIds:
          type: array
          items:
            type: string
        customerGroupIds:
          type: array
          items:
            type: string
      title: ValueModelContentOverridesItemsScope
    ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsValue:
      oneOf:
      - type: number
        format: double
      - type: string
      - type: boolean
      title: ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsValue
    ValueModelContentFormulasItemsVariablesItemsType:
      type: string
      enum:
      - number
      - string
      - boolean
      - duration
      default: number
      title: ValueModelContentFormulasItemsVariablesItemsType
    ValueModelContentFormulasItems:
      type: object
      properties:
        id:
          type: string
        valueTypeSlug:
          type: string
        label:
          type: string
        description:
          type: string
        variables:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentFormulasItemsVariablesItems'
        expression:
          type: string
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/ValueModelContentFormulasItemsConditionsItems'
        defaultResult:
          $ref: '#/components/schemas/ValueModelContentFormulasItemsDefaultResult'
      required:
      - id
      - valueTypeSlug
      - label
      - variables
      - expression
      title: ValueModelContentFormulasItems
    ValueModelSummaryStatus:
      type: string
      enum:
      - draft
      - active
      - archived
      title: ValueModelSummaryStatus
    ValueModelContentOverridesItemsSignalOverrides:
      type: object
      properties:
        defaults:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ValueModelContentOverridesItemsSignalOverridesDefaults'
      title: ValueModelContentOverridesItemsSignalOverrides
    ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsResult:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsResultType'
        value:
          type: number
          format: double
        expression:
          type: string
      required:
      - type
      title: ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsResult
    ValueModelContentValueTypesItemsUnit:
      type: object
      title: ValueModelContentValueTypesItemsUnit
    ValueModelDetail:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Value model version ID.
        version:
          type: integer
          description: Monotonically increasing version number.
        content:
          $ref: '#/components/schemas/ValueModelContent'
        createdAt:
          type: string
          format: date-time
        activatedAt:
          type:
          - string
          - 'null'
          format: date-time
        effectiveFrom:
          type:
          - string
          - 'null'
          format: date-time
        effectiveTo:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - id
      - version
      - content
      - createdAt
      - activatedAt
      - effectiveFrom
      - effectiveTo
      title: ValueModelDetail
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
        details:
          type: string
      required:
      - error
      title: ErrorResponse
    ValueModelContentSegmentTablesItemsRowsItems:
      type: object
      properties:
        segmentValues:
          type: object
          additionalProperties:
            type: string
        variables:
          type: object
          additionalProperties:
            type: number
            format: double
      required:
      - segmentValues
      - variables
      title: ValueModelContentSegmentTablesItemsRowsItems
    ValueModelContentFormulasItemsVariablesItemsDerivedFrom:
      type: object
      properties:
        sourceField:
          type: string
        targetUnit:
          $ref: '#/components/schemas/ValueModelContentFormulasItemsVariablesItemsDerivedFromTargetUnit'
      required:
      - sourceField
      - targetUnit
      title: ValueModelContentFormulasItemsVariablesItemsDerivedFrom
    ValueModelContentFormulasItemsConditionsItems:
      type: object
      properties:
        field:
          type: string
        operator:
          $ref: '#/components/schemas/ValueModelContentFormulasItemsConditionsItemsOperator'
        value:
          $ref: '#/components/schemas/ValueModelContentFormulasItemsConditionsItemsValue'
        result:
          $ref: '#/components/schemas/ValueModelContentFormulasItemsConditionsItemsResult'
      required:
      - field
      - operator
      - value
      - result
      title: ValueModelContentFormulasItemsConditionsItems
    ValueModelContentFormulasItemsDefaultResultType:
      type: string
      enum:
      - constant
      - expression
      title: ValueModelContentFormulasItemsDefaultResultType
    ValueModelContentValueTypesItemsMonetaryConversionVariablesItems:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        default:
          type: number
          format: double
      required:
      - id
      - label
      - default
      title: ValueModelContentValueTypesItemsMonetaryConversionVariablesItems
    ValueModelContentFormulasItemsVariablesItems:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        type:
          $ref: '#/components/schemas/ValueModelContentFormulasItemsVariablesItemsType'
        description:
          type: string
        derivedFrom:
          $ref: '#/components/schemas/ValueModelContentFormulasItemsVariablesItemsDerivedFrom'
      required:
      - id
      - label
      title: ValueModelContentFormulasItemsVariablesItems
    ValueModelContentFormulasItemsConditionsItemsValue:
      oneOf:
      - type: number
        format: double
      - type: string
      - type: boolean
      title: ValueModelContentFormulasItemsConditionsItemsValue
    ValueModelContentFormulasItemsConditionsItemsOperator:
      type: string
      enum:
      - gte
      - gt
      - lt
      - lte
      - eq
      - neq
      - contains
      - eq_string
      - eq_bool
      title: ValueModelContentFormulasItemsConditionsItemsOperator
    ValueModelContentValueTypesItemsMonetaryConversionConditionsItems:
      type: object
      properties:
        field:
          type: string
        operator:
          $ref: '#/components/schemas/ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsOperator'
        value:
          $ref: '#/components/schemas/ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsValue'
        result:
          $ref: '#/components/schemas/ValueModelContentValueTypesItemsMonetaryConversionConditionsItemsResult'
      required:
      - field
      - operator
      - value
      - result
      title: ValueModelContentValueTypesItemsMonetaryConversionConditionsItems
    BackfillResponse:
      type: object
      properties:
        valueModelId:
          type: string
          format: uuid
        version:
          type: integer
      required:
      - valueModelId
      - version
      title: BackfillResponse
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer