Create chat completion

curl --request POST \
  --url https://app.gc.ai/api/external/v1/chat/completions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "What are the key terms to look for in a software license agreement?",
  "file_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "playbook_ids": [
    "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
  ],
  "playbook_id": "<string>",
  "skill_ids": [
    "b2c3d4e5-f6a7-4890-bcde-f12345678901"
  ],
  "chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
'

import requests

url = "https://app.gc.ai/api/external/v1/chat/completions"

payload = {
    "message": "What are the key terms to look for in a software license agreement?",
    "file_ids": ["123e4567-e89b-12d3-a456-426614174000"],
    "playbook_ids": ["f9e8d7c6-b5a4-3210-fedc-ba0987654321"],
    "playbook_id": "<string>",
    "skill_ids": ["b2c3d4e5-f6a7-4890-bcde-f12345678901"],
    "chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
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({
    message: 'What are the key terms to look for in a software license agreement?',
    file_ids: ['123e4567-e89b-12d3-a456-426614174000'],
    playbook_ids: ['f9e8d7c6-b5a4-3210-fedc-ba0987654321'],
    playbook_id: '<string>',
    skill_ids: ['b2c3d4e5-f6a7-4890-bcde-f12345678901'],
    chat_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  })
};

fetch('https://app.gc.ai/api/external/v1/chat/completions', 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/chat/completions",
  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([
    'message' => 'What are the key terms to look for in a software license agreement?',
    'file_ids' => [
        '123e4567-e89b-12d3-a456-426614174000'
    ],
    'playbook_ids' => [
        'f9e8d7c6-b5a4-3210-fedc-ba0987654321'
    ],
    'playbook_id' => '<string>',
    'skill_ids' => [
        'b2c3d4e5-f6a7-4890-bcde-f12345678901'
    ],
    'chat_id' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  ]),
  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/chat/completions"

	payload := strings.NewReader("{\n  \"message\": \"What are the key terms to look for in a software license agreement?\",\n  \"file_ids\": [\n    \"123e4567-e89b-12d3-a456-426614174000\"\n  ],\n  \"playbook_ids\": [\n    \"f9e8d7c6-b5a4-3210-fedc-ba0987654321\"\n  ],\n  \"playbook_id\": \"<string>\",\n  \"skill_ids\": [\n    \"b2c3d4e5-f6a7-4890-bcde-f12345678901\"\n  ],\n  \"chat_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\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/chat/completions")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": \"What are the key terms to look for in a software license agreement?\",\n  \"file_ids\": [\n    \"123e4567-e89b-12d3-a456-426614174000\"\n  ],\n  \"playbook_ids\": [\n    \"f9e8d7c6-b5a4-3210-fedc-ba0987654321\"\n  ],\n  \"playbook_id\": \"<string>\",\n  \"skill_ids\": [\n    \"b2c3d4e5-f6a7-4890-bcde-f12345678901\"\n  ],\n  \"chat_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.gc.ai/api/external/v1/chat/completions")

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  \"message\": \"What are the key terms to look for in a software license agreement?\",\n  \"file_ids\": [\n    \"123e4567-e89b-12d3-a456-426614174000\"\n  ],\n  \"playbook_ids\": [\n    \"f9e8d7c6-b5a4-3210-fedc-ba0987654321\"\n  ],\n  \"playbook_id\": \"<string>\",\n  \"skill_ids\": [\n    \"b2c3d4e5-f6a7-4890-bcde-f12345678901\"\n  ],\n  \"chat_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n}"

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

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "chat/completions",
  "result": {
    "result": "When reviewing a software license agreement, key terms to examine include:\n\n1. **License Grant** - Understand the scope of rights granted...",
    "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "documents": [
      {
        "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "signed_url": "<string>",
        "original_file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "original_filename": "<string>"
      }
    ],
    "emails": [
      {
        "to": "<string>",
        "subject": "<string>",
        "body": "<string>",
        "plaintext_body": "<string>",
        "cc": "<string>",
        "bcc": "<string>"
      }
    ],
    "diagrams": [
      {
        "title": "<string>",
        "diagram_type": "<string>",
        "mermaid": "<string>"
      }
    ]
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "created_at": "<string>",
  "completed_at": "<string>"
}

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "chat/completions",
  "result": {
    "result": "When reviewing a software license agreement, key terms to examine include:\n\n1. **License Grant** - Understand the scope of rights granted...",
    "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "documents": [
      {
        "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "signed_url": "<string>",
        "original_file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "original_filename": "<string>"
      }
    ],
    "emails": [
      {
        "to": "<string>",
        "subject": "<string>",
        "body": "<string>",
        "plaintext_body": "<string>",
        "cc": "<string>",
        "bcc": "<string>"
      }
    ],
    "diagrams": [
      {
        "title": "<string>",
        "diagram_type": "<string>",
        "mermaid": "<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": {}
}

Chat

Create Chat Completion

Send a message to GC AI and receive an AI-generated response.

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.

Multi-turn conversations

Every response includes a chat_id. Pass it back as chat_id on a later request to continue that conversation. Conversation state — prior messages, tool calls, and any returned documents, emails, or diagrams — is held server-side, so each turn sends only the new message (plus any new file_ids); never re-send prior turns or previously returned outputs.

Only one turn may be in flight per chat at a time: a request whose chat_id already has a turn running is rejected with 409. Wait for the prior turn to reach a terminal state before sending the next.

Continuing a chat is scoped like materialization: personal keys continue chats they created; organization keys continue organization chats. See Multi-turn Conversations.

Server-side tools

The model can invoke tools automatically while generating a response. Tool calls happen server-side. Only the final assistant text is returned in result.result.

Tool	Description	Key type
Document reading	Read, query, and search within attached files	All
Web search	Search the web for current information	All
Research agent	Multi-step web research with synthesis	All
Case-law lookup	Search case law databases	User-scoped only
Playbook review	Run playbook checks against attached files (requires `playbook_ids`)	All
Document editing	Apply redline edits to an attached DOCX. All proposed revisions are auto-accepted; the edited file is returned via `result.documents`. The original file is preserved.	User-scoped only
Document generation	Generate a new DOCX from a prompt. The generated file is returned via `result.documents`.	User-scoped only
Slide generation	Generate a new PowerPoint deck (PPTX) from a prompt. The generated file is returned via `result.documents`.	User-scoped only
Email drafting	Draft a structured email from a prompt. The draft is returned via `result.emails` (`to`, `subject`, `body`, …).	All
Diagrams	Generate a diagram from a prompt. The diagram is returned via `result.diagrams` as validated Mermaid source (`mermaid`) you can render with any Mermaid-compatible renderer.	All

The following tools are not available via API in beta (the response is plain text with no channel for rich outputs):

Tool	Reason unavailable
Interactive clarification	Requires a back-and-forth channel with the caller

This is an inference endpoint and is rate limited: during the free beta, roughly 1 request/minute per organization (burst of 3). Exceeding the limit returns 429 with a Retry-After header.

POST

chat

completions

Create chat completion

curl --request POST \
  --url https://app.gc.ai/api/external/v1/chat/completions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "What are the key terms to look for in a software license agreement?",
  "file_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "playbook_ids": [
    "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
  ],
  "playbook_id": "<string>",
  "skill_ids": [
    "b2c3d4e5-f6a7-4890-bcde-f12345678901"
  ],
  "chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
