> ## 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.
# 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](/api-reference/concepts/async-jobs) for how waiting, polling, and the envelope work.
## 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`) | 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 |
|---|---|
| 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 |
## OpenAPI
````yaml POST /chat/completions
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**.
## Current Limitations
The API is optimized for single-turn completions. The following are not yet
available via API:
- **Multi-turn conversations**: each request is independent
- **Interactive clarification**: the model cannot pause to ask the caller a
follow-up question; the `askUserQuestions` tool is disabled on the API
surface in beta
## 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: Chat
description: AI chat completion endpoints
- name: Files
description: File upload and management endpoints
- name: Folders
description: Folder management endpoints
- name: Playbooks
description: Playbook review endpoints
- name: Projects
description: Project management endpoints
- name: Utility
description: Health check and connectivity endpoints
paths:
/chat/completions:
post:
tags:
- Chat
summary: Create chat completion
description: >-
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](/api-reference/concepts/async-jobs) for how waiting, polling,
and the envelope work.
## 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`) | 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 |
|---|---|
| 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 |
operationId: createChatCompletion
parameters:
- 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/ChatCompletionRequest'
responses:
'200':
description: Job completed within the effective wait window
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionResponse'
'202':
description: >-
Job accepted but not yet complete, including fire-and-forget
requests
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionResponse'
'400':
description: Invalid request body or invalid/conflicting wait controls
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 or playbook review not enabled for this account
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: One or more `file_ids` or the `playbook_id` were not found
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:
ChatCompletionRequest:
type: object
properties:
message:
type: string
minLength: 1
description: The user's message or prompt
example: What are the key terms to look for in a software license agreement?
file_ids:
type: array
items:
type: string
format: uuid
description: >-
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:
type: string
format: uuid
description: >-
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`.
Org-scoped keys can use org-visible and official playbooks.
example: f9e8d7c6-b5a4-3210-fedc-ba0987654321
required:
- message
ChatCompletionResponse:
type: object
properties:
job_id:
type: string
format: uuid
description: Async job identifier
kind:
type: string
enum:
- chat/completions
description: Stable job kind for this endpoint
status:
type: string
enum:
- pending
- running
- succeeded
- failed
- canceled
description: Current job status
result:
type: object
nullable: true
properties:
result:
type: string
description: The AI-generated response text
example: >-
When reviewing a software license agreement, key terms to
examine include:
1. **License Grant** - Understand the scope of rights granted...
chat_id:
type: string
format: uuid
description: >-
The chat ID. API chats stay out of chat history until you
materialize them. Pass this ID to `POST /chat/{id}/materialize`
to surface the chat. See [Chat
Visibility](/api-reference/concepts/chat-visibility).
required:
- result
- chat_id
description: Completion payload when the job has succeeded
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
message:
type: string
description: Additional error details
details:
type: object
additionalProperties:
nullable: true
description: Validation error details (for 400 errors)
required:
- error
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.
````