Charthop budget API

swagger: '2.0'
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access budget 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: budget
paths:
  /v1/org/{orgId}/budget:
    get:
      tags:
      - budget
      summary: Find budgets
      operationId: findBudgets
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: groupId
        in: query
        description: Group id to filter budgets by
        required: false
        type: string
      - name: date
        in: query
        description: Date to filter budgets as-of (defaults to today)
        required: false
        type: string
        format: date
      - name: fromId
        in: query
        description: Starting budget id for pagination
        required: false
        type: string
      - name: status
        in: query
        description: Status to filter budgets by (DRAFT, ACTIVE, or ARCHIVED)
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        type: integer
        format: int32
      - name: returnAccess
        in: query
        description: 'Return access information -- pass a list of actions to check, for example: create,update,delete'
        required: false
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsBudget'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
    post:
      tags:
      - budget
      summary: Create a new budget
      operationId: createBudget
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: Budget data to create
        required: true
        schema:
          $ref: '#/definitions/CreateBudget'
      responses:
        '201':
          description: created
          schema:
            $ref: '#/definitions/Budget'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: org not found
  /v1/org/{orgId}/budget/calculate-usage:
    get:
      tags:
      - budget
      summary: Calculate potential budget usage, for use while creating/setting budgets
      operationId: calculateBudgetUsage
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: groupIds
        in: query
        description: Group ids
        required: false
        type: string
      - name: costExpr
        in: query
        description: Cost expression to calculate
        required: false
        type: string
      - name: currency
        in: query
        description: Currency to calculate in
        required: false
        type: string
      - name: date
        in: query
        description: Date to retrieve as of
        required: false
        type: string
        format: date
      responses:
        '204':
          description: deleted
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/budget/{budgetId}:
    get:
      tags:
      - budget
      summary: Get a budget by id or slug
      operationId: getBudget
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: budgetId
        in: path
        description: Budget id or slug
        required: true
        type: string
      - name: date
        in: query
        description: Date to get budget data as-of (defaults to today)
        required: false
        type: string
        format: date
      responses:
        '200':
          description: ok
          schema:
            $ref: '#/definitions/Budget'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
    patch:
      tags:
      - budget
      summary: Update an existing budget
      operationId: updateBudget
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: budgetId
        in: path
        description: Budget id
        required: true
        type: string
      - name: date
        in: query
        description: Date to update budget on (defaults to today)
        required: false
        type: string
        format: date
      - name: body
        in: body
        description: Budget data to update
        required: true
        schema:
          $ref: '#/definitions/UpdateBudget'
      responses:
        '200':
          description: updated
          schema:
            $ref: '#/definitions/Budget'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    delete:
      tags:
      - budget
      summary: Delete a budget
      operationId: deleteBudget
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: budgetId
        in: path
        description: Budget id
        required: true
        type: string
      - name: date
        in: query
        description: Date to delete budget on (defaults to today)
        required: false
        type: string
        format: date
      responses:
        '204':
          description: deleted
        '400':
          description: invalid data
        '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
  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'
  Money:
    type: object
    required:
    - amount
    - currency
    properties:
      amount:
        type: number
      currency:
        type: string
      places:
        type: integer
        format: int32
  Budget:
    type: object
    required:
    - id
    - orgId
    - slug
    - startDate
    - endDate
    - sensitive
    - shareAccess
    - status
    - createDate
    properties:
      id:
        type: string
        description: globally unique id
        example: 588f7ee98f138b19220041a7
      orgId:
        type: string
        description: parent organization id
        example: 588f7ee98f138b19220041a7
      slug:
        type: string
        description: url-safe slug for the budget, auto-generated from label if not provided
      label:
        type: string
        description: human-readable label for the budget
      ownerPersonIds:
        type: array
        description: list of persons who own this budget
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      groupIds:
        type: array
        description: list of group IDs (e.g. department) for this budget
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      color:
        type: string
        description: color of budget
        pattern: ^#[a-f0-9]{6}$
      startDate:
        type: string
        format: date
        description: start date of the budget
      endDate:
        type: string
        format: date
        description: end date of the budget
      sensitive:
        type: string
        description: sensitivity level of budget
        enum:
        - GLOBAL
        - ORG
        - SENSITIVE
        - PERSONAL
        - MANAGER
        - HIGH
        - PRIVATE
      shareAccess:
        type: array
        description: users who are specifically granted permission to view or edit this budget
        items:
          $ref: '#/definitions/ShareAccess'
      costExpr:
        type: string
        description: calculation to compute cost
      status:
        type: string
        description: status of the budget
        enum:
        - DRAFT
        - ACTIVE
        - ARCHIVED
      usage:
        description: current amount used (calculated and time tracked field)
        $ref: '#/definitions/Money'
      amount:
        description: budget amount for the current date (time tracked field)
        $ref: '#/definitions/Money'
      createDate:
        type: string
        format: date
        description: when this budget starts existing in org history
      deleteDate:
        type: string
        format: date
        description: when this budget stops existing in org history (null if still active)
      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'
  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
  ShareAccess:
    type: object
    required:
    - access
    properties:
      access:
        type: string
        description: access permission level
        enum:
        - NONE
        - LIMITED_READ
        - LIMITED_WRITE
        - STANDARD_READ
        - STANDARD_WRITE
        - COMPENSATION_READ
        - FULL_READ
        - COMP_PLANNING_PARTICIPANT
        - COMPENSATION_WRITE
        - WRITE
        - COMPENSATION_OWNER
        - OWNER
      userId:
        type: string
        description: user id
        example: 5887a7718f138b6a2a0041a7
      groupId:
        type: string
        description: group id
        example: 5887a7718f138b6a2a0041a7
      fields:
        type: string
        description: fields
        example: name,image,title
  ResultsBudget:
    type: object
    required:
    - data
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/Budget'
      next:
        type: string
      access:
        type: array
        items:
          $ref: '#/definitions/ResultsAccess'
  UpdateBudget:
    type: object
    properties:
      slug:
        type: string
        description: url-safe slug for the budget, auto-generated from label if not provided
      label:
        type: string
        description: human-readable label for the budget
      ownerPersonIds:
        type: array
        description: list of persons who own this budget
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      groupIds:
        type: array
        description: list of group IDs (e.g. department) for this budget
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      color:
        type: string
        description: color of budget
        pattern: ^#[a-f0-9]{6}$
      startDate:
        type: string
        format: date
        description: start date of the budget
      endDate:
        type: string
        format: date
        description: end date of the budget
      sensitive:
        type: string
        description: sensitivity level of budget
        enum:
        - GLOBAL
        - ORG
        - SENSITIVE
        - PERSONAL
        - MANAGER
        - HIGH
        - PRIVATE
      shareAccess:
        type: array
        description: users who are specifically granted permission to view or edit this budget
        items:
          $ref: '#/definitions/ShareAccess'
      costExpr:
        type: string
        description: calculation to compute cost
      status:
        type: string
        description: status of the budget
        enum:
        - DRAFT
        - ACTIVE
        - ARCHIVED
      amount:
        description: budget amount for the current date (time tracked field)
        $ref: '#/definitions/Money'
  CreateBudget:
    type: object
    required:
    - startDate
    - endDate
    - sensitive
    properties:
      slug:
        type: string
        description: url-safe slug for the budget, auto-generated from label if not provided
      label:
        type: string
        description: human-readable label for the budget
      ownerPersonIds:
        type: array
        description: list of persons who own this budget
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      groupIds:
        type: array
        description: list of group IDs (e.g. department) for this budget
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      color:
        type: string
        description: color of budget
        pattern: ^#[a-f0-9]{6}$
      startDate:
        type: string
        format: date
        description: start date of the budget
      endDate:
        type: string
        format: date
        description: end date of the budget
      sensitive:
        type: string
        description: sensitivity level of budget
        enum:
        - GLOBAL
        - ORG
        - SENSITIVE
        - PERSONAL
        - MANAGER
        - HIGH
        - PRIVATE
      shareAccess:
        type: array
        description: users who are specifically granted permission to view or edit this budget
        items:
          $ref: '#/definitions/ShareAccess'
      costExpr:
        type: string
        description: calculation to compute cost
      status:
        type: string
        description: status of the budget
        enum:
        - DRAFT
        - ACTIVE
        - ARCHIVED
      amount:
        description: budget amount for the current date (time tracked field)
        $ref: '#/definitions/Money'