GCgc-ai
Playbooks

Run a playbook against uploaded files

Run a playbook against one or more uploaded files and receive structured check results.

<Note> This endpoint is asynchronous: it returns a job envelope, and the result is filled in once the job completes. See [Asynchronous Requests](https://docs.gc.ai/api-reference/concepts/async-jobs) for how waiting, polling, and the envelope work. </Note>

Files referenced by file_ids must be accessible to the caller and in ready status. The playbook must be in completed status. Org-scoped keys can run org-visible playbooks against non-access-controlled files.

<Note> This is an inference endpoint and is [rate limited](https://docs.gc.ai/api-reference/concepts/rate-limits): 60 requests/minute per organization (20 per API key). Exceeding the limit returns `429` with a `Retry-After` header. </Note>
post/playbooks/{id}/run

Request

Path parameters

idstring uuid required

Playbook ID from GET /playbooks.

Query parameters

waitinteger nullable

Optional long-poll wait time in seconds. Use 0 for fire-and-forget behavior. If both wait and Prefer: wait=... are supplied, they must match. Values above 90 are clamped.

Headers

Preferstring

Optional RFC 7240 wait preference, for example wait=0. If both this header and the wait query parameter are supplied, they must match.

Example:wait=0

Request body

file_idsstring[] required

IDs of uploaded files to review. Files must be in ready status. At least one file is required.

review_mode'first-party' | 'third-party'

Whose perspective the review takes. third-party reviews a counterparty document (default); first-party reviews your own.

representing_partystring

Name of the party the review represents (default: "our company").

check_idsstring[]

Optional subset of check IDs to evaluate. Omit to run every check in the playbook.

company_idstring uuid

Optional company profile to ground the review in, so the checks have that company's context (industry, jurisdiction, regulations, risk posture). Discover company profiles via GET /company-profiles.

Opt-in: supply this to ground the review against a specific company. When omitted, the review runs with no company profile. This is separate from representing_party, which stays free text.

Response

Job completed within the effective wait window

job_idstring uuid required

Async job identifier

kind'playbooks/run' required

Stable job kind for this endpoint

status'pending' | 'running' | 'succeeded' | 'failed' | 'canceled' required

Current job status

created_atstring required

ISO 8601 creation timestamp

completed_atstring nullable required

ISO 8601 completion timestamp, or null when not terminal

Changes

No recorded changes to this operation across all 1 revision of this API.