'

import requests

url = "https://app.gc.ai/api/external/v1/chat/completions"

payload = {
    "message": "What are the key terms to look for in a software license agreement?",
    "file_ids": ["123e4567-e89b-12d3-a456-426614174000"],
    "playbook_ids": ["f9e8d7c6-b5a4-3210-fedc-ba0987654321"],
    "playbook_id": "<string>",
    "skill_ids": ["b2c3d4e5-f6a7-4890-bcde-f12345678901"],
    "chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
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({
    message: 'What are the key terms to look for in a software license agreement?',
    file_ids: ['123e4567-e89b-12d3-a456-426614174000'],
    playbook_ids: ['f9e8d7c6-b5a4-3210-fedc-ba0987654321'],
    playbook_id: '<string>',
    skill_ids: ['b2c3d4e5-f6a7-4890-bcde-f12345678901'],
    chat_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  })
};

fetch('https://app.gc.ai/api/external/v1/chat/completions', 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/chat/completions",
  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([
    'message' => 'What are the key terms to look for in a software license agreement?',
    'file_ids' => [
        '123e4567-e89b-12d3-a456-426614174000'
    ],
    'playbook_ids' => [
        'f9e8d7c6-b5a4-3210-fedc-ba0987654321'
    ],
    'playbook_id' => '<string>',
    'skill_ids' => [
        'b2c3d4e5-f6a7-4890-bcde-f12345678901'
    ],
    'chat_id' => 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  ]),
  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/chat/completions"

	payload := strings.NewReader("{\n  \"message\": \"What are the key terms to look for in a software license agreement?\",\n  \"file_ids\": [\n    \"123e4567-e89b-12d3-a456-426614174000\"\n  ],\n  \"playbook_ids\": [\n    \"f9e8d7c6-b5a4-3210-fedc-ba0987654321\"\n  ],\n  \"playbook_id\": \"<string>\",\n  \"skill_ids\": [\n    \"b2c3d4e5-f6a7-4890-bcde-f12345678901\"\n  ],\n  \"chat_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\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/chat/completions")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": \"What are the key terms to look for in a software license agreement?\",\n  \"file_ids\": [\n    \"123e4567-e89b-12d3-a456-426614174000\"\n  ],\n  \"playbook_ids\": [\n    \"f9e8d7c6-b5a4-3210-fedc-ba0987654321\"\n  ],\n  \"playbook_id\": \"<string>\",\n  \"skill_ids\": [\n    \"b2c3d4e5-f6a7-4890-bcde-f12345678901\"\n  ],\n  \"chat_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.gc.ai/api/external/v1/chat/completions")

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  \"message\": \"What are the key terms to look for in a software license agreement?\",\n  \"file_ids\": [\n    \"123e4567-e89b-12d3-a456-426614174000\"\n  ],\n  \"playbook_ids\": [\n    \"f9e8d7c6-b5a4-3210-fedc-ba0987654321\"\n  ],\n  \"playbook_id\": \"<string>\",\n  \"skill_ids\": [\n    \"b2c3d4e5-f6a7-4890-bcde-f12345678901\"\n  ],\n  \"chat_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n}"

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

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "chat/completions",
  "result": {
    "result": "When reviewing a software license agreement, key terms to examine include:\n\n1. **License Grant** - Understand the scope of rights granted...",
    "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "documents": [
      {
        "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "signed_url": "<string>",
        "original_file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "original_filename": "<string>"
      }
    ],
    "emails": [
      {
        "to": "<string>",
        "subject": "<string>",
        "body": "<string>",
        "plaintext_body": "<string>",
        "cc": "<string>",
        "bcc": "<string>"
      }
    ],
    "diagrams": [
      {
        "title": "<string>",
        "diagram_type": "<string>",
        "mermaid": "<string>"
      }
    ]
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "created_at": "<string>",
  "completed_at": "<string>"
}

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "kind": "chat/completions",
  "result": {
    "result": "When reviewing a software license agreement, key terms to examine include:\n\n1. **License Grant** - Understand the scope of rights granted...",
    "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "documents": [
      {
        "file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "filename": "<string>",
        "signed_url": "<string>",
        "original_file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "original_filename": "<string>"
      }
    ],
    "emails": [
      {
        "to": "<string>",
        "subject": "<string>",
        "body": "<string>",
        "plaintext_body": "<string>",
        "cc": "<string>",
        "bcc": "<string>"
      }
    ],
    "diagrams": [
      {
        "title": "<string>",
        "diagram_type": "<string>",
        "mermaid": "<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"

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

message

string

required

The user's message or prompt

Minimum string length: 1

Example:

"What are the key terms to look for in a software license agreement?"

file_ids

string<uuid>[]

Optional uploaded file IDs to attach as context for this completion. Upload files first via POST /files.

Example:

["123e4567-e89b-12d3-a456-426614174000"]

playbook_ids

string<uuid>[]

Optional playbook IDs to ground the completion in (up to 20). The model uses each playbook's checks and guidance to structure its review of the attached files. Discover playbooks via GET /playbooks.

Org-scoped keys can use org-visible and official playbooks.

Maximum array length: 20

Example:

["f9e8d7c6-b5a4-3210-fedc-ba0987654321"]

playbook_id

string

deprecated

Deprecated and no longer accepted. Use playbook_ids (an array) instead. Requests that include this field are rejected with a 400 so the playbook is never silently dropped.

skill_ids

string<uuid>[]

Optional skill IDs to run on the first turn. Each skill's instructions are injected as context for this completion. Discover skills via GET /skills.

Only valid when starting a new chat — omit them when continuing with chat_id.

Example:

["b2c3d4e5-f6a7-4890-bcde-f12345678901"]

chat_id

string<uuid>

Optional chat ID to continue an existing conversation, from the chat_id of a prior completion. Omit to start a new chat.

Conversation state is held server-side, so send only your new message (plus any new file_ids) — do not re-send prior turns or previously returned documents/emails/diagrams. Only one turn may be in flight per chat at a time. See Multi-turn Conversations.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

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:

chat/completions

status

enum<string>

required

Current job status

Available options:

pending,

running,

succeeded,

failed,

canceled

result

object | null

required

Completion 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

Slack Triage Bot Get Async Job Status

⌘I

Concepts

Examples

Chat

Files

Folders

Playbooks

Profiles

Projects

Skills

Usage

Utility

Create Chat Completion

Multi-turn conversations

Server-side tools

Authorizations

Headers

Query Parameters

Body

Response