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

# Create knowledge base

> Creates a knowledge base from files, website pages or text. The source you pick decides how you send the request:

| Source | Content type | What to send |
|---|---|---|
| Files | multipart/form-data | One or more files in `files` |
| Website pages | application/json | The page URLs in `source.config.pages` |
| Text | application/json | The text in `source.config.content` |

<Note>
Processing runs in the background. Poll [Get knowledge base status](/api-reference/knowledge-bases/get-knowledge-base-status) until it's `ready` before an agent can use it.
</Note>




## OpenAPI

````yaml /api-reference/rest/openapi.yaml post /v1/knowledge-bases
openapi: 3.1.0
info:
  title: Zero Runtime REST API
  version: '1.0'
  description: >-
    Create, configure, version and deploy agents, and wire SIP telephony to
    them.
servers:
  - url: https://api.zeroruntime.ai
security:
  - token: []
tags:
  - name: Agents
  - name: Versions
  - name: Deployment
  - name: Phone numbers
  - name: Routing rules
  - name: Calls
  - name: Batch calls
  - name: Knowledge bases
  - name: Knowledge base folders
paths:
  /v1/knowledge-bases:
    post:
      tags:
        - Knowledge bases
      summary: Create knowledge base
      description: >
        Creates a knowledge base from files, website pages or text. The source
        you pick decides how you send the request:


        | Source | Content type | What to send |

        |---|---|---|

        | Files | multipart/form-data | One or more files in `files` |

        | Website pages | application/json | The page URLs in
        `source.config.pages` |

        | Text | application/json | The text in `source.config.content` |


        <Note>

        Processing runs in the background. Poll [Get knowledge base
        status](/api-reference/knowledge-bases/get-knowledge-base-status) until
        it's `ready` before an agent can use it.

        </Note>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/KnowledgeBaseWebsiteInput'
                - $ref: '#/components/schemas/KnowledgeBaseTextInput'
            examples:
              Website pages:
                summary: Website pages
                value:
                  name: 'Help center: billing'
                  source:
                    type: url
                    config:
                      pages:
                        - https://help.example.com/billing
                        - https://help.example.com/billing/refunds
                        - https://help.example.com/plans
                      autoRefresh:
                        enabled: true
                        intervalDays: 7
              Text:
                summary: Text
                value:
                  name: Return policy
                  source:
                    type: txt
                    config:
                      content: Items can be returned within 30 days of delivery...
          multipart/form-data:
            schema:
              type: object
              required:
                - files
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: >-
                    Up to 10 files of at most 30 MB each, as `pdf`, `txt`,
                    `csv`, `json`, `docx` or `md`. Each file becomes its own
                    knowledge base, named after the file.
                folderId:
                  type: string
                  description: >-
                    An existing folder to put the new knowledge bases in. Send
                    this or `folderName`, not both.
                  example: f4p9z
                folderName:
                  type: string
                  maxLength: 80
                  description: >-
                    Creates a top-level folder with this name and puts them in
                    it. Send this or `folderId`, not both.
                  example: Product docs
      responses:
        '201':
          description: >
            Created, with `status: "processing"`. Pages and text return the
            knowledge base. Files return `{ data: [ ... ] }`, one per file. A
            file that couldn't be stored comes back with `status: "failed"`,
            while the rest still go through.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/KnowledgeBase'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/KnowledgeBase'
              example:
                knowledgeId: w8d3k
                name: 'Help center: billing'
                type: url
                status: processing
                statusReason: null
                failureCode: null
                sizeInBytes: 0
                pageCount: null
                sectionCount: null
                charCount: null
                folderId: null
                currentVersion: 1
                latestVersion: 1
                createdAt: '2026-10-13T09:30:00.000Z'
                updatedAt: '2026-10-13T09:30:00.000Z'
        '400':
          description: >
            The request didn't validate. Nothing is created.


            A body that fails field validation returns `message: "Invalid
            payload"`, with every problem in `errors`. Other cases return just
            `message`:


            - `All pages must be on the same domain (help.example.com),
            "https://other.com/pricing" is not`

            - `None of the selected pages are valid URLs`

            - `No files uploaded`

            - `A maximum of 10 files can be uploaded at once`

            - `"notes.exe" is not a supported file type. Supported types: pdf,
            txt, csv, json, docx, md`

            - `"report.pdf" is not a valid pdf file`

            - `Send folderId or folderName, not both`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseValidationError'
              example:
                message: Invalid payload
                errors:
                  formErrors: []
                  fieldErrors:
                    name:
                      - String must contain at least 1 character(s)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: The `folderId` isn't on your account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              example:
                message: Folder not found
        '409':
          description: >-
            `folderName` matches an existing top-level folder. Send its
            `folderId` instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              example:
                message: >-
                  A folder named "Product docs" already exists, send its
                  folderId instead
        '413':
          description: A file is over 30 MB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              example:
                message: File exceeds the 30MB limit
        '422':
          description: The website can't be reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              example:
                message: URL is unreachable
