swagger: '2.0'
info:
  title: Kapa.ai
  description: API for Kapa.ai
  termsOfService: https://www.kapa.ai/terms
  version: v1
host: api.placeholder.com
schemes:
- https
basePath: /query/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
  Bearer:
    type: apiKey
    name: X-API-KEY
    in: header
security:
- Bearer: []
paths:
  /projects/{project_id}/analytics/activity/:
    get:
      operationId: projects_analytics_get_activity
      summary: Activity
      description: Returns aggregate as well as time series statistics for a project
      parameters:
      - name: token_types
        in: query
        description: 'Comma-separated list of token types to filter by. Available
          choices: SLACK, DISCORD, WIDGET, API, INTERNAL'
        required: false
        type: string
      - name: start_date_time
        in: query
        description: Start datetime for filtering in ISO 8601 format (e.g., 2020-01-01T00:00:00Z).
        required: false
        type: string
        format: date-time
      - name: end_date_time
        in: query
        description: End datetime for filtering in ISO 8601 format (e.g., 2020-01-01T23:59:59Z).
        required: false
        type: string
        format: date-time
      - name: aggregation_period
        in: query
        description: 'Period for aggregating data. Available choices: HOUR, DAY, WEEK,
          MONTH, YEAR'
        required: true
        type: string
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/ActivityResponse'
      tags:
      - Activity
    parameters:
    - name: project_id
      in: path
      required: true
      type: string
  /projects/{project_id}/analytics/source-retrieval/questions/:
    get:
      operationId: projects_analytics_source-retrieval_project_analytics_source_retrieval_questions
      summary: Questions
      description: Returns a list of questions answered through the sources of a project
      parameters:
      - name: page
        in: query
        description: Page number for pagination
        required: false
        type: integer
      - name: page_size
        in: query
        description: Number of items per page for pagination
        required: false
        type: integer
      - name: start_date_time
        in: query
        description: Start date for filtering, in ISO 8601 format (e.g., 2023-01-01T00:00:00Z).
        required: false
        type: string
        format: date-time
      - name: end_date_time
        in: query
        description: End date for filtering, in ISO 8601 format (e.g., 2023-01-31T23:59:59Z).
        required: false
        type: string
        format: date-time
      - name: url_path
        in: query
        description: Specific URL path to filter the results by.
        required: false
        type: string
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/QuestionAnswerURLStats'
      tags:
      - Source Analytics
    parameters:
    - name: project_id
      in: path
      required: true
      type: string
  /projects/{project_id}/analytics/source-retrieval/statistics/:
    get:
      operationId: projects_analytics_source-retrieval_project_analytics_source_retrieval_statistics
      summary: Statistics
      description: |-
        Returns a list of source used by kapa to answer questions together with a count
        of questions answered by them.
      parameters:
      - name: page
        in: query
        description: Page number for pagination
        required: false
        type: integer
      - name: page_size
        in: query
        description: Number of items per page for pagination
        required: false
        type: integer
      - name: start_date
        in: query
        description: Start date for the data retrieval period in ISO 8601 format (e.g.,
          2020-01-01T00:00:00Z).
        required: false
        type: string
        format: date-time
      - name: end_date
        in: query
        description: End date for the data retrieval period in ISO 8601 format (e.g.,
          2020-01-02T23:59:59Z).
        required: false
        type: string
        format: date-time
      - name: url_path
        in: query
        description: Specific URL path to filter the statistics by.
        required: false
        type: string
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/SourceRetrievalEvent'
      tags:
      - Source Analytics
    parameters:
    - name: project_id
      in: path
      required: true
      type: string
  /projects/{project_id}/threads/:
    get:
      operationId: projects_get_threads
      summary: Threads
      description: Returns all threads for a project
      parameters:
      - name: page
        in: query
        description: Page number for pagination
        required: false
        type: integer
      - name: page_size
        in: query
        description: Number of items per page for pagination
        required: false
        type: integer
      - name: reaction_filter
        in: query
        description: Filter by reaction type
        required: false
        type: string
        enum:
        - UPVOTE
        - DOWNVOTE
      - name: confidence_filter
        in: query
        description: Filter by confidence level
        required: false
        type: string
        enum:
        - UNCERTAIN
        - CERTAIN
      - name: status_tag_filter
        in: query
        description: Filter by status tag id
        required: false
        type: string
        format: uuid
      - name: start_date
        in: query
        description: Start date for filtering threads (YYYY-MM-DDTHH:MM:SSZ)
        required: false
        type: string
        format: date-time
      - name: end_date
        in: query
        description: End date for filtering threads (YYYY-MM-DDTHH:MM:SSZ)
        required: false
        type: string
        format: date-time
      - name: search_text
        in: query
        description: Text to search within threads
        required: false
        type: string
      - name: token_filter
        in: query
        description: Filter by specific token
        required: false
        type: string
      - name: sort_by_date
        in: query
        description: Sort the results in the specified order by date. If not specified
          results are ordered by date in descending order.
        required: false
        type: string
        enum:
        - asc
        - desc
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/Thread'
      tags:
      - Threads
    parameters:
    - name: project_id
      in: path
      required: true
      type: string
  /projects/{project_id}/threads/{id}/:
    get:
      operationId: projects_threads_read
      description: Views for a thread.
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/Thread'
      tags:
      - projects
    patch:
      operationId: projects_threads_partial_update
      description: Views for a thread.
      parameters:
      - name: data
        in: body
        required: true
        schema:
          $ref: '#/definitions/Thread'
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/Thread'
      tags:
      - projects
    parameters:
    - name: project_id
      in: path
      required: true
      type: string
    - name: id
      in: path
      required: true
      type: string
  /projects/{project_id}/threads/{id}/question-answers/:
    get:
      operationId: projects_threads_get_question_answers
      summary: Question Answers
      description: Returns all question answers for a single thread
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/QuestionAnswer'
      tags:
      - Threads
    parameters:
    - name: project_id
      in: path
      required: true
      type: string
    - name: id
      in: path
      required: true
      type: string
  /projects/{project_id}/threads/{id}/related-threads/:
    get:
      operationId: projects_threads_get_related_threads
      summary: Related Threads
      description: |-
        Returns the k semantially most related threads to
        the current thread out of n threads in the project's history.
      parameters: []
      responses:
        '200':
          description: ''
          schema:
            type: array
            items:
              $ref: '#/definitions/ThreadInfo'
      tags:
      - Threads
    parameters:
    - name: project_id
      in: path
      required: true
      type: string
    - name: id
      in: path
      required: true
      type: string
