<!-- Generated by scripts/generate_endpoint_docs.py — do not edit by hand. -->
# `api.documents.upload`

> `POST /documents` — ACPortal

**Python**

```python
api.documents.upload(*, job_display_id: str, file_path: str | Path, document_type: DocumentType | int, document_type_description: str | None = None, shared: int = 0, tags: list[str] | None = None, job_items: list[str] | None = None, rfq_id: int | None = None, filename: str | None = None) -> DocumentUploadResponse
```

**CLI**

```bash
ab documents upload [--job-display-id ...] [--file-path ...] [--document-type ...] [--document-type-description ...] [--shared ...] [--tags ...] [--job-items ...] [--rfq-id ...] [--filename ...]
```

POST /documents — upload a single document of any type (multipart).

The accompanying form fields are validated through
:class:`~ab.api.models.documents.DocumentUploadRequest` and the file is
streamed as the ``file`` part. This is the canonical upload primitive;
:meth:`upload_item_photo` is a thin wrapper that fills in the
item-photo specifics.

Args:
    job_display_id: Job display ID the document belongs to.
    file_path: Path to the file to upload.
    document_type: Document type; see :class:`~ab.api.models.enums.DocumentType`.
    document_type_description: Optional human-readable type label.
    shared: Sharing bitmask (0 = private).
    tags: Optional tags to attach.
    job_items: Item UUID(s) to associate (used for item photos).
    rfq_id: Optional RFQ ID to associate.
    filename: Override the multipart filename (defaults to the file's name).

Returns:
    DocumentUploadResponse: The parsed upload result.

## Request body — `DocumentUploadRequest`

| Field | Type | Required | Description |
|---|---|---|---|
| `JobDisplayId` | `str` | yes | Job display ID the document belongs to (e.g. '2000000'). |
| `DocumentType` | `DocumentType \| int` | yes | Document type ID; see DocumentType (6 = Item Photo). |
| `DocumentTypeDescription` | `Optional[str]` | no | Human-readable label for the document type. |
| `Shared` | `int` | no | Sharing bitmask (0 = private); controls portal visibility. |
| `Tags` | `Optional[list[str]]` | no | Free-form tags to attach to the document. |
| `JobItems` | `Optional[list[str]]` | no | Item UUID(s) to associate the document with (required for item photos). |
| `RfqId` | `Optional[int]` | no | RFQ ID to associate the document with, if applicable. |

## Response

Returns `DocumentUploadResponse`.

| Field | Type | Required | Description |
|---|---|---|---|
| `success` | `Optional[bool]` | no | Whether the upload succeeded. |
| `message` | `Optional[str]` | no | Human-readable status or error message. |
| `uploadedFiles` | `Optional[list[UploadedFile]]` | no | Per-file results for the upload. |
| `id` | `Optional[int]` | no | Document ID when a single file was uploaded. |
| `fileName` | `Optional[str]` | no | Stored file name when a single file was uploaded. |

---

[← Back to api.documents](../documents.md)