Documents

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

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.

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

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 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.