Documents

class ab.api.endpoints.documents.DocumentsEndpoint(client)[source]

Operations on documents (ACPortal API).

Parameters:: client (HttpClient)

upload(*, job_display_id, file_path, document_type, document_type_description=None, shared=0, tags=None, job_items=None, rfq_id=None, filename=None)[source]

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

The accompanying form fields are validated through DocumentUploadRequest and the file is streamed as the file part. This is the canonical upload primitive; upload_item_photo() is a thin wrapper that fills in the item-photo specifics.

Parameters:

job_display_id (str) – Job display ID the document belongs to.
file_path (str | Path) – Path to the file to upload.
document_type (DocumentType | int) – Document type; see DocumentType.
document_type_description (str | None) – Optional human-readable type label.
shared (int) – Sharing bitmask (0 = private).
tags (list[str] | None) – Optional tags to attach.
job_items (list[str] | None) – Item UUID(s) to associate (used for item photos).
rfq_id (int | None) – Optional RFQ ID to associate.
filename (str | None) – Override the multipart filename (defaults to the file’s name).

Returns:

The parsed upload result.

Return type:

DocumentUploadResponse

Docs: https://ab-sdk.readthedocs.io/en/latest/api/documents/upload.html Request model: DocumentUploadRequest Response model: DocumentUploadResponse

upload_item_photo(*, job_display_id, item_ids, file_path, shared=0, tags=None, filename=None)[source]

Upload one item photo, associated with one or more job items.

A thin convenience wrapper over upload() that sets document_type=DocumentType.ITEM_PHOTO and routes item_ids to the JobItems form field. Accepts a single item UUID or a list.

Parameters:

job_display_id (str) – Job display ID the photo belongs to.
item_ids (str | list[str]) – One item UUID, or a list of UUIDs, to attach the photo to.
file_path (str | Path) – Path to the image file.
shared (int) – Sharing bitmask (0 = private).
tags (list[str] | None) – Optional tags to attach.
filename (str | None) – Override the multipart filename (defaults to the file’s name).

Returns:

The parsed upload result.

Return type:

DocumentUploadResponse

upload_item_photos(*, job_display_id, item_ids, file_paths, shared=0, tags=None)[source]

Upload several item photos in one call — one request per file.

Returns one DocumentUploadResponse per file, in the same order as file_paths (always a list, even for a single file — unlike the legacy SDK’s variable return). Every file is attached to the same item_ids.

Parameters:

job_display_id (str) – Job display ID the photos belong to.
item_ids (str | list[str]) – One item UUID, or a list of UUIDs, to attach every photo to.
file_paths (list[str | Path]) – Paths to the image files to upload.
shared (int) – Sharing bitmask (0 = private).
tags (list[str] | None) – Optional tags to attach to every photo.

Returns:

One result per uploaded file, in order.

Return type:

list[DocumentUploadResponse]

list(job_display_id)[source]

GET /documents/list

Docs: https://ab-sdk.readthedocs.io/en/latest/api/documents/list.html Query params: DocumentListParams Response model: List[Document]

Parameters:: job_display_id (str | int)
Return type:: list[Document]

get(doc_path)[source]

GET /documents/get/{docPath} — returns raw bytes.

Parameters:: doc_path (str)
Return type:: bytes

update(doc_id, *, data)[source]

PUT /documents/update/{docId}.

Parameters:

doc_id (str) – Document identifier.
data (DocumentUpdateRequest | dict) – Document update payload. Accepts a DocumentUpdateRequest instance or a dict.

Return type:

None

Request model: DocumentUpdateRequest

Docs: https://ab-sdk.readthedocs.io/en/latest/api/documents/update.html Request model: DocumentUpdateRequest

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.

Methods

upload

POST /documents — Upload a single document of any type (multipart). This is the canonical upload primitive; the form fields are validated through DocumentUploadRequest.

Returns: DocumentUploadResponse

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: DocumentUploadResponse

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 DocumentUploadResponse per file), even for a single file.

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[Document]`

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

get

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

Returns: bytes

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.

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