JobMojito Knowledge base API

openapi: 3.2.0
info:
  title: JobMojito Knowledge base API
  version: 1.0.0
  description: Public API for JobMojito, served by Supabase Edge Functions. Authenticate with a Supabase JWT access token via the Authorization header.
servers:
- url: https://cool.jobmojito.com/functions/v1
  description: Production
tags:
- name: Knowledge base
  description: Upload documents used to generate knowledge-base interviews.
paths:
  /knowledge-base-document-upload:
    post:
      tags:
      - Knowledge base
      summary: Upload a knowledge base document
      description: Uploads a document to a knowledge base store and queues it for processing. Accepts the file either as multipart/form-data (binary `file`) or as application/json (base64 `file`). Use `interview_ids` to limit the document to chosen interviews.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/KnowledgeBaseDocumentUploadMultipart'
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeBaseDocumentUploadJson'
      responses:
        '200':
          description: The document was uploaded and queued for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseDocumentUploadResponse'
        '403':
          description: Your token is not allowed to use this endpoint (it is not a merchant, merchant owner or admin token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error, including an `interview_ids` entry that is not an interview of this company on this knowledge base.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error (includes a missing/invalid file or store).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: upload_knowledge_base_document
  /knowledge-base-document-list:
    get:
      tags:
      - Knowledge base
      summary: List knowledge base documents and their interview limits
      description: Paginated list of your company's knowledge base documents (uploaded files, URLs and written documents), each with the interviews it is limited to. Pass `knowledge_base_id` to read one document's limit. Capped at 1000 records per page.
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          format: uuid
          description: 'A document id (the knowledge_base_id of a listed document, not a store id): read this one document. Answers 404 if your token cannot see it, including when it is another company''s. `merchant_id` and `offset` are ignored.'
          example: 44444444-4444-4444-8444-444444444444
        required: false
        name: knowledge_base_id
        in: query
      - schema:
          type: string
          format: uuid
          description: Only the documents of this knowledge base store. Omit for every store of the company.
          example: d9d6f121-1230-48fd-b3a7-8b5a1e8db052
        required: false
        name: knowledge_base_store_id
        in: query
      - schema:
          type: string
          format: uuid
          description: Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
          example: 28106cba-1c27-4e53-b149-32113e5e8e31
        required: false
        name: merchant_id
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 50
          description: Maximum number of records to return (1–1000).
          example: 50
        required: false
        name: limit
        in: query
      - schema:
          type: integer
          nullable: true
          minimum: 0
          default: 0
          description: Number of records to skip from the start of the result set.
          example: 0
        required: false
        name: offset
        in: query
      responses:
        '200':
          description: A page of documents with pagination metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseDocumentListResponse'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Your token is not allowed to use this endpoint (it is not a merchant, merchant owner or admin token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The document named in `knowledge_base_id` does not exist or your token cannot see it. Another company's document answers the same way.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: list_knowledge_base_documents
  /knowledge-base-document-set-interviews:
    post:
      tags:
      - Knowledge base
      summary: Change which interviews can use a document
      description: 'Replaces the interview limit of an existing knowledge base document: a list of interviews, an empty list for none, or null for every interview on the knowledge base. Takes effect for the next live session and the next generation; the document is not processed again and costs no credits.'
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeBaseDocumentSetInterviewsRequest'
      responses:
        '200':
          description: The limit was replaced. The response reports the new one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseDocumentSetInterviewsResponse'
        '401':
          description: Missing or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Your token is not allowed to use this endpoint (it is not a merchant, merchant owner or admin token).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No document with this id that your token can change. Another company's document answers the same way, and so does a per-interview text, which is not a document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error naming the field, including an `interview_ids` entry that is not an interview of this company on this knowledge base. Nothing is changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: set_knowledge_base_document_interviews
  /knowledge-base-store-list:
    get:
      tags:
      - Knowledge base
      summary: List knowledge base stores
      description: 'The company''s knowledge base stores, with how many documents each holds: the knowledge_base_store_id an interview draws on and a document is uploaded to. Owners, recruiters and admins; a hiring manager gets an empty list. Read only.'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: string
          format: uuid
          description: Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
          example: 28106cba-1c27-4e53-b149-32113e5e8e31
        required: false
        name: merchant_id
        in: query
      responses:
        '200':
          description: The stores.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseStoreList'
        '401':
          description: Missing, expired or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not company staff, or another company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error; the message (and name, when given) says which field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: list_knowledge_base_stores
  /knowledge-base-store-save:
    post:
      tags:
      - Knowledge base
      summary: Create or change a knowledge base store
      description: Creates a knowledge base store, or renames one or changes whether the AI uses only its documents (strict). Documents are added with knowledge-base-document-upload. Changing strict changes how every interview on the store answers. Owners, recruiters and admins; nothing is sent to candidates.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeBaseStoreSave'
      responses:
        '200':
          description: The store after the call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseStoreSaveResult'
        '401':
          description: Missing, expired or invalid access token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: A hiring manager (read only), not company staff, or another company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No store with this id in this company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: A new store without a name, a name of more than 200 characters, or nothing to change (name says which field).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: save_knowledge_base_store
components:
  schemas:
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: Total matching records across all pages.
          example: 137
        limit:
          type: integer
          description: Page size used for this response.
          example: 50
        offset:
          type: integer
          description: Offset used for this response.
          example: 0
        has_more:
          type: boolean
          description: True when more records exist beyond this page (offset + returned < total).
          example: true
      required:
      - total
      - limit
      - offset
      - has_more
    KnowledgeBaseDocumentUploadJson:
      type: object
      properties:
        knowledge_base_store_id:
          type: string
          minLength: 1
          format: uuid
          description: The knowledge base store to add the document to.
          example: d9d6f121-1230-48fd-b3a7-8b5a1e8db052
        name:
          type: string
          minLength: 1
          description: 'Document name with its extension, which decides how the file is read: .doc, .docx, .rtf, .odt, .pdf, .pages or .pptx; any other is refused with 422 (name).'
        merchant_id:
          type: string
          description: Override merchant id (admin / sub-merchant only).
        interview_ids:
          type: array
          nullable: true
          items:
            type: string
            format: uuid
          description: 'The interviews that may use this document, in the live session and when generating questions. An interview uses this knowledge base once its knowledge_base_store_id is set (job-interview-create / job-interview-update): link it first. Omit it or send null to use the document in every interview on the knowledge base. An empty list limits it to no interview. Each interview must belong to the same company and use this knowledge base. With multipart/form-data, repeat the field or send one JSON array such as `["<id>"]`, and write an empty list as `[]`.'
          example:
          - de300000-0000-4000-8001-000000000007
        file:
          type: string
          minLength: 1
          description: The document file, base64-encoded.
      required:
      - knowledge_base_store_id
      - name
      - file
    KnowledgeBaseDocumentUploadResponse:
      type: object
      properties:
        knowledge_base_id:
          type: string
          description: Id of the created knowledge_base record.
        limit_to_interviews:
          type: boolean
          description: True when the document is limited to the interviews in `interview_ids`. False when every interview on the knowledge base can use it.
        interview_ids:
          type: array
          items:
            type: string
          description: The interviews this document is limited to. Present only when `limit_to_interviews` is true; an empty list means no interview can use it.
      required:
      - knowledge_base_id
      - limit_to_interviews
    KnowledgeBaseStoreList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeBaseStore'
          description: The stores, by name.
      required:
      - data
    KnowledgeBaseDocumentListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              knowledge_base_id:
                type: string
                description: Document id, for knowledge-base-document-set-interviews.
              knowledge_base_store_id:
                type: string
                nullable: true
                description: The knowledge base store the document belongs to.
              merchant_id:
                type: string
                nullable: true
                description: The company that owns the document.
              name:
                type: string
                nullable: true
                description: Document name.
              type:
                type: string
                description: 'Where it came from: `file`, `url` or `markdown`.'
              status:
                type: string
                nullable: true
                description: Lifecycle status.
              processing_status:
                type: string
                nullable: true
                description: Parsing progress of a file or URL. Written documents have none.
              created_at:
                type: string
                nullable: true
                description: Creation timestamp (ISO 8601).
              limit_to_interviews:
                type: boolean
                description: True when the document is limited to the interviews in `interview_ids`. False when every interview on the knowledge base can use it.
              interview_ids:
                type: array
                items:
                  type: string
                description: The interviews this document is limited to. Present only when `limit_to_interviews` is true; an empty list means no interview can use it.
            required:
            - knowledge_base_id
            - knowledge_base_store_id
            - merchant_id
            - name
            - type
            - status
            - processing_status
            - created_at
            - limit_to_interviews
          description: The documents for this page with the interview limit of each, newest first.
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - data
      - pagination
    KnowledgeBaseStoreSave:
      type: object
      properties:
        merchant_id:
          type: string
          format: uuid
          description: Optional company to act on. Admins and sub-merchant operators only; other callers always use their token's company.
        knowledge_base_store_id:
          type: string
          format: uuid
          description: 'The store to change (from knowledge-base-store-list). Left out: a new store is created.'
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: Name of the store, 1 to 200 characters. Required for a new store; left out on a change, it stays.
        strict:
          type: boolean
          description: 'true (the default for a new store): the AI uses only these documents. false: it uses them alongside its general knowledge. Left out on a change, it stays.'
    KnowledgeBaseDocumentSetInterviewsRequest:
      type: object
      properties:
        knowledge_base_id:
          type: string
          minLength: 1
          format: uuid
          description: 'The document to change: `knowledge_base_id` from the upload response or from knowledge-base-document-list.'
          example: 44444444-4444-4444-8444-444444444444
        interview_ids:
          type: array
          description: 'The whole new list, which replaces the old one. An interview uses this knowledge base once its knowledge_base_store_id is set (job-interview-create / job-interview-update): link it first. A list limits the document to those interviews, an empty list to no interview, and null opens it to every interview on the knowledge base. Required, so that leaving it out can never open a document. Each interview must belong to the same company as the document and use the same knowledge base.'
          nullable: true
          items:
            type: string
            format: uuid
          example:
          - de300000-0000-4000-8001-000000000007
      required:
      - knowledge_base_id
      - interview_ids
    KnowledgeBaseDocumentSetInterviewsResponse:
      type: object
      properties:
        knowledge_base_id:
          type: string
          description: The document that was changed.
        limit_to_interviews:
          type: boolean
          description: True when the document is limited to the interviews in `interview_ids`. False when every interview on the knowledge base can use it.
        interview_ids:
          type: array
          items:
            type: string
          description: The interviews this document is limited to. Present only when `limit_to_interviews` is true; an empty list means no interview can use it.
      required:
      - knowledge_base_id
      - limit_to_interviews
    Error:
      type: object
      properties:
        error:
          type: string
          example: Field is required.
        name:
          type: string
          example: interview_result_id
      required:
      - error
    KnowledgeBaseStoreSaveResult:
      allOf:
      - $ref: '#/components/schemas/KnowledgeBaseStore'
      - type: object
        properties:
          created:
            type: boolean
            description: True when a new store was created.
        required:
        - created
    KnowledgeBaseDocumentUploadMultipart:
      type: object
      properties:
        knowledge_base_store_id:
          type: string
          minLength: 1
          format: uuid
          description: The knowledge base store to add the document to.
          example: d9d6f121-1230-48fd-b3a7-8b5a1e8db052
        name:
          type: string
          description: 'Document name with its extension, which decides how the file is read: .doc, .docx, .rtf, .odt, .pdf, .pages or .pptx; any other is refused with 422 (name). Falls back to the uploaded file name for multipart.'
        merchant_id:
          type: string
          description: Override merchant id (admin / sub-merchant only).
        interview_ids:
          type: array
          nullable: true
          items:
            type: string
            format: uuid
          description: 'The interviews that may use this document, in the live session and when generating questions. An interview uses this knowledge base once its knowledge_base_store_id is set (job-interview-create / job-interview-update): link it first. Omit it or send null to use the document in every interview on the knowledge base. An empty list limits it to no interview. Each interview must belong to the same company and use this knowledge base. With multipart/form-data, repeat the field or send one JSON array such as `["<id>"]`, and write an empty list as `[]`.'
          example:
          - de300000-0000-4000-8001-000000000007
        file:
          type: string
          description: The document file (binary).
          format: binary
      required:
      - knowledge_base_store_id
      - file
    KnowledgeBaseStore:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: 'The store: knowledge_base_store_id of create_interview, upload_knowledge_base_document and list_knowledge_base_documents.'
        name:
          type: string
          description: Name of the store.
        strict:
          type: boolean
          description: 'true: the AI uses only these documents; false: it uses them alongside its general knowledge.'
        document_count:
          type: integer
          description: How many documents the store holds.
      required:
      - id
      - name
      - strict
      - document_count
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Supabase JWT — `Authorization: Bearer <token>`.'