Run a playbook against uploaded files

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"
  ],
  "company_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://app.gc.ai/api/external/v1/playbooks/{id}/run"

payload = {
    "file_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "review_mode": "third-party",
    "representing_party": "our company",
    "check_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "company_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    file_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    review_mode: 'third-party',
    representing_party: 'our company',
    check_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    company_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://app.gc.ai/api/external/v1/playbooks/{id}/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.gc.ai/api/external/v1/playbooks/{id}/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'file_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'review_mode' => 'third-party',
    'representing_party' => 'our company',
    'check_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'company_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.gc.ai/api/external/v1/playbooks/{id}/run"

	payload := strings.NewReader("{\n  \"file_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"review_mode\": \"third-party\",\n  \"representing_party\": \"our company\",\n  \"check_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"company_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.gc.ai/api/external/v1/playbooks/{id}/run")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"review_mode\": \"third-party\",\n  \"representing_party\": \"our company\",\n  \"check_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"company_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.gc.ai/api/external/v1/playbooks/{id}/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"file_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"review_mode\": \"third-party\",\n  \"representing_party\": \"our company\",\n  \"check_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"company_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

response = http.request(request)
puts response.read_body

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "playbooks/run",
  "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
    },
    "documents": [
      {
        "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "signed_url": "<string>",
        "download_url": "<string>",
        "original_file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "original_filename": "<string>"
      }
    ]
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "created_at": "<string>",
  "completed_at": "<string>"
}

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "playbooks/run",
  "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
    },
    "documents": [
      {
        "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "signed_url": "<string>",
        "download_url": "<string>",
        "original_file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "original_filename": "<string>"
      }
    ]
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "created_at": "<string>",
  "completed_at": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

Playbooks

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 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: 60 requests/minute per organization (20 per API key). Exceeding the limit returns 429 with a Retry-After header.

POST

playbooks

{id}

run

Run a playbook against uploaded files

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"
  ],
  "company_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'

import requests

url = "https://app.gc.ai/api/external/v1/playbooks/{id}/run"

payload = {
    "file_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "review_mode": "third-party",
    "representing_party": "our company",
    "check_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "company_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    file_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    review_mode: 'third-party',
    representing_party: 'our company',
    check_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    company_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  })
};

fetch('https://app.gc.ai/api/external/v1/playbooks/{id}/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.gc.ai/api/external/v1/playbooks/{id}/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'file_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'review_mode' => 'third-party',
    'representing_party' => 'our company',
    'check_ids' => [
        '3c90c3cc-0d44-4b50-8888-8dd25736052a'
    ],
    'company_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.gc.ai/api/external/v1/playbooks/{id}/run"

	payload := strings.NewReader("{\n  \"file_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"review_mode\": \"third-party\",\n  \"representing_party\": \"our company\",\n  \"check_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"company_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.gc.ai/api/external/v1/playbooks/{id}/run")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"file_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"review_mode\": \"third-party\",\n  \"representing_party\": \"our company\",\n  \"check_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"company_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.gc.ai/api/external/v1/playbooks/{id}/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"file_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"review_mode\": \"third-party\",\n  \"representing_party\": \"our company\",\n  \"check_ids\": [\n    \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n  ],\n  \"company_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"

response = http.request(request)
puts response.read_body

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "playbooks/run",
  "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
    },
    "documents": [
      {
        "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "signed_url": "<string>",
        "download_url": "<string>",
        "original_file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "original_filename": "<string>"
      }
    ]
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "created_at": "<string>",
  "completed_at": "<string>"
}

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "playbooks/run",
  "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
    },
    "documents": [
      {
        "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "signed_url": "<string>",
        "download_url": "<string>",
        "original_file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "original_filename": "<string>"
      }
    ]
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "created_at": "<string>",
  "completed_at": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

{
  "error": "<string>",
  "code": "<string>",
  "message": "<string>",
  "details": {}
}

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

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

company_id

string<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_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 | null

required

Playbook review payload when the job has succeeded

Show child attributes

error

object | null

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

⌘I

REST

MCP

CLI

Run a Playbook Against Uploaded Files

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response