OpenAPI Specification
openapi: 3.0.3
info:
title: GC AI External Chat Projects 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**.
## Multi-turn Conversations
Conversations can span multiple turns: pass the `chat_id` returned by a completion back on your next request to continue the same chat. See [Multi-turn Conversations](/api-reference/concepts/multi-turn).
## Current Limitations
The following is not yet available via API:
- **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
tags:
- name: Projects
description: Project management endpoints
paths:
/projects:
get:
summary: List projects
description: 'List projects accessible to the caller, optionally filtered by name.
With a user-scoped key (`u:gcai_...`), the user sees projects they created, projects shared with them, and non-access-controlled projects. With an org-scoped key (`gcai_...`), only non-access-controlled (org-wide) projects are returned.'
operationId: listProjects
tags:
- Projects
security:
- ApiKeyAuth: []
parameters:
- schema:
type: integer
minimum: 1
maximum: 500
default: 100
description: Max items to return (default 100, max 500)
required: false
description: Max items to return (default 100, max 500)
name: limit
in: query
- schema:
type: integer
nullable: true
minimum: 0
default: 0
description: Number of items to skip (default 0)
required: false
description: Number of items to skip (default 0)
name: offset
in: query
- schema:
type: string
description: Case-insensitive substring match on project name
required: false
description: Case-insensitive substring match on project name
name: search
in: query
responses:
'200':
description: Paginated list of projects
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectListResponse'
'400':
description: Result set too large for offset pagination
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
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded. See [Rate Limits](/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
headers:
Retry-After:
schema:
type: string
description: Seconds to wait before retrying after a rate-limit block.
example: '60'
required: true
description: Seconds to wait before retrying after a rate-limit block.
RateLimit-Limit:
schema:
type: string
description: Request quota for the applicable window.
example: '3'
required: true
description: Request quota for the applicable window.
RateLimit-Remaining:
schema:
type: string
description: Requests remaining in the current window.
example: '0'
required: true
description: Requests remaining in the current window.
RateLimit-Reset:
schema:
type: string
description: Seconds until the quota resets.
example: '60'
required: true
description: Seconds until the quota resets.
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'
post:
summary: Create a project
description: 'Create a new project to group files, folders, and chats around a single matter (deal, vendor, or program).
With a user-scoped key, the caller is recorded as the project creator and granted admin access. With an org-scoped key, `creatorId` is null and the project defaults to non-access-controlled (org-wide).'
operationId: createProject
tags:
- Projects
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProjectRequest'
responses:
'201':
description: Project created
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
'400':
description: Invalid request body
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
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded. See [Rate Limits](/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
headers:
Retry-After:
schema:
type: string
description: Seconds to wait before retrying after a rate-limit block.
example: '60'
required: true
description: Seconds to wait before retrying after a rate-limit block.
RateLimit-Limit:
schema:
type: string
description: Request quota for the applicable window.
example: '3'
required: true
description: Request quota for the applicable window.
RateLimit-Remaining:
schema:
type: string
description: Requests remaining in the current window.
example: '0'
required: true
description: Requests remaining in the current window.
RateLimit-Reset:
schema:
type: string
description: Seconds until the quota resets.
example: '60'
required: true
description: Seconds until the quota resets.
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'
/projects/{id}:
get:
summary: Get a project
description: Retrieve a single project by ID. Returns the caller's access level alongside the project metadata.
operationId: getProject
tags:
- Projects
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
format: uuid
description: The project ID
required: true
description: The project ID
name: id
in: path
responses:
'200':
description: Project details
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
'401':
description: Missing or malformed API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Project not found or access denied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded. See [Rate Limits](/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
headers:
Retry-After:
schema:
type: string
description: Seconds to wait before retrying after a rate-limit block.
example: '60'
required: true
description: Seconds to wait before retrying after a rate-limit block.
RateLimit-Limit:
schema:
type: string
description: Request quota for the applicable window.
example: '3'
required: true
description: Request quota for the applicable window.
RateLimit-Remaining:
schema:
type: string
description: Requests remaining in the current window.
example: '0'
required: true
description: Requests remaining in the current window.
RateLimit-Reset:
schema:
type: string
description: Seconds until the quota resets.
example: '60'
required: true
description: Seconds until the quota resets.
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'
patch:
summary: Update a project
description: 'Update a project''s name, description, or custom instructions. Only the fields you supply are changed; omitted fields are left untouched. Pass `null` for `description` or `custom_instructions` to clear them.
Requires write access to the project. Org-scoped keys can update non-access-controlled projects.'
operationId: updateProject
tags:
- Projects
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
format: uuid
description: The project ID
required: true
description: The project ID
name: id
in: path
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProjectRequest'
responses:
'200':
description: Updated project
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectResponse'
'400':
description: Invalid request body
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
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Project not found or insufficient write access
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded. See [Rate Limits](/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
headers:
Retry-After:
schema:
type: string
description: Seconds to wait before retrying after a rate-limit block.
example: '60'
required: true
description: Seconds to wait before retrying after a rate-limit block.
RateLimit-Limit:
schema:
type: string
description: Request quota for the applicable window.
example: '3'
required: true
description: Request quota for the applicable window.
RateLimit-Remaining:
schema:
type: string
description: Requests remaining in the current window.
example: '0'
required: true
description: Requests remaining in the current window.
RateLimit-Reset:
schema:
type: string
description: Seconds until the quota resets.
example: '60'
required: true
description: Seconds until the quota resets.
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'
delete:
summary: Delete a project
description: 'Delete a project. Files, folders, and chats linked to the project are detached, not deleted — they remain in the organization and can be reattached elsewhere.
Requires admin access to the project. Org-scoped keys can delete non-access-controlled projects.'
operationId: deleteProject
tags:
- Projects
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
format: uuid
description: The project ID
required: true
description: The project ID
name: id
in: path
responses:
'204':
description: Project deleted
'401':
description: Missing or malformed API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Project not found or insufficient access
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded. See [Rate Limits](/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
headers:
Retry-After:
schema:
type: string
description: Seconds to wait before retrying after a rate-limit block.
example: '60'
required: true
description: Seconds to wait before retrying after a rate-limit block.
RateLimit-Limit:
schema:
type: string
description: Request quota for the applicable window.
example: '3'
required: true
description: Request quota for the applicable window.
RateLimit-Remaining:
schema:
type: string
description: Requests remaining in the current window.
example: '0'
required: true
description: Requests remaining in the current window.
RateLimit-Reset:
schema:
type: string
description: Seconds until the quota resets.
example: '60'
required: true
description: Seconds until the quota resets.
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'
/projects/{id}/files:
post:
summary: Attach a file to a project
description: 'Attach an already-uploaded file to a project. The file remains in its current folder; this only records the project link.
Requires write access to the project and read access to the file. Org-scoped keys can attach non-access-controlled files to non-access-controlled projects.'
operationId: attachFileToProject
tags:
- Projects
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
format: uuid
description: The project ID
required: true
description: The project ID
name: id
in: path
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AttachFileRequest'
responses:
'204':
description: File attached (idempotent, repeat calls are no-ops)
'400':
description: Invalid request body
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
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Project not found, file not found, or insufficient write access
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded. See [Rate Limits](/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
headers:
Retry-After:
schema:
type: string
description: Seconds to wait before retrying after a rate-limit block.
example: '60'
required: true
description: Seconds to wait before retrying after a rate-limit block.
RateLimit-Limit:
schema:
type: string
description: Request quota for the applicable window.
example: '3'
required: true
description: Request quota for the applicable window.
RateLimit-Remaining:
schema:
type: string
description: Requests remaining in the current window.
example: '0'
required: true
description: Requests remaining in the current window.
RateLimit-Reset:
schema:
type: string
description: Seconds until the quota resets.
example: '60'
required: true
description: Seconds until the quota resets.
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'
get:
summary: List files on a project
description: List files directly linked to a project. Files reachable only via a linked folder are not included; list those folders separately with `GET /projects/{id}/folders`.
operationId: listProjectFiles
tags:
- Projects
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
format: uuid
description: The project ID
required: true
description: The project ID
name: id
in: path
- schema:
type: integer
minimum: 1
maximum: 500
default: 100
description: Max items to return (default 100, max 500)
required: false
description: Max items to return (default 100, max 500)
name: limit
in: query
- schema:
type: integer
nullable: true
minimum: 0
default: 0
description: Number of items to skip (default 0)
required: false
description: Number of items to skip (default 0)
name: offset
in: query
responses:
'200':
description: Paginated list of files
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectFileListResponse'
'401':
description: Missing or malformed API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Project not found or access denied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded. See [Rate Limits](/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
headers:
Retry-After:
schema:
type: string
description: Seconds to wait before retrying after a rate-limit block.
example: '60'
required: true
description: Seconds to wait before retrying after a rate-limit block.
RateLimit-Limit:
schema:
type: string
description: Request quota for the applicable window.
example: '3'
required: true
description: Request quota for the applicable window.
RateLimit-Remaining:
schema:
type: string
description: Requests remaining in the current window.
example: '0'
required: true
description: Requests remaining in the current window.
RateLimit-Reset:
schema:
type: string
description: Seconds until the quota resets.
example: '60'
required: true
description: Seconds until the quota resets.
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'
/projects/{id}/files/{fileId}:
delete:
summary: Detach a file from a project
description: 'Remove the link between a file and a project. The file itself is not deleted — it stays in the organization and can be reattached later. Idempotent: detaching a file that is not attached is a no-op.
Requires write access to the project. Org-scoped keys can detach files from non-access-controlled projects.'
operationId: detachFileFromProject
tags:
- Projects
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
format: uuid
description: The project ID
required: true
description: The project ID
name: id
in: path
- schema:
type: string
format: uuid
description: The file ID
required: true
description: The file ID
name: fileId
in: path
responses:
'204':
description: File detached (idempotent, repeat calls are no-ops)
'401':
description: Missing or malformed API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Project not found or insufficient write access
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Rate limit exceeded. See [Rate Limits](/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
headers:
Retry-After:
schema:
type: string
description: Seconds to wait before retrying after a rate-limit block.
example: '60'
required: true
description: Seconds to wait before retrying after a rate-limit block.
RateLimit-Limit:
schema:
type: string
description: Request quota for the applicable window.
example: '3'
required: true
description: Request quota for the applicable window.
RateLimit-Remaining:
schema:
type: string
description: Requests remaining in the current window.
example: '0'
required: true
description: Requests remaining in the current window.
RateLimit-Reset:
schema:
type: string
description: Seconds until the quota resets.
example: '60'
required: true
description: Seconds until the quota resets.
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'
/projects/{id}/folders:
get:
summary: List folders linked to a project
description: List folders linked to a project. To enumerate the contents of a folder, call `GET /folders/{id}/children`.
operationId: listProjectFolders
tags:
- Projects
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
format: uuid
description: The project ID
required: true
description: The project ID
name: id
in: path
- schema:
type: integer
minimum: 1
maximum: 500
default: 100
description: Max items to return (default 100, max 500)
required: false
description: Max items to return (default 100, max 500)
name: limit
in: query
- schema:
type: integer
nullable: true
minimum: 0
default: 0
description: Number of items to skip (default 0)
required: false
description:
# --- truncated at 32 KB (61 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gc-ai/refs/heads/main/openapi/gc-ai-projects-api-openapi.yml