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

# Upload File

> Creates a new knowledge base item by uploading a file.

Upload a file to create a knowledge base item that can be used to provide contextual information to your AI agents. Supported file formats include PDF, Word documents, text files, and more.

### Headers

**authorization** `string` *required*

Your API key for authentication.

**content-type** `string` *required*

Must be `multipart/form-data` for file uploads.

### Body Parameters (multipart/form-data)

**type** `string` *required* (default: file)

Must be `"file"` for file uploads.

**name** `string`

KB name (defaults to filename if not provided).

**description** `string`

Optional description of the knowledge base item content.

**file** `file` *required*

The file to upload and process into a knowledge base item.

### Response

**data** `object`

The created knowledge base item object.

**data.id** `string`

Unique identifier for the knowledge base item.

**data.name** `string`

Name of the knowledge base item.

**data.description** `string`

Description of the knowledge base item (if provided).

**data.status** `string`

Current status: `"PROCESSING"`, `"COMPLETED"`, `"FAILED"`, or `"DELETED"`.

**data.type** `string`

Will be `"FILE"` for file-based knowledge base items.

**data.created\_at** `string`

ISO timestamp of creation.

**data.updated\_at** `string`

ISO timestamp of last update.

**data.error\_message** `string`

Error message if status is `"FAILED"`.

**data.file** `object`

File information for the uploaded file.

**data.file.file\_name** `string`

Original filename.

**data.file.file\_size** `number`

File size in bytes.

**data.file.file\_type** `string`

MIME type of the file.

**errors** `null`

Will be `null` on successful creation.

```bash cURL theme={null}
curl -X POST https://api.bland.ai/v1/knowledge/learn \
  -H "authorization: Bearer YOUR_API_KEY" \
  -F "type=file" \
  -F "name=Company FAQs" \
  -F "description=Frequently asked questions and policies" \
  -F "file=@company_faqs.pdf"
```

```bash With Default Name theme={null}
curl -X POST https://api.bland.ai/v1/knowledge/learn \
  -H "authorization: Bearer YOUR_API_KEY" \
  -F "type=file" \
  -F "description=Product documentation" \
  -F "file=@product_docs.pdf"
```

```json Success Response theme={null}
{
  "data": {
    "id": "kb_01H8X9QK5R2N7P3M6Z8W4Y1V5T",
    "name": "Company FAQs",
    "description": "Frequently asked questions and policies",
    "status": "PROCESSING",
    "type": "FILE",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z",
    "file": {
      "file_name": "company_faqs.pdf",
      "file_size": 2048576,
      "file_type": "application/pdf"
    }
  },
  "errors": null
}
```

```json Error Response theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "KB_UPLOAD_LIMIT_EXCEEDED",
      "message": "You have reached your knowledge base upload limit"
    }
  ]
}
```

```json Rate Limited Response theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "KB_UPLOAD_RATE_LIMITED",
      "message": "Please wait 10 seconds between knowledge base uploads, or wait for your current upload to complete."
    }
  ]
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


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