> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gc.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Run a Playbook Against Uploaded Files
> Run a playbook against one or more uploaded files and receive structured check results.
This endpoint is asynchronous: it returns a job envelope, and the result is filled in once the job completes. See [Asynchronous Requests](/api-reference/concepts/async-jobs) for how waiting, polling, and the envelope work.
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.
## OpenAPI
````yaml POST /playbooks/{id}/run
openapi: 3.0.3
info:
title: GC AI External API
version: 1.0.0
description: >-
The GC AI External API allows programmatic access to GC AI's chat
capabilities. It's designed for integration with workflow automation tools
like Zapier, Make, n8n, or custom applications.
## Authentication
All API requests must include an API key in the `Authorization` header:
```
Authorization: gcai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
API keys can be created in the GC AI app under **Settings → API**.
## Current Limitations
The API is optimized for single-turn completions. The following are not yet
available via API:
- **Multi-turn conversations**: each request is independent
- **Interactive clarification**: the model cannot pause to ask the caller a
follow-up question; the `askUserQuestions` tool is disabled on the API
surface in beta
## Usage
Usage is tracked and viewable in the GC AI app under **Settings → API → View
Usage**.
## Support
For API support, contact [support@gc.ai](mailto:support@gc.ai) or reach out
to your account representative.
contact:
email: support@gc.ai
servers:
- url: https://app.gc.ai/api/external/v1
description: Production server
security: []
tags:
- name: Chat
description: AI chat completion endpoints
- name: Files
description: File upload and management endpoints
- name: Folders
description: Folder management endpoints
- name: Playbooks
description: Playbook review endpoints
- name: Projects
description: Project management endpoints
- name: Utility
description: Health check and connectivity endpoints
paths:
/playbooks/{id}/run:
post:
tags:
- Playbooks
summary: Run a playbook against uploaded files
description: >-
Run a playbook against one or more uploaded files and receive structured
check results.
This endpoint is asynchronous: it returns a job envelope, and the result
is filled in once the job completes. See [Asynchronous
Requests](/api-reference/concepts/async-jobs) for how waiting, polling,
and the envelope work.
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.
operationId: runPlaybook
parameters:
- schema:
type: string
format: uuid
description: Playbook ID from `GET /playbooks`.
required: true
description: Playbook ID from `GET /playbooks`.
name: id
in: path
- schema:
type: integer
nullable: true
minimum: 0
description: >-
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.
example: 0
required: false
description: >-
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.
name: wait
in: query
- schema:
type: string
description: >-
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
required: false
description: >-
Optional RFC 7240 wait preference, for example `wait=0`. If both
this header and the `wait` query parameter are supplied, they must
match.
name: Prefer
in: header
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RunPlaybookRequest'
responses:
'200':
description: Job completed within the effective wait window
content:
application/json:
schema:
$ref: '#/components/schemas/RunPlaybookResponse'
'202':
description: Job accepted but not yet complete
content:
application/json:
schema:
$ref: '#/components/schemas/RunPlaybookResponse'
'400':
description: Invalid request body, playbook not ready, or files still extracting
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Missing or malformed API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Playbook not found or file IDs not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: One or more files have a permanent extraction failure
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Service temporarily unavailable
headers:
Retry-After:
schema:
type: string
description: >-
Seconds to wait before retrying after a transient service
outage.
example: '5'
required: true
description: >-
Seconds to wait before retrying after a transient service
outage.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- ApiKeyAuth: []
components:
schemas:
RunPlaybookRequest:
type: object
properties:
file_ids:
type: array
items:
type: string
format: uuid
minItems: 1
description: >-
IDs of uploaded files to review. Files must be in `ready` status. At
least one file is required.
review_mode:
type: string
enum:
- first-party
- third-party
default: third-party
description: >-
Whose perspective the review takes. `third-party` reviews a
counterparty document (default); `first-party` reviews your own.
representing_party:
type: string
default: our company
description: 'Name of the party the review represents (default: "our company").'
check_ids:
type: array
items:
type: string
format: uuid
minItems: 1
description: >-
Optional subset of check IDs to evaluate. Omit to run every check in
the playbook.
required:
- file_ids
RunPlaybookResponse:
type: object
properties:
job_id:
type: string
format: uuid
description: Async job identifier
kind:
type: string
enum:
- playbooks/run
description: Stable job kind for this endpoint
status:
type: string
enum:
- pending
- running
- succeeded
- failed
- canceled
description: Current job status
result:
$ref: '#/components/schemas/RunPlaybookResult'
error:
type: object
nullable: true
properties:
code:
type: string
message:
type: string
required:
- code
- message
description: Failure payload when the job has failed
created_at:
type: string
description: ISO 8601 creation timestamp
completed_at:
type: string
nullable: true
description: ISO 8601 completion timestamp, or null when not terminal
required:
- job_id
- kind
- status
- result
- error
- created_at
- completed_at
Error:
type: object
properties:
error:
type: string
description: Error message
message:
type: string
description: Additional error details
details:
type: object
additionalProperties:
nullable: true
description: Validation error details (for 400 errors)
required:
- error
RunPlaybookResult:
type: object
nullable: true
properties:
playbookTitle:
type: string
totalChecks:
type: number
results:
type: array
items:
$ref: '#/components/schemas/PlaybookCheckResult'
summary:
type: object
properties:
flags:
type: number
fallbacks:
type: number
passes:
type: number
errors:
type: number
required:
- flags
- fallbacks
- passes
- errors
required:
- playbookTitle
- totalChecks
- results
- summary
description: Playbook review payload when the job has succeeded
PlaybookCheckResult:
type: object
properties:
checkId:
type: string
format: uuid
checkTitle:
type: string
evaluationResult:
type: string
description: Evaluation outcome. One of `Pass`, `Flag`, `Fallback`, or `Error`.
documentPosition:
type: number
nullable: true
description: >-
Position in the document where the matched language was found, or
null if not anchored.
required:
- checkId
- checkTitle
- evaluationResult
- documentPosition
additionalProperties:
nullable: true
description: >-
Per-check evaluation result. Additional fields (e.g. `analysis`,
`revisions`) may appear depending on the check type.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: |-
API key for authentication. Format: `gcai_xxxxxxxxx`
Create API keys in the GC AI app under Settings → API.
````