swagger: '2.0'
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access category 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: category
paths:
  /v1/org/{orgId}/category:
    get:
      tags:
      - category
      summary: Return categories that are available to the organization
      operationId: getCategories
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: type
        in: query
        description: (Optional) Return only built-in or custom categories
        required: false
        type: string
      - name: unsorted
        in: query
        description: (Optional) Return categories array unsorted
        required: false
        type: boolean
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsCategory'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
    post:
      tags:
      - category
      summary: Create a category
      operationId: createCategory
      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: Category data to create
        required: true
        schema:
          $ref: '#/definitions/CreateCategory'
      responses:
        '201':
          description: category created
          schema:
            $ref: '#/definitions/Category'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
  /v1/org/{orgId}/category/{categoryId}:
    get:
      tags:
      - category
      summary: Return a particular category by id
      operationId: getCategory
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: categoryId
        in: path
        description: Category id
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/Category'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
    patch:
      tags:
      - category
      summary: Update an existing category
      operationId: updateCategory
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: categoryId
        in: path
        description: Category id
        required: true
        type: string
      - name: body
        in: body
        description: Category data to update
        required: true
        schema:
          $ref: '#/definitions/UpdateCategory'
      responses:
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
    delete:
      tags:
      - category
      summary: Delete a category
      operationId: deleteCategory
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: categoryId
        in: path
        description: Category id
        required: true
        type: string
      responses:
        '200':
          description: category deleted
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
definitions:
  Category:
    type: object
    required:
    - id
    - label
    properties:
      id:
        type: string
        description: globally unique id
        example: 588f7ee98f138b19220041a7
      orgId:
        type: string
        description: parent organization id (empty if built-in)
        example: 588f7ee98f138b19220041a7
      label:
        type: string
        description: human-readable label of category
        example: Performance
        minItems: 3
        maxItems: 80
      fieldIds:
        type: array
        description: set of field ids included in this category
        uniqueItems: true
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      nativeFields:
        type: array
        description: set of native field names included in this category
        uniqueItems: true
        items:
          type: string
      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'
  UpdateCategory:
    type: object
    properties:
      label:
        type: string
        description: human-readable label of category
        example: Performance
        minItems: 3
        maxItems: 80
      fieldIds:
        type: array
        description: set of field ids included in this category
        uniqueItems: true
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      nativeFields:
        type: array
        description: set of native field names included in this category
        uniqueItems: true
        items:
          type: string
  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
  CreateCategory:
    type: object
    required:
    - label
    properties:
      orgId:
        type: string
        description: parent organization id (empty if built-in)
        example: 588f7ee98f138b19220041a7
      label:
        type: string
        description: human-readable label of category
        example: Performance
        minItems: 3
        maxItems: 80
      fieldIds:
        type: array
        description: set of field ids included in this category
        uniqueItems: true
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      nativeFields:
        type: array
        description: set of native field names included in this category
        uniqueItems: true
        items:
          type: string
  ResultsCategory:
    type: object
    required:
    - data
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/Category'
      next:
        type: string