# Documents

> Turn a brief, Brand Pack, and optional Offer into downloadable PPTX, DOCX, or PDF files.

Canonical guide: <https://api.blackpearl.com/docs/documents>

Raw Markdown: <https://api.blackpearl.com/docs/raw/documents.md>

OpenAPI: <https://api.blackpearl.com/v1/openapi.json>

Documents is a GA generation capability for finished sales collateral. It runs the Doc Maker managed agent asynchronously and stores the resulting files with the Job. It does not create account dossiers: the separate Company Dossier Specifications operations remain Preview planning contracts.

## Create a document Job

Operation `create_document_job_v1_documents_post` accepts `POST /v1/documents`. `brief` is required and describes the artifact, audience, and content. The other inputs constrain or enrich the run:

| Field | Behavior |
|---|---|
| `document_type` | Optional `proposal`, `playbook`, `deck`, `gtm_strategy`, `report`, or `one_pager`. The agent chooses when omitted. |
| `format` | Optional `pptx`, `docx`, or `pdf`. The agent chooses when omitted. |
| `target_domain` | Optional focus-account domain. Schemes, `www.`, and paths are normalized to a bare domain. |
| `brand` | Optional Brand profile ID or key. The organization's default Brand is used when omitted. |
| `offer` | Optional Offer ID or key whose value propositions, proof points, pricing, ICP, and stage fit are attached. |
| `template_urls` | Up to three HTTP(S) reference documents whose structure, tone, and layout should be followed. |
| `title` | Optional title retained with the Job and result. |
| `external_ref` | Optional caller correlation value echoed in the result. |

The selected Brand must have a completed guideline so the platform can freeze its Brand Pack into the run. An attached Offer must be active and belong to the same organization.

```bash
JOB=$(curl --fail-with-body --silent --show-error \
  --request POST "$BLACKPEARL_API_BASE_URL/v1/documents" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" \
  --header "Idempotency-Key: document-20260720-acme-proposal" \
  --header "Content-Type: application/json" \
  --data '{
    "brief": "Create a first-meeting proposal for Acme RevOps. Lead with pipeline visibility, explain our 90-day rollout, and close with pricing.",
    "document_type": "proposal",
    "format": "docx",
    "target_domain": "acme.example",
    "brand": "northstar",
    "offer": "analytics_suite",
    "template_urls": ["https://cdn.example/templates/enterprise-proposal.docx"],
    "title": "Acme RevOps proposal",
    "external_ref": "crm-account-123"
  }')

JOB_ID=$(printf '%s' "$JOB" | jq -er '.id')
```

The endpoint returns `202 Accepted` with a typed `DocumentJobResponse`. Generate and persist the `Idempotency-Key` before the first attempt. Matching retries within 24 hours replay the original response; using the key with changed input returns `idempotency_key_reused`.

## Poll and interpret the result

Poll `GET /v1/jobs/{job_id}` using the bounded flow in [Jobs and resumable polling](https://api.blackpearl.com/docs/jobs). The `documents` Job variant retains the normalized input, three execution stages, usage, and a typed result after success.

The result contains:

- `files`: stored file references with `file_id`, `filename`, `format`, `size_bytes`, and an informational Console download path;
- `brand` and optional `offer`: the exact selling context resolved for the run;
- `progress`: up to 50 curated agent milestones;
- `model`, `duration_seconds`, `request_echo`, `title`, `target_domain`, and `external_ref` for traceability.

Real runs ledger the managed session's authoritative token usage and cost in the Job `usage` object. A succeeded Job can contain more than one file. Treat generated claims and downloaded content as reviewable application data, not publishing or outreach authority.

If the managed Doc Maker integration is not configured, the Job fails closed with a configuration error and produces no synthetic file.

## Download files

Operation `download_document_job_file_v1_documents__job_id__files__file_id__get` returns `GET /v1/documents/{job_id}/files/{file_id}`. Use the IDs from the successful Job result:

```bash
COMPLETED_JOB=$(curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/jobs/$JOB_ID" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY")

FILE_ID=$(printf '%s' "$COMPLETED_JOB" | jq -er '.result.files[0].file_id')

curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/documents/$JOB_ID/files/$FILE_ID" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" \
  --output acme-proposal.docx
```

The response is the raw file with a format-specific `Content-Type` and an attachment filename. Unknown formats use `application/octet-stream`. Files share the Job's 30-day retention window and are visible only to the owning project.

Common create failures are `capability_disabled`, `insufficient_credits`, `quota_exceeded`, `budget_exceeded`, `brand_not_found`, `brand_guideline_missing`, `offer_not_found`, and `offer_archived`. A missing or cross-project Job or file returns `not_found`. Follow [Errors and retry decisions](https://api.blackpearl.com/docs/errors) and never repeat an ambiguous create request without its original idempotency key.

## Preview dossier planning contracts

Company Dossier Specifications remain Preview and contract-only. They freeze a target company, connector revision, requested sections, collection budgets, purpose, and policy version; they perform no provider request, research, model call, or rendering.

Preview operation `create_company_dossier_specification_v1_company_dossier_specifications_post` creates an immutable plan. Preview operation `list_company_dossier_specifications_v1_company_dossier_specifications_get` lists plans with cursor pagination. Preview operation `get_company_dossier_specification_v1_company_dossier_specifications__specification_id__get` reads one plan.

Do not interpret a stored dossier specification as collected evidence, generated collateral, permission to crawl a site, or authorization to publish.