Run a Playbook Against Uploaded Files

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

Requires a user-scoped API key (u:gcai_...). Files referenced by file_ids must belong to the caller and be in ready status. Poll GET /files/{id} until extraction completes. The playbook must be in completed status.

Set wait=0 or Prefer: wait=0 to enqueue the run and return immediately with a pending job envelope. Otherwise the endpoint waits up to the effective wait window before returning. Poll GET /jobs/{id} for the result if the job is not yet complete.

POST /playbooks/{id}/run

Run a playbook against uploaded files

cURL

curl --request POST \
  --url https://app.gc.ai/api/external/v1/playbooks/{id}/run \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "file_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "review_mode": "third-party",
  "representing_party": "our company",
  "check_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}
'

200

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "result": {
    "playbookTitle": "<string>",
    "totalChecks": 123,
    "results": [
      {
        "checkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "checkTitle": "<string>",
        "evaluationResult": "<string>",
        "documentPosition": 123
      }
    ],
    "summary": {
      "flags": 123,
      "fallbacks": 123,
      "passes": 123,
      "errors": 123
    }
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "created_at": "<string>",
  "completed_at": "<string>"
}

Authorizations

Authorization · string · header · required

API key for authentication. Format: gcai_xxxxxxxxx

Create API keys in the GC AI app under Settings → API.

Headers

Prefer · string

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"

Path Parameters

id · string<uuid> · required

Playbook ID from GET /playbooks.

Query Parameters

wait · integer | null

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.

Required range: x >= 0

Example:

0

Body

application/json

file_ids · string<uuid>[] · required

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

Minimum array length: 1

review_mode · enum<string> · default: third-party

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

Available options: first-party, third-party

representing_party · string · default: our company

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

check_ids · string<uuid>[]

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

Minimum array length: 1

Response

200

application/json

Job completed within the effective wait window

job_id · string<uuid> · required

Async job identifier

kind · enum<string> · required

Stable job kind for this endpoint

Available options: playbooks/run

status · enum<string> · required

Current job status

Available options: pending, running, succeeded, failed, canceled

result · object · required

Playbook review payload when the job has succeeded

Show child attributes

error · object · required

Failure payload when the job has failed

Show child attributes

created_at · string · required

ISO 8601 creation timestamp

completed_at · string | null · required

ISO 8601 completion timestamp, or null when not terminal