openapi: 3.2.0
info:
  title: Kit for AI — API Playground Knowledge Bases API
  version: 1.0.0
  description: Welcome to the **Kit for AI** API playground.
  contact:
    name: Kit for AI
    url: https://kitforai.com
servers:
- url: https://kitforai.com
security:
- apiKey: []
tags:
- name: Knowledge Bases
paths:
  /api/v1/knowledge-bases:
    get:
      summary: List knowledge bases
      description: List the caller's knowledge bases, optionally filtered by `kind`.
      responses:
        '200':
          description: Knowledge bases
        '401':
          description: Missing or invalid API key
      tags:
      - Knowledge Bases
      operationId: getApiV1KnowledgeBases
      x-operation-id-source: derived
    post:
      summary: Create a knowledge base
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                kind:
                  type: string
                  enum:
                  - knowledge_base
                  default: knowledge_base
                description:
                  type: string
      responses:
        '201':
          description: Created
        '401':
          description: Missing or invalid API key
      tags:
      - Knowledge Bases
      operationId: postApiV1KnowledgeBases
      x-operation-id-source: derived
  /api/v1/knowledge-bases/{id}:
    get:
      summary: Read a knowledge base — all its docs as one Markdown document
      description: Returns the knowledge base's documents joined into a single `content` field — the whole category, ready for your model.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Knowledge base content
        '404':
          description: Not found
      tags:
      - Knowledge Bases
      operationId: getApiV1KnowledgeBasesById
      x-operation-id-source: derived
    delete:
      summary: Delete a knowledge base
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted
      tags:
      - Knowledge Bases
      operationId: deleteApiV1KnowledgeBasesById
      x-operation-id-source: derived
  /api/v1/knowledge-bases/{id}/documents:
    post:
      summary: Attach a converted document to a knowledge base
      description: Attach a conversion (from `POST /api/v1/convert`) to a knowledge base so it can be searched and cited. This is the second step of the ingest → attach flow.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - conversionId
              properties:
                conversionId:
                  type: string
                  description: The id returned by /api/v1/convert
      responses:
        '201':
          description: Attached
        '404':
          description: Knowledge base or document not found
      tags:
      - Knowledge Bases
      operationId: postApiV1KnowledgeBasesByIdDocuments
      x-operation-id-source: derived
  /api/v1/knowledge-bases/{id}/search:
    post:
      summary: Search a knowledge base
      description: Hybrid semantic + keyword search over a knowledge base's attached (non-excluded) documents. Returns the most relevant passages with their source document and a relevance score — the retrieval half of a RAG answer.
      operationId: searchKnowledgeBase
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  description: The question or search text
                k:
                  type: integer
                  default: 6
                  description: Max passages to return
      responses:
        '200':
          description: Ranked passages
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    document:
                      type: string
                      description: Source document name
                    content:
                      type: string
                      description: The matching passage
                    score:
                      type: number
                      description: Relevance score
                    documentId:
                      type:
                      - string
                      - 'null'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Knowledge base not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Knowledge Bases
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            endUserMessage:
              type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key