The Mark AI API lets you programmatically add documents to your Knowledge Bases. You can upload a single document, send a batch of up to 20, and track processing progress. This article covers all three operations. For the full endpoint reference, see the API documentation.
Prerequisites
1. A Mark AI workspace with an active subscription that includes API access.
2. An API key generated from your workspace settings. The full key is only shown once at creation: store it securely.
3. The external ID of your target Knowledge Base (prefixed with kb_). Retrieve it via GET /knowledge-bases or from the app.
All requests use the X-API-Key header and target {API_BASE_URL}/api/v1. Rate limiting is enforced server-side on all endpoints.
Upload a single document
POST /knowledge-bases/{id}/documents
Provide exactly one of url or text (they are mutually exclusive). The name (max 255 chars) and tags (max 20 per document) fields are optional. Tags are auto-created if they don't exist yet. Text content must not exceed 10 MB.
curl -X POST "{API_BASE_URL}/api/v1/knowledge-bases/kb_a8f3x9k2m4pQ/documents" \ -H "X-API-Key: <your API key>" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/report.pdf", "name": "Q4 2025 Report", "tags": ["reports", "quarterly"] }'
Response (201 Created):
{ "id": "doc_b7n4p1q8r3wX", "status": "processing", "name": "Q4 2025 Report", "sourceType": "url", "tags": ["reports", "quarterly"], "createdAt": "2026-03-18T10:30:00.000Z" }
Documents are processed asynchronously. See the "Track progress" section below.
Upload multiple documents (batch)
POST /knowledge-bases/{id}/documents/batch
Send an array of 1 to 20 documents. Each item follows the same structure as a single upload. Items are processed sequentially: one item's failure does not abort the rest.
curl -X POST "{API_BASE_URL}/api/v1/knowledge-bases/kb_a8f3x9k2m4pQ/documents/batch" \ -H "X-API-Key: <your API key>" \ -H "Content-Type: application/json" \ -d '{ "documents": [ { "url": "https://example.com/guide.pdf", "tags": ["product"] }, { "text": "FAQ content...", "name": "FAQ", "tags": ["faq"] } ] }'Response (200 OK):
{ "batchId": "batch_x9k2m4pQb7n4", "results": [ { "status": "success", "document": { "id": "doc_p1q8r3wXa8f3", "status": "processing" } }, { "status": "error", "error": { "code": "duplicate_document", "message": "..." } } ], "summary": { "total": 2, "succeeded": 1, "failed": 1 } }
Important: the HTTP status is always 200, even when individual items fail. Always inspect each result's status field.
Track progress
Poll a single job
GET /jobs/{jobId} returns the job status: queued, processing, completed, or failed. On success, result.documentId holds the final document ID. On failure, result.errorCode and result.errorMessage describe the cause.
Poll a batch
GET /jobs/batches/{batchId} returns the batch status and a summary with total, completed, failed, and pending counts. The batch status switches to completed once all jobs have finished.
Polling tips
Poll every 5 to 10 seconds. Web pages typically finish in seconds. Large PDFs may take longer due to asynchronous text extraction: a job staying in processing is normal, not a failure. Job logs are retained for 90 days, so record your results within that window.
In the app: Content Upload tab
Non-developer teammates can follow the same uploads in the Content Upload tab of the Knowledge Base. Each document maps 1-to-1 to an API-created document and shows a matching state: "Queued/Processing", "Complete", or "Failed" (with the error reason displayed in the UI). This tab is the easiest way to visually confirm an API upload landed and finished indexing.
Error reference
HTTP | Code | Meaning | Action |
400 |
| Missing or invalid body parameters | Check that exactly one of |
401 | - | API key missing, invalid, or expired | Verify your |
403 | - | Subscription lacks API access | Contact your admin to enable API access |
404 |
| KB not found or not accessible | Verify the |
409 |
| Same URL already exists in this KB | Use a different URL or remove the existing document from the app |
413 |
| Text exceeds 10 MB | Reduce content size or split into multiple documents |
422 |
| File format not supported | |
429 |
| Rate limit or quota exceeded | Wait and retry |
Limits cheat sheet
Parameter | Limit |
Text content size | 10 MB |
Tags per document | 20 |
Documents per batch | 20 |
Job log retention | 90 days |
For the complete endpoint reference, visit the Mark AI API documentation.