components:
  schemas:
    KnowledgeBaseWebsiteInput:
      title: Website pages
      type: object
      required:
        - name
        - source
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: A name for the knowledge base.
        source:
          type: object
          required:
            - type
            - config
          properties:
            type:
              type: string
              enum:
                - url
            config:
              type: object
              required:
                - pages
              properties:
                pages:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    format: uri
                  description: >-
                    Up to 100 `http` or `https` URLs, all on one domain. Only
                    these pages are parsed, and links on them aren't followed.
                    Find a site's pages with [Discover
                    pages](/api-reference/knowledge-bases/discover-pages).
                autoRefresh:
                  type: object
                  description: >-
                    Re-parses the same pages on a schedule. Each run creates a
                    new version.
                  properties:
                    enabled:
                      type: boolean
                      default: false
                    intervalDays:
                      type: integer
                      minimum: 1
                      maximum: 365
                      default: 7
                      description: Days between runs.
        folderId:
          type: string
          description: >-
            An existing folder to put it in. Send this or `folderName`, not
            both.
        folderName:
          type: string
          maxLength: 80
          description: >-
            Creates a top-level folder with this name and puts it there. Send
            this or `folderId`, not both.
    KnowledgeBaseTextInput:
      title: Text
      type: object
      required:
        - name
        - source
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          description: A name for the knowledge base.
        source:
          type: object
          required:
            - type
            - config
          properties:
            type:
              type: string
              enum:
                - txt
            config:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
                  minLength: 1
                  maxLength: 5000000
                  description: The text itself.
        folderId:
          type: string
          description: >-
            An existing folder to put it in. Send this or `folderName`, not
            both.
        folderName:
          type: string
          maxLength: 80
          description: >-
            Creates a top-level folder with this name and puts it there. Send
            this or `folderId`, not both.
    KnowledgeBase:
      type: object
      description: Status and size fields describe the current version.
      properties:
        knowledgeId:
          type: string
          description: 5 characters
          lowercase letters and digits. Attach it to an agent with `knowledgeBaseIds`.: null
          example: k7x2m
        name:
          type: string
          example: pricing.pdf
        type:
          type: string
          enum:
            - pdf
            - txt
            - csv
            - json
            - docx
            - md
            - url
        status:
          $ref: '#/components/schemas/KnowledgeBaseStatus'
        statusReason:
          type:
            - string
            - 'null'
          description: Why processing failed.
        failureCode:
          type:
            - string
            - 'null'
          description: For example `upload_failed` or `job_not_scheduled`.
        sizeInBytes:
          type:
            - integer
            - 'null'
          description: '`0` for website knowledge bases.'
        pageCount:
          type:
            - integer
            - 'null'
        sectionCount:
          type:
            - integer
            - 'null'
        charCount:
          type:
            - integer
            - 'null'
        folderId:
          type:
            - string
            - 'null'
          description: '`null` when it''s at the top level.'
        currentVersion:
          type: integer
          description: The version agents read from.
        latestVersion:
          type: integer
          description: The newest version. It may still be processing
          or may have failed.: null
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    KnowledgeBaseValidationError:
      type: object
      properties:
        message:
          type: string
          example: Invalid payload
        errors:
          type: object
          description: Every problem found, grouped by field.
          properties:
            formErrors:
              type: array
              items:
                type: string
            fieldErrors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
    Message:
      type: object
      properties:
        message:
          type: string
    KnowledgeBaseStatus:
      type: string
      enum:
        - processing
        - ready
        - failed
      description: |
        - `processing`: being parsed and indexed. Not available to agents yet.
        - `ready`: indexed and available to agents.
        - `failed`: processing stopped. `statusReason` says why.
    Error:
      type: object
      properties:
        error:
          type: string
  responses:
    Unauthorized:
      description: Missing or invalid `Authorization` header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    token:
      type: apiKey
      in: header
      name: Authorization
      description: Your API token, sent raw (no `Bearer` prefix).
      x-default: <auth-token>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.