---
title: "Upload a document for printing"
description: "Upload a print-ready PDF or explicit RAW printer-language payload before creating a CloudPrint print job."
---
# Upload a document for printing
Upload a print-ready PDF or explicit RAW printer-language payload before creating a CloudPrint print job.
POST/api/v1/documentsAPI version: v1operationId:uploadDocumentView as Markdown
## What this endpoint does
Upload a print-ready PDF or explicit RAW printer-language payload before creating a CloudPrint print job.
## Authentication
Send a short-lived access token in `Authorization: Bearer `.
**Required scopes:** `documents:write`
## Request
**Production base URL:** `https://public-api.cloudprint.me/api/v1/documents`
### Parameters
This endpoint has no path, query or custom header parameters.
### Request body
**Content type:** `multipart/form-data`
| Name | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `file` | `string (binary)` | yes | Binary PDF or RAW document uploaded as multipart form data. | — |
| `document_format` | `string \| null` | no | Explicit print format, such as `pdf` or `raw`. | enum: `pdf`, `raw`; example: `"raw"` |
| `document_raw_language` | `string \| null` | no | Printer command language used by RAW data, for example ZPL or EPL. | enum: `tspl`, `zpl`, `cpcl`, `escpos`; example: `"zpl"` |
### Example requests
#### cURL
```bash
curl -sS https://public-api.cloudprint.me/api/v1/documents \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F "file=@shipping-label.pdf"
```
## Response
**HTTP status:** `201` — Document uploaded
### Response fields
| Name | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `document_id` | `string (uuid)` | yes | Stable UUID returned after a successful document upload. | — |
| `original_filename` | `string` | yes | — | example: `"invoice.pdf"` |
| `mime_type` | `string` | yes | — | example: `"application/pdf"` |
| `document_format` | `string` | yes | Explicit print format, such as `pdf` or `raw`. | enum: `pdf`, `raw`; example: `"pdf"` |
| `document_raw_language` | `string \| null` | yes | Printer command language used by RAW data, for example ZPL or EPL. | enum: `tspl`, `zpl`, `cpcl`, `escpos`; example: `null` |
| `size_bytes` | `integer` | yes | Stored document size in bytes. | example: `1024` |
### Example response
```json
{
"document_id": "11111111-1111-4111-8111-111111111111",
"original_filename": "invoice.pdf",
"mime_type": "application/pdf",
"document_format": "pdf",
"document_raw_language": null,
"size_bytes": 1024
}
```
## Errors
| HTTP status | Description |
| --- | --- |
| `400` | Invalid upload request |
| `401` | OAuth bearer token is missing or invalid |
| `403` | OAuth bearer token does not include documents:write |
| `413` | Uploaded file is too large |
| `415` | Uploaded file type is not supported by the Public API |
| `422` | Document validation failed |
| `429` | Rate limit exceeded |
| `500` | Unexpected error |
## Integration guidance
- PDF is the default. For RAW printing, explicitly send `document_format=raw` and `document_raw_language`.
- Convert DOC and DOCX to a print-ready PDF in your backend before uploading.
- Keep the returned `document_id` for the subsequent print-job request.
## Related documentation