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

# Upload Document

> Upload a UTF-8 text file into a knowledge base. The document is created with status `pending` while embedding runs in the background. Maximum file size is 130 KB.

Upload a UTF-8 text file into a knowledge base. This is a **multipart** request, not JSON.

Form fields:

* `name` (required)
* `description` (optional, 2000 characters or fewer)
* `file` (required, maximum 130 KB)

The document is created with `status: "pending"` while Akapulu Labs chunks and embeds it (usually about 15–20 seconds). Poll [list documents](/api-reference/knowledge-bases/documents-list) until `status` is `completed`.

Example:

```bash theme={null}
curl -X POST "https://akapulu.com/api/knowledge-bases/<KNOWLEDGE_BASE_ID>/documents/create/" \
  -H "Authorization: Bearer <YOUR_AKAPULU_API_KEY>" \
  -F "name=Product FAQ" \
  -F "description=Support answers" \
  -F "file=@./faq.txt"
```


## OpenAPI

````yaml openapi/akapulu.json POST /knowledge-bases/{corpus_id}/documents/create
openapi: 3.1.0
info:
  title: Akapulu Labs API
  version: 1.0.0
  description: Public Akapulu Labs API reference.
servers:
  - url: https://akapulu.com/api
security:
  - bearerAuth: []
paths:
  /knowledge-bases/{corpus_id}/documents/create:
    post:
      tags:
        - Knowledge bases
      summary: Upload document
      description: >-
        Upload a UTF-8 text file into a knowledge base. The document is created
        with status `pending` while embedding runs in the background. Maximum
        file size is 130 KB.
      parameters:
        - name: corpus_id
          in: path
          required: true
          description: Knowledge base ID.
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadDocumentRequest'
      responses:
        '200':
          description: Document accepted for embedding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadDocumentResponse'
              examples:
                success:
                  value:
                    status: pending
                    id: 44444444-5555-6666-7777-888888888888
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                default:
                  value:
                    error: file is required
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalid_key:
                  value:
                    error: Invalid API key
        '404':
          description: Knowledge base not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                default:
                  value:
                    error: Knowledge base not found
components:
  schemas:
    UploadDocumentRequest:
      type: object
      required:
        - name
        - file
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type: string
          maxLength: 2000
        file:
          type: string
          format: binary
          description: UTF-8 text file. Maximum 130 KB.
    UploadDocumentResponse:
      type: object
      required:
        - status
        - id
      properties:
        status:
          type: string
          enum:
            - pending
        id:
          type: string
          format: uuid
        redirect_url:
          type: string
          description: Dashboard path. Ignore for API clients.
    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````