swagger: '2.0'
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access ai-credit-limit API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
host: localhost
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: ai-credit-limit
paths:
  /v1/ai-credit-limit:
    get:
      tags:
      - ai-credit-limit
      summary: Find AI credit limits, optionally filtered by customer
      operationId: findLimits
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: customerId
        in: query
        description: Customer identifier
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        type: integer
        format: int32
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsAiCreditLimit'
        '401':
          description: not authorized
        '403':
          description: permission denied
    post:
      tags:
      - ai-credit-limit
      summary: Create an AI credit limit
      operationId: createLimit
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: body
        in: body
        description: AI credit limit data to create
        required: true
        schema:
          $ref: '#/definitions/CreateAiCreditLimit'
      responses:
        '201':
          description: successful operation
          schema:
            $ref: '#/definitions/AiCreditLimit'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
  /v1/ai-credit-limit/by-customer-month:
    get:
      tags:
      - ai-credit-limit
      summary: Get an AI credit limit by customer and month
      operationId: getLimitByCustomerMonth
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: customerId
        in: query
        description: Customer identifier
        required: true
        type: string
      - name: date
        in: query
        description: Date within the month to look up
        required: true
        type: string
        format: date
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/AiCreditLimit'
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/ai-credit-limit/export-report:
    post:
      tags:
      - ai-credit-limit
      summary: Export the AI credit usage report as CSV (ChartHop staff only)
      operationId: exportReport
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: startMonth
        in: query
        description: First month to include (inclusive), in YYYY-MM format
        required: true
        type: string
      - name: endMonth
        in: query
        description: Last month to include (inclusive), in YYYY-MM format
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Process'
        '400':
          description: invalid date range
        '401':
          description: not authorized
        '403':
          description: permission denied
  /v1/ai-credit-limit/{id}:
    get:
      tags:
      - ai-credit-limit
      summary: Get an AI credit limit by id
      operationId: getLimit
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: id
        in: path
        description: AI credit limit identifier
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/AiCreditLimit'
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    patch:
      tags:
      - ai-credit-limit
      summary: Update an AI credit limit
      operationId: updateLimit
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: id
        in: path
        description: AI credit limit identifier
        required: true
        type: string
      - name: body
        in: body
        description: Fields to update
        required: true
        schema:
          $ref: '#/definitions/UpdateAiCreditLimit'
      responses:
        '204':
          description: successful operation
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    delete:
      tags:
      - ai-credit-limit
      summary: Delete an AI credit limit
      operationId: deleteLimit
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: id
        in: path
        description: AI credit limit identifier
        required: true
        type: string
      responses:
        '204':
          description: successful operation
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
definitions:
  AccessAction:
    type: object
    required:
    - action
    properties:
      action:
        type: string
      fields:
        type: array
        uniqueItems: true
        items:
          type: string
      types:
        type: array
        uniqueItems: true
        items:
          type: string
  Process:
    type: object
    required:
    - id
    - orgId
    - label
    - type
    - status
    - runUserId
    - createId
    - createAt
    - options
    properties:
      id:
        type: string
        description: globally unique id
        example: 588f7ee98f138b19220041a7
      orgId:
        type: string
        description: parent org id
        example: 588f7ee98f138b19220041a7
      label:
        type: string
        description: human-readable label that identifies this process
      type:
        type: string
        description: process type
      status:
        type: string
        description: current status of process
        enum:
        - PENDING
        - RUNNING
        - DONE
        - ERROR
      filePath:
        type: string
        description: data file path
      logPath:
        type: string
        description: data log path
      runUserId:
        type: string
        description: user id who is running the process
        example: 588f7ee98f138b19220041a7
      parentProcessId:
        type: string
        description: process id of parent process
        example: 588f7ee98f138b19220041a7
      createId:
        type: string
        description: created by user id (user who requested the process run)
        example: 588f7ee98f138b19220041a7
      createBehalfId:
        type: string
        description: created on behalf of user id
        example: 588f7ee98f138b19220041a7
      createAttribution:
        $ref: '#/definitions/Attribution'
      createAt:
        type: string
        description: created timestamp
        example: '2017-01-24T13:57:52Z'
      updateId:
        type: string
        description: last updated by user id
        example: 588f7ee98f138b19220041a7
      updateBehalfId:
        type: string
        description: last updated on behalf of user id
        example: 588f7ee98f138b19220041a7
      updateAttribution:
        $ref: '#/definitions/Attribution'
      updateAt:
        type: string
        description: last updated timestamp
        example: '2017-01-24T13:57:52Z'
      startAt:
        type: string
        description: started at timestamp
        example: '2017-01-24T13:57:52Z'
      endAt:
        type: string
        description: ended at timestamp
        example: '2017-01-24T13:57:52Z'
      message:
        type: string
        description: status or error message
      progress:
        type: number
        format: double
        description: percent progress so far
      internalError:
        type: string
        description: internal-only error message
      options:
        type: object
        description: options passed to the process
      results:
        type: object
        description: results summary for the process
        additionalProperties:
          type: object
      logDataList:
        type: array
        description: list of log data that occurred during running of this process
        items:
          $ref: '#/definitions/LogData'
      state:
        type: object
        description: process-specific state data
      summary:
        type: string
        description: human-readable, searchable summary of what this process did
      appId:
        type: string
        description: app id of the process
        example: 588f7ee98f138b19220041a7
      uuid:
        type: string
        description: unique ID of the process at queue time
        example: 84db3c6e-0877-4436-8af1-768c06b29586
  LogData:
    type: object
    required:
    - level
    - at
    - data
    properties:
      level:
        type: string
        enum:
        - INFO
        - WARN
        - ERROR
      at:
        type: string
        description: created timestamp
        example: '2017-01-24T13:57:52Z'
      message:
        type: string
      data:
        type: object
        additionalProperties:
          type: object
  ResultsAccess:
    type: object
    required:
    - allowed
    properties:
      ids:
        type: array
        uniqueItems: true
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      allowed:
        type: array
        uniqueItems: true
        items:
          $ref: '#/definitions/AccessAction'
  CreateAiCreditLimit:
    type: object
    required:
    - customerId
    - month
    - creditSoftLimit
    - overageRate
    properties:
      customerId:
        type: string
        description: customer id this limit applies to
        example: 588f7ee98f138b19220041a7
      month:
        type: string
        description: month this limit applies to
      creditSoftLimit:
        type: integer
        format: int64
        description: maximum number of credits included for the month
      overageRate:
        type: number
        description: overage rate in cents per credit beyond the soft limit
      creditHardLimit:
        type: integer
        format: int64
        description: hard cap on credit usage for the month; usage above this is rejected
  UpdateAiCreditLimit:
    type: object
    properties:
      creditSoftLimit:
        type: integer
        format: int64
        description: maximum number of credits included for the month
      overageRate:
        type: number
        description: overage rate in cents per credit beyond the soft limit
      creditHardLimit:
        type: integer
        format: int64
        description: hard cap on credit usage for the month; usage above this is rejected
  Attribution:
    type: object
    properties:
      principalUserId:
        type: string
        example: 588f7ee98f138b19220041a7
      agentUserIds:
        type: array
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      eventId:
        type: string
        example: 588f7ee98f138b19220041a7
      aiChatId:
        type: string
        example: 588f7ee98f138b19220041a7
      aiToolUseId:
        type: string
      channel:
        type: string
        enum:
        - WEB
        - MOBILE
        - SLACK
        - TEAMS
        - MCP
  AiCreditLimit:
    type: object
    required:
    - id
    - customerId
    - month
    - creditSoftLimit
    - overageRate
    properties:
      id:
        type: string
        description: globally unique id
        example: 588f7ee98f138b19220041a7
      customerId:
        type: string
        description: customer id this limit applies to
        example: 588f7ee98f138b19220041a7
      month:
        type: string
        description: month this limit applies to
      creditSoftLimit:
        type: integer
        format: int64
        description: maximum number of credits included for the month
      overageRate:
        type: number
        description: overage rate in cents per credit beyond the soft limit
      creditHardLimit:
        type: integer
        format: int64
        description: hard cap on credit usage for the month; usage above this is rejected
      createId:
        type: string
        description: created by user id
        example: 588f7ee98f138b19220041a7
      createBehalfId:
        type: string
        description: created on behalf of user id
        example: 588f7ee98f138b19220041a7
      createAttribution:
        $ref: '#/definitions/Attribution'
      createAt:
        type: string
        description: created timestamp
        example: '2017-01-24T13:57:52Z'
      updateId:
        type: string
        description: last updated by user id
        example: 588f7ee98f138b19220041a7
      updateBehalfId:
        type: string
        description: last updated on behalf of user id
        example: 588f7ee98f138b19220041a7
      updateAttribution:
        $ref: '#/definitions/Attribution'
      updateAt:
        type: string
        description: last updated timestamp
        example: '2017-01-24T13:57:52Z'
      deleteId:
        type: string
        description: deleted by user id
        example: 588f7ee98f138b19220041a7
      deleteBehalfId:
        type: string
        description: deleted on behalf of user id
        example: 588f7ee98f138b19220041a7
      deleteAttribution:
        $ref: '#/definitions/Attribution'
      deleteAt:
        type: string
        description: deleted timestamp
        example: '2017-01-24T13:57:52Z'
  ResultsAiCreditLimit:
    type: object
    required:
    - data
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/AiCreditLimit'
      next:
        type: string
      access:
        type: array
        items:
          $ref: '#/definitions/ResultsAccess'