> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneinbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a knowledge base source — file, URL, or inline text (auto-creates the KB)



## OpenAPI

````yaml /openapi/openapi.yaml post /v1/knowledge-bases/sources
openapi: 3.1.0
info:
  title: OneInbox API
  version: 1.0.0
servers:
  - url: https://api-tokyo.oneinbox.ai
    description: Production (Tokyo ap-northeast-1)
security: []
tags:
  - name: health
  - name: integrations
  - name: llm-models
  - name: tools
  - name: knowledge-bases
  - name: voices
  - name: webhooks
  - name: agents
  - name: phone-numbers
  - name: calls
  - name: workspace
  - name: usage
  - name: audit-events
paths:
  /v1/knowledge-bases/sources:
    post:
      tags:
        - knowledge-bases
      summary: >-
        Add a knowledge base source — file, URL, or inline text (auto-creates
        the KB)
      operationId: add_kb_source_autocreate_v1_knowledge_bases_sources_post
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              oneOf:
                - $ref: '#/components/schemas/AddUrlSourceBody'
                - $ref: '#/components/schemas/AddTextSourceBody'
                - $ref: '#/components/schemas/AddFileSourceBody'
              discriminator:
                propertyName: type
                mapping:
                  url:
                    $ref: '#/components/schemas/AddUrlSourceBody'
                  text:
                    $ref: '#/components/schemas/AddTextSourceBody'
                  file:
                    $ref: '#/components/schemas/AddFileSourceBody'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KBSourceCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - API Key: []
components:
  schemas:
    AddUrlSourceBody:
      title: URL
      type: object
      required:
        - type
        - source
      properties:
        type:
          type: string
          enum:
            - url
          example: url
        source:
          type: string
          description: >-
            Publicly accessible URL to crawl. OneInbox reads all linked pages
            automatically.
          example: https://docs.yourproduct.com/faq
    AddTextSourceBody:
      title: Inline Text
      type: object
      required:
        - type
        - source
      properties:
        type:
          type: string
          enum:
            - text
          example: text
        source:
          type: string
          description: Raw text content to index directly — no file upload needed.
          example: Our return policy is 30 days, no questions asked.
        metadata:
          type: object
          description: Optional metadata stored with this source (e.g. title, tags)
          properties:
            title:
              type: string
              example: Return Policy
    AddFileSourceBody:
      title: File Upload
      type: object
      required:
        - file
      description: >
        Upload a file to index. Do **not** include a `type` field — the server
        infers the type from the file content.


        Supported formats: PDF, DOCX, XLSX, TXT, MD
      properties:
        file:
          type: string
          format: binary
          description: File bytes. Supported formats — PDF, DOCX, XLSX, TXT, MD.
    KBSourceCreateResponse:
      properties:
        source:
          $ref: '#/components/schemas/KBSourceResponse'
        job:
          $ref: '#/components/schemas/KBJobResponse'
        message:
          type: string
          title: Message
          default: >-
            Source accepted. Ingestion is running in the background. Poll GET
            /v1/knowledge-bases/{kb_id}/jobs/{job_id} for status.
      type: object
      required:
        - source
        - job
      title: KBSourceCreateResponse
      description: >-
        201 response for POST /sources — returns the source and a job_id to
        poll.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    KBSourceResponse:
      properties:
        source_id:
          type: string
          title: Source Id
        kb_id:
          type: string
          title: Kb Id
        type:
          type: string
          title: Type
        source:
          type: string
          title: Source
        chunk_count:
          type: integer
          title: Chunk Count
        status:
          type: string
          title: Status
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
        file_name:
          anyOf:
            - type: string
            - type: 'null'
          title: File Name
        mime_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Mime Type
        file_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: File Size
        token_count:
          type: integer
          title: Token Count
          default: 0
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - source_id
        - kb_id
        - type
        - source
        - chunk_count
        - status
        - error_message
        - created_at
      title: KBSourceResponse
    KBJobResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        kb_id:
          type: string
          title: Kb Id
        source_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Id
        type:
          type: string
          title: Type
        status:
          type: string
          title: Status
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
        payload:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Payload
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - job_id
        - kb_id
        - type
        - status
        - error_message
        - payload
        - started_at
        - completed_at
        - created_at
      title: KBJobResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    API Key:
      type: http
      description: >-
        Your **API key** sent as a Bearer credential — `Authorization: Bearer
        <api_key>`, where `<api_key>` starts with `oi_sk_` (create one via `POST
        /v1/api-keys`). Although the field is labelled 'token', paste your API
        key here. A dashboard JWT is also accepted on this header for the same
        endpoints.
      scheme: bearer

````