> ## 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.
This is an inference endpoint and is [rate limited](/api-reference/concepts/rate-limits): 60 requests/minute per organization (20 per API key). Exceeding the limit returns `429` with a `Retry-After` header.
## 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**.
## Multi-turn Conversations
Conversations can span multiple turns: pass the `chat_id` returned by a
completion back on your next request to continue the same chat. See
[Multi-turn Conversations](/api-reference/concepts/multi-turn).
## Current Limitations
The following is not yet available via API:
- **Interactive clarification**: the model cannot pause to ask the caller a
follow-up question; the `askUserQuestions` tool is disabled on the API
surface
## 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: Async Jobs
description: Poll the status and result of asynchronous API jobs
- name: Chat
description: AI chat completion endpoints
- name: Chats
description: Chat management, message history, and sharing endpoints
- name: Contract Intelligence
description: Vault discovery and document ingestion endpoints for Contract Intelligence
- name: Files
description: File upload and management endpoints
- name: Folders
description: Folder management endpoints
- name: Playbooks
description: Playbook review endpoints
- name: Profiles
description: Personal and company profile endpoints
- name: Projects
description: Project management endpoints
- name: Skills
description: Skill library management endpoints
- name: Utility
description: Health check and connectivity endpoints
- name: Usage
description: Usage and credit/billing reporting 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.
This is an inference endpoint and is [rate
limited](/api-reference/concepts/rate-limits): 60 requests/minute per
organization (20 per API key). Exceeding the limit returns `429` with a
`Retry-After` header.
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, file IDs not found, or the `company_id` was 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'
'429':
description: >-
Rate limit exceeded. See [Rate
Limits](/api-reference/concepts/rate-limits) for the tiers, limits,
and how to back off.
headers:
Retry-After:
schema:
type: string
description: Seconds to wait before retrying after a rate-limit block.
example: '60'
required: true
description: Seconds to wait before retrying after a rate-limit block.
RateLimit-Limit:
schema:
type: string
description: Request quota for the applicable window.
example: '3'
required: true
description: Request quota for the applicable window.
RateLimit-Remaining:
schema:
type: string
description: Requests remaining in the current window.
example: '0'
required: true
description: Requests remaining in the current window.
RateLimit-Reset:
schema:
type: string
description: Seconds until the quota resets.
example: '60'
required: true
description: Seconds until the quota resets.
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.
company_id:
type: string
format: uuid
description: >-
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.
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
code:
type: string
description: >-
Machine-readable error code present on some errors (e.g.
`RATE_LIMITED`, `INSUFFICIENT_CREDITS`, `TRIAL_NOT_STARTED`,
`BILLING_NOT_CONFIGURED`). Branch on this rather than the
human-readable `error` string.
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
documents:
type: array
items:
$ref: '#/components/schemas/ApiDocument'
description: >-
Redlined documents produced from the review's suggested revisions,
applied as tracked changes. Present only when a single DOCX file was
reviewed and at least one revision applied. Works with either a
user-scoped or an org-scoped key. The original file is preserved;
each entry exposes a new `file_id` and a signed download URL.
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.
ApiDocument:
type: object
properties:
file_id:
type: string
format: uuid
description: >-
The new uploaded file ID for the produced document. Use it with
`POST /chat/completions` `file_ids` to apply further edits to this
version. Download via `signed_url` for the finished file.
original_file_id:
type: string
format: uuid
description: >-
The `file_id` the changes were applied to (edits only). The original
file is preserved unchanged. Omitted for newly generated documents.
filename:
type: string
description: >-
Filename of the produced document (edits are prefixed with
`edited_`).
original_filename:
type: string
description: >-
Filename of the source file the changes were applied to (edits
only). Omitted for newly generated documents.
signed_url:
type: string
format: uri
description: >-
Time-limited direct download URL (no login required). Valid for 7
days from job completion. Download promptly; the URL is not
re-minted, so re-fetching the job after expiry returns the same
expired URL. For a link you intend to store or email, use
`download_url` instead.
download_url:
type: string
format: uri
description: >-
Permanent, login-gated download link for the produced document.
Unlike `signed_url` it never expires: it points at a GC AI web page
that mints a fresh download for a signed-in user with access to the
file, and redirects to GC AI login otherwise. Use this for links you
store or email. The produced document inherits the source document's
access, so it opens for whoever can already see the source: a
document uploaded to the organization is org-visible, one in a
project is visible to that project's members, and one in personal
files stays private to the uploader. Recipients still need a GC AI
login.
required:
- file_id
- filename
- signed_url
- download_url
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.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.