swagger: '2.0'
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access ai-hint 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-hint
paths:
  /v1/ai-hint:
    get:
      tags:
      - ai-hint
      summary: Find hints
      operationId: findHints
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: from
        in: query
        description: Identifier to paginate from
        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/ResultsAiHint'
        '401':
          description: not authorized
        '403':
          description: permission denied
    post:
      tags:
      - ai-hint
      summary: Create a hint
      operationId: createHint
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: body
        in: body
        description: Hint data to create
        required: true
        schema:
          $ref: '#/definitions/CreateAiHint'
      responses:
        '201':
          description: successful operation
          schema:
            $ref: '#/definitions/AiHint'
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
  /v1/ai-hint/generate:
    get:
      tags:
      - ai-hint
      summary: Generate placeholder hint content for a given tool and entity type
      operationId: generateHint
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: toolName
        in: query
        description: Tool name
        required: false
        type: string
      - name: entityType
        in: query
        description: Entity type
        required: false
        type: string
      responses:
        '200':
          description: successful operation
        '401':
          description: not authorized
        '403':
          description: permission denied
  /v1/ai-hint/{id}:
    get:
      tags:
      - ai-hint
      summary: Get a hint
      operationId: getHint
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: id
        in: path
        description: Hint identifier
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/AiHint'
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    patch:
      tags:
      - ai-hint
      summary: Update a hint
      operationId: updateHint
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: id
        in: path
        description: Hint identifier
        required: true
        type: string
      - name: body
        in: body
        description: Fields to update
        required: true
        schema:
          $ref: '#/definitions/UpdateAiHint'
      responses:
        '204':
          description: successful operation
        '400':
          description: invalid data
        '401':
          description: not authorized
        '403':
          description: permission denied
        '404':
          description: not found
    delete:
      tags:
      - ai-hint
      summary: Delete a hint
      operationId: deleteHint
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: id
        in: path
        description: Hint 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
  ResultsAiHint:
    type: object
    required:
    - data
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/AiHint'
      next:
        type: string
      access:
        type: array
        items:
          $ref: '#/definitions/ResultsAccess'
  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'
  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
  AiHint:
    type: object
    required:
    - id
    - name
    properties:
      id:
        type: string
        description: globally unique id
        example: 588f7ee98f138b19220041a7
      name:
        type: string
        description: unique name for this hint
      toolName:
        type: string
        description: tool name this hint applies to, e.g. Create, Update, Delete, DataExplorer
      entityType:
        type: string
        description: entity type this hint applies to, e.g. ACTION, FORM, REPORT
      keywords:
        type: array
        description: keywords that trigger this hint when matched in user messages
        items:
          type: string
      schema:
        type: string
        description: optional schema override; if null, auto-generated from the entity adapter's create class
      addHintIds:
        type: array
        description: additional hint ids to include when this hint is surfaced
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      content:
        type: string
        description: the hint content to provide to the AI
      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'
  CreateAiHint:
    type: object
    required:
    - name
    - content
    properties:
      name:
        type: string
        description: unique name for this hint
      toolName:
        type: string
        description: tool name this hint applies to, e.g. Create, Update, Delete, DataExplorer
      entityType:
        type: string
        description: entity type this hint applies to, e.g. ACTION, FORM, REPORT
      keywords:
        type: array
        description: keywords that trigger this hint when matched in user messages
        items:
          type: string
      schema:
        type: string
        description: optional schema override; if null, auto-generated from the entity adapter's create class
      addHintIds:
        type: array
        description: additional hint ids to include when this hint is surfaced
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      content:
        type: string
        description: the hint content to provide to the AI
  UpdateAiHint:
    type: object
    properties:
      name:
        type: string
        description: unique name for this hint
      toolName:
        type: string
        description: tool name this hint applies to, e.g. Create, Update, Delete, DataExplorer
      entityType:
        type: string
        description: entity type this hint applies to, e.g. ACTION, FORM, REPORT
      keywords:
        type: array
        description: keywords that trigger this hint when matched in user messages
        items:
          type: string
      schema:
        type: string
        description: optional schema override; if null, auto-generated from the entity adapter's create class
      addHintIds:
        type: array
        description: additional hint ids to include when this hint is surfaced
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      content:
        type: string
        description: the hint content to provide to the AI