---
title: "Upload a knowledge file"
method: POST
path: "/knowledge/files"
tags: ["Knowledge"]
---

# Upload a knowledge file

`POST /knowledge/files`

Uploads one file up to 10 MB and starts extraction and indexing. Supported formats are PDF, Word, Excel, PowerPoint, text, Markdown, HTML, CSV, and JSON. The returned document begins in processing status.

## Response `201`

The knowledge document was created and queued for processing.

- KnowledgeDocument
  - `character_count` integer, nullable, required
  - `created_at` string, date-time, required
  - `error_message` string, nullable, required
  - `file_name` string, nullable, required
  - `file_size_bytes` integer, nullable, required
  - `id` string, required
  - `is_enabled` boolean, required
  - `last_checked_at` string, date-time, nullable, required
  - `last_synced_at` string, date-time, nullable, required
  - `name` string, required
  - `next_refresh_at` string, date-time, nullable, required
  - `object` 'knowledge_document', required
  - `refresh_error_message` string, nullable, required
  - `refresh_interval_hours` 0 | 6 | 12 | 24 | 168 | null, nullable, required
  - `refresh_status` 'idle' | 'refreshing' | 'failed', required
  - `source_type` 'file' | 'url', required
  - `source_url` string, uri, nullable, required
  - `status` 'processing' | 'ready' | 'failed', required
  - `updated_at` string, date-time, required

## Other responses

- `400` — The request parameters are invalid.
- `401` — The Agent API key is missing, invalid, or revoked.
- `403` — The API key does not have the required permission.
- `409` — The operation conflicts with the resource's current state.
- `413` — The uploaded file exceeds the maximum allowed size.
- `415` — The request or uploaded file uses an unsupported media type.
- `429` — Too many requests. Retry after the number of seconds in Retry-After.
- `500` — The request failed unexpectedly.
- `503` — The API is temporarily unavailable. The request was not processed.

---

[API](https://skmtc.dev/heroui/apis/heroui-agents-api.md) · [All operations](https://skmtc.dev/heroui/apis/heroui-agents-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/heroui/heroui-agents-api/revisions/b8efcc339d1b/schema)