# Documents

```{eval-rst}
.. autoclass:: ab.api.endpoints.documents.DocumentsEndpoint
   :members:
   :undoc-members:
```

## Per-endpoint reference

Each route-backed method has its own page rendering the HTTP route, the
Python and CLI call signatures, and the request/response model field tables.
This is the page `help(api.documents.<method>)` links to via its `Docs:` footer.
These pages are generated by `scripts/generate_endpoint_docs.py` and kept
current by a CI freshness gate.

```{toctree}
:maxdepth: 1
:glob:

documents/*
```


## Methods

### upload

`POST /documents` — Upload a single document of any type (multipart). This is
the canonical upload primitive; the form fields are validated through
{class}`~ab.api.models.documents.DocumentUploadRequest`.

**Returns:** {class}`~ab.api.models.documents.DocumentUploadResponse`

```python
from ab import ABConnectAPI
from ab.api.models.enums import DocumentType

api = ABConnectAPI(env="staging")
result = api.documents.upload(
    job_display_id="2000001",
    file_path="/path/to/file.pdf",
    document_type=DocumentType.BOL,
)
```

### upload_item_photo

Upload one item photo, associated with one or more job items. A thin wrapper
over `upload()` that sets `DocumentType.ITEM_PHOTO` and routes the item id(s)
to the `JobItems` field.

**Returns:** {class}`~ab.api.models.documents.DocumentUploadResponse`

```python
result = api.documents.upload_item_photo(
    job_display_id="2000001",
    item_ids="550e8400-e29b-41d4-a716-446655440001",  # a single UUID or a list
    file_path="/path/to/photo.jpg",
)
```

### upload_item_photos

Upload several item photos in one call — one request per file. Always returns a
list (one {class}`~ab.api.models.documents.DocumentUploadResponse` per file),
even for a single file.

```python
results = api.documents.upload_item_photos(
    job_display_id="2000001",
    item_ids="550e8400-e29b-41d4-a716-446655440001",
    file_paths=["/path/to/a.jpg", "/path/to/b.jpg"],
)
```

### list

`GET /documents/list` — List documents for a job.

**Returns:** `list[`{class}`~ab.api.models.documents.Document`]`

```python
docs = api.documents.list("2000001")
```

### get

`GET /documents/get/{docPath}` — Download a document (binary).

**Returns:** `bytes`

```python
content = api.documents.get("path/to/document.pdf")
with open("downloaded.pdf", "wb") as f:
    f.write(content)
```

### update

`PUT /documents/update/{docId}` — Update document metadata.

```python
api.documents.update("doc-id", data={"sharingLevel": 1})
```