---
title: "Upload a document"
method: POST
path: "/knowledge-bases/{id}/documents"
tags: ["Knowledge Base"]
---

# Upload a document

`POST /knowledge-bases/{id}/documents`

## Request

- Base URL: `https://api.markcopy.ai/api/v1`
- URL: `https://api.markcopy.ai/api/v1/knowledge-bases/{id}/documents`
- Auth: API key in header `X-API-Key`

Upload a document to a knowledge base by providing a URL (web page or file) or raw text content. The document is processed asynchronously — the response confirms the document was accepted and queued for processing.

When uploading raw text that you've already extracted yourself (for example, from an internal wiki or an auth-gated page), you can optionally pass `sourceUrl` to record the original URL as the document's source for retrieval and citation.

**Supported file formats:** PDF, DOCX, DOC, TXT, CSV, XLSX, XLS, PPTX, PPT, MP3, WAV, OGG, M4A, WEBM, PNG, JPG, JPEG, GIF, WEBP

## Path parameters

- `id` string, required

## Request body

- object
  - `url` string, uri: URL of a web page or file to import. Mutually exclusive with `text`.
  - `text` string: Raw text content to store. Mutually exclusive with `url`.
  - `name` string: Human-readable name for the document. If omitted, a name is derived from the URL or a default is used.
  - `tags` string[]: Tags to associate with the document. Tags are created automatically if they don't exist.
  - `sourceUrl` string, uri: Optional. Original URL the text was extracted from, recorded as the document's source for retrieval and citation. Only valid alongside `text` — sending it with `url` returns `invalid_parameters`. Must be a valid HTTP or HTTPS URL.
  - `mimeType` 'text/markdown' | 'text/plain' | 'text/html' | 'application/json': Optional. Declares the format of the provided `text` (markdown, plain text, HTML, or JSON). Only valid alongside `text` — sending it with `url` returns `invalid_parameters` (the content type is detected automatically when fetching a URL).

## Response `201`

Document accepted and queued for processing.

- Document
  - `id` string: Unique document ID (prefixed with `doc_`).
  - `jobId` string: Job ID for tracking processing status (prefixed with `job_`).
  - `status` 'processing': The document processing status. Newly uploaded documents always start as `processing`.
  - `name` string: The document name.
  - `sourceType` 'url' | 'text': Whether the document was uploaded via URL or raw text.
  - `tags` string[]: Tags associated with the document.
  - `createdAt` string, date-time: Timestamp of when the document was created.
  - `sourceUrl` string, uri: Echo of the `sourceUrl` field when one was provided on a text upload. Absent otherwise.
  - `mimeType` 'text/markdown' | 'text/plain' | 'text/html' | 'application/json': Echo of the `mimeType` field when one was provided on a text upload. Absent otherwise.

## Other responses

- `400`: Invalid or missing parameters.
- `401`: API key is missing, invalid, or expired.
- `403`: Plan does not include API access or key lacks required scope.
- `404`: Knowledge base not found or not accessible with this API key.
- `409`: A document with the same URL already exists in this knowledge base.
- `422`: The file URL points to an unsupported format.
- `429`: Rate limit or monthly quota exceeded.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/markcopy/apis/mark-api.md) - [All operations](https://skmtc.dev/markcopy/apis/mark-api/llms.txt) - [OpenAPI document](https://skmtc.dev/markcopy/apis/mark-api/revisions/93323d1697ae?raw)