OpenAPI Specification
openapi: 3.0.3
info:
title: GC AI External Chat Folders 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: Folders
description: Folder management endpoints
paths:
/folders:
get:
summary: List folders
description: 'List all folders accessible to the authenticated user, returned as a flat list with full paths.
Pass `scope` to filter to one of the three top-level meta-collections shown in the GC AI UI:
- `my-files`: folders rooted in the user''s personal "My Files" tree
- `shared-with-me`: folders explicitly shared with the user by other users
- `organization`: folders rooted in the organization''s "Organization Files" tree
Filtering by `scope` requires a user-scoped API key (`u:gcai_...`).'
operationId: listFolders
tags:
- Folders
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 search on folder name or description. System-owned collection types (my-files, org-files, etc.) are excluded from results. Composes with `scope`.
example: contracts
required: false
description: Case-insensitive substring search on folder name or description. System-owned collection types (my-files, org-files, etc.) are excluded from results. Composes with `scope`.
name: q
in: query
- schema:
type: string
enum:
- my-files
- shared-with-me
- organization
description: Filter folders to a single meta-collection. Requires a user-scoped API key.
example: my-files
required: false
description: Filter folders to a single meta-collection. Requires a user-scoped API key.
name: scope
in: query
responses:
'200':
description: List of folders
content:
application/json:
schema:
$ref: '#/components/schemas/FolderListResponse'
'400':
description: Invalid scope parameter
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: Scope filter requires a user-scoped 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 folder
description: 'Create a new folder for organizing files. Folders can be nested by specifying a `parent_folder_id`.
Org-scoped keys can create folders under non-access-controlled parents. The `scope` parameter requires a user-scoped key.'
operationId: createFolder
tags:
- Folders
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFolderRequest'
responses:
'201':
description: Folder created
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
'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: Parent folder 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'
/folders/{id}:
get:
summary: Get a folder
description: Retrieve a single folder by ID.
operationId: getFolder
tags:
- Folders
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
format: uuid
description: The folder ID
required: true
description: The folder ID
name: id
in: path
responses:
'200':
description: Folder details
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
'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: Folder not found
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 folder
description: 'Update a folder''s name, description, parent, or access-control flag. At least one field must be provided. System folders cannot be modified.
Org-scoped keys can update non-access-controlled folders.'
operationId: updateFolder
tags:
- Folders
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
format: uuid
description: The folder ID
required: true
description: The folder ID
name: id
in: path
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFolderRequest'
responses:
'200':
description: Folder updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Folder'
'400':
description: Invalid request body, system folder, or invalid parent
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: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Folder or destination folder not found
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 folder
description: 'Delete a folder. By default, only empty folders can be deleted; pass `?recursive=true` to delete a folder along with all of its subfolders and files. System folders cannot be deleted.
Org-scoped keys can delete non-access-controlled folders.'
operationId: deleteFolder
tags:
- Folders
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
format: uuid
description: The folder ID
required: true
description: The folder ID
name: id
in: path
- schema:
type: string
enum:
- 'true'
- 'false'
description: When `true`, recursively delete subfolders and files. Defaults to `false`.
example: 'true'
required: false
description: When `true`, recursively delete subfolders and files. Defaults to `false`.
name: recursive
in: query
responses:
'204':
description: Folder deleted successfully
'400':
description: Invalid folder ID or system folder
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: Recursive delete blocked by insufficient descendant access or access-controlled descendants
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Folder not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Folder is not empty and `recursive` was not set
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'
/folders/{id}/children:
get:
summary: List a folder's children
description: 'List the direct children of a folder. The response items are a discriminated union of subfolders and files: subfolders are returned first (alphabetical), then files (alphabetical).'
operationId: listFolderChildren
tags:
- Folders
security:
- ApiKeyAuth: []
parameters:
- schema:
type: string
format: uuid
description: The folder ID
required: true
description: The folder ID
name: id
in: path
responses:
'200':
description: Direct children of the folder
content:
application/json:
schema:
$ref: '#/components/schemas/FolderChildrenResponse'
'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: Folder not found
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'
components:
schemas:
Folder:
type: object
properties:
id:
type: string
format: uuid
description: Unique folder identifier
name:
type: string
description: Folder name
description:
type: string
nullable: true
description: Folder description, or null if unset
path:
type: string
description: Path through ancestors visible to the requester. Inaccessible ancestors are skipped, so this may not reflect absolute depth. Use `parent_folder_id` to traverse hierarchy.
example: /My Files/Contracts
parent_folder_id:
type: string
nullable: true
format: uuid
description: Parent folder ID, or null for root
folder_type:
type: string
description: Folder type (custom, my-files, etc.)
created_at:
type: string
description: ISO 8601 creation timestamp
required:
- id
- name
- description
- path
- parent_folder_id
- folder_type
- created_at
FolderChildrenResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/FolderChild'
description: Direct children of the folder. Subfolders first (alphabetical), then files (alphabetical).
required:
- items
FolderListResponse:
type: object
properties:
folders:
type: array
items:
$ref: '#/components/schemas/Folder'
pagination:
$ref: '#/components/schemas/Pagination'
required:
- folders
- pagination
FolderChild:
oneOf:
- allOf:
- $ref: '#/components/schemas/Folder'
- type: object
properties:
type:
type: string
enum:
- folder
required:
- type
- allOf:
- $ref: '#/components/schemas/File'
- type: object
properties:
type:
type: string
enum:
- file
required:
- type
CreateFolderRequest:
type: object
properties:
name:
type: string
minLength: 2
description: Folder name (min 2 characters)
example: Q4 Contracts
description:
type: string
description: Optional description
parent_folder_id:
type: string
format: uuid
description: Parent folder ID. Mutually exclusive with `scope`. If both are omitted, creates a top-level folder.
scope:
type: string
enum:
- my-files
- organization
description: Create the folder at the root of a meta-collection. Mutually exclusive with `parent_folder_id`. `shared-with-me` is not valid for create.
example: my-files
required:
- name
Pagination:
type: object
properties:
limit:
type: number
description: Page size
offset:
type: number
description: Current offset
has_more:
type: boolean
description: Whether more results exist
required:
- limit
- offset
- has_more
File:
type: object
properties:
id:
type: string
format: uuid
description: Unique file identifier
name:
type: string
description: Original filename
size:
type: number
description: File size in bytes
content_type:
type: string
description: MIME type of the file
status:
type: string
enum:
- extracting
- embedding
- ready
- failed
description: Current processing status
created_at:
type: string
description: ISO 8601 creation timestamp
required:
- id
- name
- size
- content_type
- status
- created_at
Error:
type: object
properties:
error:
type: string
description: Error message
code:
type: string
description: Machine-readable error code present on some errors (e.g. `RATE_LIMITED`, `INSUFFICIENT_CREDITS`, `TRIAL_NOT_STARTED`, `BILLING_NOT_CONFIGURED`). Branch on this rather than the human-readable `error` string.
message:
type: string
description: Additional error details
details:
type: object
additionalProperties:
nullable: true
description: Validation error details (for 400 errors)
required:
- error
UpdateFolderRequest:
type: object
properties:
name:
type: string
minLength: 2
description: New folder name (minimum 2 characters)
description:
type: string
description: New folder description
parent_folder_id:
type: string
format: uuid
description: Target parent folder ID. The destination must not be the folder itself or one of its descendants.
is_access_controlled:
type: boolean
description: Whether the folder requires explicit access grants
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.'