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",
"project_id": "d4c3b2a1-f6e5-0987-dcba-fedcba098765",
"materialize": true,
"company_id": "d4c3b2a1-f6e5-0987-dcba-fedcba098765",
"vault_id": "e5d4c3b2-a1f6-7890-bcde-f1234567890a"
}
'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",
"project_id": "d4c3b2a1-f6e5-0987-dcba-fedcba098765",
"materialize": True,
"company_id": "d4c3b2a1-f6e5-0987-dcba-fedcba098765",
"vault_id": "e5d4c3b2-a1f6-7890-bcde-f1234567890a"
}
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',
project_id: 'd4c3b2a1-f6e5-0987-dcba-fedcba098765',
materialize: true,
company_id: 'd4c3b2a1-f6e5-0987-dcba-fedcba098765',
vault_id: 'e5d4c3b2-a1f6-7890-bcde-f1234567890a'
})
};
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',
'project_id' => 'd4c3b2a1-f6e5-0987-dcba-fedcba098765',
'materialize' => true,
'company_id' => 'd4c3b2a1-f6e5-0987-dcba-fedcba098765',
'vault_id' => 'e5d4c3b2-a1f6-7890-bcde-f1234567890a'
]),
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 \"project_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"materialize\": true,\n \"company_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"vault_id\": \"e5d4c3b2-a1f6-7890-bcde-f1234567890a\"\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 \"project_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"materialize\": true,\n \"company_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"vault_id\": \"e5d4c3b2-a1f6-7890-bcde-f1234567890a\"\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 \"project_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"materialize\": true,\n \"company_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"vault_id\": \"e5d4c3b2-a1f6-7890-bcde-f1234567890a\"\n}"
response = http.request(request)
puts response.read_body{
"job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "chat/completions",
"status": "pending",
"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",
"chat_url": "https://app.gc.ai/chat/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"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>"
}
],
"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",
"status": "pending",
"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",
"chat_url": "https://app.gc.ai/chat/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"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>"
}
],
"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": {}
}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. | All |
| Document generation | Generate a new DOCX from a prompt. The generated file is returned via result.documents. | All |
| 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 |
| Vault query | Query documents and fields in an attached Contract Intelligence vault (requires vault_id) | All (subject to vault authorization) |
The following tools are not available via API (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: 60 requests/minute per organization (20 per API key). Exceeding the limit returns 429 with a Retry-After header.
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",
"project_id": "d4c3b2a1-f6e5-0987-dcba-fedcba098765",
"materialize": true,
"company_id": "d4c3b2a1-f6e5-0987-dcba-fedcba098765",
"vault_id": "e5d4c3b2-a1f6-7890-bcde-f1234567890a"
}
'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",
"project_id": "d4c3b2a1-f6e5-0987-dcba-fedcba098765",
"materialize": True,
"company_id": "d4c3b2a1-f6e5-0987-dcba-fedcba098765",
"vault_id": "e5d4c3b2-a1f6-7890-bcde-f1234567890a"
}
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',
project_id: 'd4c3b2a1-f6e5-0987-dcba-fedcba098765',
materialize: true,
company_id: 'd4c3b2a1-f6e5-0987-dcba-fedcba098765',
vault_id: 'e5d4c3b2-a1f6-7890-bcde-f1234567890a'
})
};
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',
'project_id' => 'd4c3b2a1-f6e5-0987-dcba-fedcba098765',
'materialize' => true,
'company_id' => 'd4c3b2a1-f6e5-0987-dcba-fedcba098765',
'vault_id' => 'e5d4c3b2-a1f6-7890-bcde-f1234567890a'
]),
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 \"project_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"materialize\": true,\n \"company_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"vault_id\": \"e5d4c3b2-a1f6-7890-bcde-f1234567890a\"\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 \"project_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"materialize\": true,\n \"company_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"vault_id\": \"e5d4c3b2-a1f6-7890-bcde-f1234567890a\"\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 \"project_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"materialize\": true,\n \"company_id\": \"d4c3b2a1-f6e5-0987-dcba-fedcba098765\",\n \"vault_id\": \"e5d4c3b2-a1f6-7890-bcde-f1234567890a\"\n}"
response = http.request(request)
puts response.read_body{
"job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"kind": "chat/completions",
"status": "pending",
"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",
"chat_url": "https://app.gc.ai/chat/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"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>"
}
],
"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",
"status": "pending",
"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",
"chat_url": "https://app.gc.ai/chat/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"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>"
}
],
"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
API key for authentication. Format: gcai_xxxxxxxxx
Create API keys in the GC AI app under Settings → API.
Headers
Optional RFC 7240 wait preference, for example wait=0. If both this header and the wait query parameter are supplied, they must match.
"wait=0"
Query Parameters
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.
x >= 00
Body
The user's message or prompt
1"What are the key terms to look for in a software license agreement?"
Optional uploaded file IDs to attach as context for this completion. Upload files first via POST /files.
["123e4567-e89b-12d3-a456-426614174000"]
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.
20["f9e8d7c6-b5a4-3210-fedc-ba0987654321"]
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.
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.
["b2c3d4e5-f6a7-4890-bcde-f12345678901"]
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.
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Optional project to file the chat into. Requires write access to the project. Discover projects via GET /projects.
This does two things: it grounds the completion in the project's files, and it files the chat under that project. Filing alone does not make the chat visible to people, because API chats stay out of chat history until they are materialized. Pass materialize: true (or call POST /chat/{id}/materialize afterwards) for the chat to appear under GET /projects/{id}/chats and in the GC AI web app. See Chat Visibility.
"d4c3b2a1-f6e5-0987-dcba-fedcba098765"
Surface this chat into chat history as part of the same call, instead of making a second request to POST /chat/{id}/materialize. Defaults to false, which keeps the chat headless.
Set this when a person is meant to open the chat. An organization-scoped key shares the materialized chat with the whole organization, so any member can open it and keep chatting in it. A user-scoped key keeps the chat owned by the caller.
On success the response includes chat_url. If that field is absent, materialization did not happen and the chat is still headless; retry with POST /chat/{id}/materialize using the returned chat_id. Continuing an already-materialized chat is a no-op. See Chat Visibility.
true
Optional company profile to ground the completion in, so the model has that company's context (industry, jurisdiction, regulations, risk posture). Discover company profiles via GET /company-profiles.
The company is fixed for the life of a chat. On a new chat, supply this to target a specific company (the only way to ground against a particular one in a multi-company organization); when omitted, a company is auto-resolved: user-scoped keys use the caller's active (default) company, and org-scoped keys use the organization's sole company, or none when there are several.
When continuing a chat with chat_id, omit this to reuse the chat's company. You may echo the same company_id, but a different one is rejected with 409 (start a new chat to use a different company).
"d4c3b2a1-f6e5-0987-dcba-fedcba098765"
Optional Contract Intelligence vault to ground the completion in, so the model can query that vault's documents and fields. Copy the vault ID from the GC AI web app.
Authorization: User-scoped keys need the Vault Chat permission, Contract Intelligence access, and view access to the vault. Organization-scoped keys need the organization to have Contract Intelligence entitlement; they can attach any vault in the organization because organization keys have no user identity for per-vault access checks.
The vault is fixed for the life of a chat. When continuing with chat_id, omit this to reuse the chat's vault. You may echo the same vault_id, but a different one is rejected with 409 (start a new chat to use a different vault).
When also filing into a project (project_id) that is linked to a vault, vault_id must match that vault. A different one is rejected with 409; omit vault_id to use the project's vault.
"e5d4c3b2-a1f6-7890-bcde-f1234567890a"
Response
Job completed within the effective wait window
Async job identifier
Stable job kind for this endpoint
chat/completions Current job status
pending, running, succeeded, failed, canceled Completion payload when the job has succeeded
Show child attributes
Show child attributes
Failure payload when the job has failed
Show child attributes
Show child attributes
ISO 8601 creation timestamp
ISO 8601 completion timestamp, or null when not terminal
Was this page helpful?