definitions:
  QuestionAnswerTimeSeriesByTokenType:
    required:
    - token_type
    - count
    - description
    type: object
    properties:
      token_type:
        title: Token type
        type: string
        enum:
        - SLACK
        - DISCORD
        - WIDGET
        - API
        - INTERNAL
      count:
        title: Count
        type: integer
      description:
        title: Description
        type: string
        minLength: 1
  QuestionAnswerTimeSeries:
    required:
    - period
    - total_count
    - total_uncertain_count
    - count_by_token_type
    type: object
    properties:
      period:
        title: Period
        type: string
        format: date-time
      total_count:
        title: Total count
        type: integer
      total_uncertain_count:
        title: Total uncertain count
        type: integer
      count_by_token_type:
        type: array
        items:
          $ref: '#/definitions/QuestionAnswerTimeSeriesByTokenType'
  AggregateStatistics:
    required:
    - total_questions
    - total_upvotes
    - total_downvotes
    - total_questions_uncertain
    - total_questions_uncertain_or_downvoted
    - total_unique_users
    type: object
    properties:
      total_questions:
        title: Total questions
        type: integer
      total_upvotes:
        title: Total upvotes
        type: integer
      total_downvotes:
        title: Total downvotes
        type: integer
      total_questions_uncertain:
        title: Total questions uncertain
        type: integer
      total_questions_uncertain_or_downvoted:
        title: Total questions uncertain or downvoted
        type: integer
      total_unique_users:
        title: Total unique users
        type: integer
  ActivityResponse:
    required:
    - time_series
    - aggregate_statistics
    type: object
    properties:
      time_series:
        type: array
        items:
          $ref: '#/definitions/QuestionAnswerTimeSeries'
      aggregate_statistics:
        $ref: '#/definitions/AggregateStatistics'
  QuestionAnswerURLStats:
    required:
    - question
    - answer
    - total_upvotes
    - total_downvotes
    - thread_id
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      question:
        title: Question
        type: string
        minLength: 1
      answer:
        title: Answer
        type: string
        minLength: 1
      created_at:
        title: Created at
        type: string
        format: date-time
      is_uncertain:
        title: Is uncertain
        type: boolean
        x-nullable: true
      total_upvotes:
        title: Total upvotes
        type: integer
      total_downvotes:
        title: Total downvotes
        type: integer
      thread_id:
        title: Thread id
        type: string
        minLength: 1
  SourceRetrievalEvent:
    required:
    - is_leaf
    - node_url
    - count
    - percentage_of_total
    type: object
    properties:
      is_leaf:
        title: Is leaf
        type: boolean
      node_url:
        title: Node url
        type: string
        minLength: 1
      count:
        title: Count
        type: integer
      percentage_of_total:
        title: Percentage of total
        type: string
        format: decimal
  Token:
    required:
    - token_type
    - description
    type: object
    properties:
      id:
        title: ID
        type: integer
        readOnly: true
      token_type:
        title: Token type
        type: string
        enum:
        - SLACK
        - DISCORD
        - WIDGET
        - API
        - INTERNAL
      description:
        title: Description
        type: string
        minLength: 1
      created_at:
        title: Created at
        type: string
        format: date-time
      total_number_of_question_answers:
        title: Total number of question answers
        type: integer
  Thread:
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      token:
        $ref: '#/definitions/Token'
      total_upvotes:
        title: Total upvotes
        type: integer
        readOnly: true
      total_downvotes:
        title: Total downvotes
        type: integer
        readOnly: true
      total_comments:
        title: Total comments
        type: integer
        readOnly: true
      total_thread_comments:
        title: Total thread comments
        type: integer
      end_user_id:
        title: End user id
        type: string
        format: uuid
        readOnly: true
      total_number_of_question_answers:
        title: Total number of question answers
        type: integer
      created_at:
        title: Created at
        type: string
        format: date-time
      initial_question:
        title: Initial question
        type: string
        readOnly: true
        minLength: 1
      is_uncertain:
        title: Is uncertain
        type: boolean
        readOnly: true
      status_tag:
        title: Status tag
        type: string
        readOnly: true
      status_tag_id:
        title: Status tag id
        type: string
        format: uuid
        x-nullable: true
  QuestionAnswer:
    required:
    - question
    - answer
    - total_upvotes
    - total_downvotes
    - total_comments
    type: object
    properties:
      id:
        title: Id
        type: string
        format: uuid
        readOnly: true
      question:
        title: Question
        type: string
        minLength: 1
      answer:
        title: Answer
        type: string
        minLength: 1
      created_at:
        title: Created at
        type: string
        format: date-time
      is_uncertain:
        title: Is uncertain
        type: boolean
        x-nullable: true
      relevant_sources:
        title: Relevant sources
        type: string
        readOnly: true
      total_upvotes:
        title: Total upvotes
        type: integer
      total_downvotes:
        title: Total downvotes
        type: integer
      total_comments:
        title: Total comments
        type: integer
      feedback:
        title: Feedback
        type: string
        readOnly: true
  ThreadInfo:
    required:
    - id
    type: object
    properties:
      id:
        title: Id
        type: string
        minLength: 1
      first_question:
        title: First question
        type: string
        minLength: 1
x-tagGroups:
- name: Analytics
  tags:
  - Activity
  - Common Questions
  - Source Analytics
  - Threads
