---
title: "Upload a file directly from an agent or application"
method: POST
path: "/api/documents"
---

# Upload a file directly from an agent or application

`POST /api/documents`

## Request

- Base URL: `https://postedly.com`
- URL: `https://postedly.com/api/documents`
- Auth: HTTP bearer

Preferred for an agent that has file bytes and authenticated HTTP access. Reuse its existing OAuth bearer token with quotes:write, send multipart fields file, service (optional; defaults to fax) and optional expectedSha256. Return HTTP 201 with a Document object directly: its id is the quote documentId. Validate the returned hash against the source. There is no user download/re-upload step and no arbitrary URL import. Stored upload acceptance does not guarantee a selected product or service can quote the file; quote preflight applies exact product dimensions/page limits and generates the final proof for approval. Uploading neither charges nor sends.

## Response `201`

Validated document saved privately for the authenticated owner. This is the Document object itself, not an envelope.

- Document
  - `id` string, uuid, required: Use this value as documentId in a quote; the person does not need to copy it.
  - `name` string, required
  - `pages` integer, required: Inspected page count; images count as one. Upload PDFs allow up to 50 pages; service-specific quote limits can be lower.
  - `bytes` integer, required
  - `sha256` string, required: Server-computed SHA-256 of the stored raw file bytes.
  - `contentType` 'application/pdf' | 'image/jpeg' | 'image/png', required: Detected media type, not a trusted client declaration.
  - `previewUrl` string, uri-reference, required: Private preview. Standard document URLs require the same owner’s bearer token; capability-scoped handoff URLs require their unexpired ticket. Resolve relative URLs against this API origin. Never make the file public to show a preview.

## Other responses

- `400`: Invalid service, missing file, invalid SHA-256, hash mismatch, invalid or encrypted PDF, unsupported format, or document limits exceeded. No document is saved when validation fails.
- `401`: Valid session or OAuth bearer token required
- `403`: OAuth token requires quotes:write
- `413`: Request body exceeds the bounded upload envelope
- `429`: Upload rate limit exceeded
- `500`: Upload could not be stored

---

[API](https://skmtc.dev/postedly/apis/postedly-send-api.md) · [All operations](https://skmtc.dev/postedly/apis/postedly-send-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postedly/apis/postedly-send-api/revisions/c7c71c05f64b?raw)