Create Chat Completion

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

Async behavior

Set wait=0 or Prefer: wait=0 to enqueue the completion and return immediately with a pending job envelope. Otherwise the endpoint blocks up to the effective wait window before returning.

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_id)	User-scoped only

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

Tool	Reason unavailable
Document generation	Produces a downloadable file
Slide generation	Produces a downloadable file
Diagrams	Produces an inline visual
Email drafting	Produces a structured email object
Document editing	Requires an active Word session
Interactive clarification	Requires a back-and-forth channel with the caller

POST /chat/completions

Create chat completion

cURL

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_id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321"
}
'

200

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "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"
  },
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "created_at": "<string>",
  "completed_at": "<string>"
}

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_id · string<uuid>

Optional playbook ID to ground the completion in. The model uses the playbook's checks and guidance to structure its review of the attached files. Discover playbooks via GET /playbooks.

Requires a user-scoped API key (u:gcai_...).

Example:

"f9e8d7c6-b5a4-3210-fedc-ba0987654321"

Response

200

application/json

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 · required

Completion payload when the job has succeeded

Show child attributes

error · object · 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