openapi: 3.0.3
info:
title: GC AI External Chat Profiles 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: Profiles
description: Personal and company profile endpoints
paths:
/me:
get:
summary: Identify the caller
description: 'Return the identity behind the API key making the request — the organization it belongs to, and, for user-scoped keys, the user it acts as.
Works with **either** a user-scoped key (`u:gcai_...`) or an org-scoped key (`gcai_...`). Org-scoped keys carry no user identity, so `user` is `null` for them. Use this to confirm which credential and account a request resolves to before calling `/me/profile` or `/company-profile`.'
operationId: getMe
tags:
- Profiles
security:
- ApiKeyAuth: []
responses:
'200':
description: The caller identity
content:
application/json:
schema:
$ref: '#/components/schemas/CallerIdentityResponse'
'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'
/me/profile:
get:
summary: Get your personal profile
description: 'Retrieve the calling user''s personal profile — the chat-context fields the web UI exposes under Settings → Profile. A profile that has never been saved is returned with default values.
Display name and avatar are managed by your identity provider, not this API, so they are not included.
Requires a **user-scoped** key (`u:gcai_...`); org-scoped keys carry no user identity and receive 403.'
operationId: getMyProfile
tags:
- Profiles
security:
- ApiKeyAuth: []
responses:
'200':
description: The personal profile
content:
application/json:
schema:
$ref: '#/components/schemas/PersonalProfileResponse'
'401':
description: Missing or malformed API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Key is not user-scoped, or the API key is invalid
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 your personal profile
description: 'Partially update the calling user''s personal profile. Omitted fields are left unchanged; nullable fields accept `null` to clear them. The profile is created on first write.
Display name and avatar are managed by your identity provider, not this API.
Requires a **user-scoped** key (`u:gcai_...`); org-scoped keys receive 403.'
operationId: updateMyProfile
tags:
- Profiles
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePersonalProfileRequest'
responses:
'200':
description: The updated personal profile
content:
application/json:
schema:
$ref: '#/components/schemas/PersonalProfileResponse'
'400':
description: No fields provided, or 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: Key is not user-scoped, or the API key is invalid
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'
/company-profile:
get:
summary: Get the company profile
description: 'Retrieve the organization''s company profile — the company context (industry, jurisdiction, regulations, risk posture) the AI uses to ground answers.
Readable with either a user-scoped or org-scoped key. With a user-scoped key, the user''s active (default) company is returned when one is set; otherwise the organization''s sole company is returned. An organization with multiple companies and no applicable default returns 409.'
operationId: getCompanyProfile
tags:
- Profiles
security:
- ApiKeyAuth: []
responses:
'200':
description: The company profile
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyProfileResponse'
'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: No company profile exists for this organization
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: The organization has more than one company profile, so the singular `/company-profile` resource cannot disambiguate. Manage multiple companies in the web UI.
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 the company profile
description: 'Partially update the organization''s company profile. Omitted fields are left unchanged; nullable fields accept `null` to clear them.
Requires an **org-scoped** key (`gcai_...`) — company context is organization-level configuration, so user-scoped keys receive 403. Creating the first company profile is done in the web UI.'
operationId: updateCompanyProfile
tags:
- Profiles
security:
- ApiKeyAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCompanyProfileRequest'
responses:
'200':
description: The updated company profile
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyProfileResponse'
'400':
description: No fields provided, or 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: Key is not org-scoped, or the API key is invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No company profile exists to update
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: The organization has more than one company profile, so the singular `/company-profile` resource cannot disambiguate. Manage multiple companies in the web UI.
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:
CallerIdentityResponse:
type: object
properties:
token_type:
type: string
enum:
- user
- organization
description: Scope of the API key making the request. `user` for personal keys (`u:gcai_...`), `organization` for org keys (`gcai_...`).
api_key_id:
type: string
description: Identifier of the API key used to authenticate the request
organization:
$ref: '#/components/schemas/CallerOrganization'
user:
type: object
nullable: true
properties:
id:
type: integer
description: Calling user identifier
email:
type: string
nullable: true
description: Calling user email, or null if unset
required:
- id
- email
description: The authenticated user, or null for org-scoped keys (which carry no user identity).
required:
- token_type
- api_key_id
- organization
- user
UpdateCompanyProfileRequest:
type: object
properties:
name:
type: string
minLength: 1
description: Company name (cannot be cleared)
dba_name:
type: string
nullable: true
description: Doing-business-as name. Send null to clear.
industry:
type: string
nullable: true
description: Industry sector. Send null to clear.
size:
type: string
nullable: true
description: Company size band. Send null to clear.
location:
type: string
nullable: true
description: Primary office location. Send null to clear.
incorporation_country:
type: string
nullable: true
description: Country of incorporation. Send null to clear.
incorporation_state:
type: string
nullable: true
description: State/province of incorporation. Send null to clear.
description:
type: string
nullable: true
description: Short company description. Send null to clear.
revenue:
type: string
nullable: true
description: Annual revenue band. Send null to clear.
legal_matters:
type: string
nullable: true
description: Typical legal matters. Send null to clear.
regulations:
type: string
nullable: true
description: Key regulations. Send null to clear.
risk_tolerance:
type: string
nullable: true
description: Risk tolerance level. Send null to clear.
additional_info:
type: string
nullable: true
description: Free-form additional context. Send null to clear.
customer_types:
type: array
nullable: true
items:
type: string
description: Types of customers served. Send null or [] to clear.
CallerOrganization:
type: object
properties:
id:
type: string
format: uuid
description: Organization the key belongs to
name:
type: string
nullable: true
description: Organization display name, or null if unset
required:
- id
- name
CompanyProfileResponse:
type: object
properties:
id:
type: string
format: uuid
description: Unique company profile identifier
name:
type: string
description: Company name
dba_name:
type: string
nullable: true
description: Doing-business-as name, or null
industry:
type: string
nullable: true
description: Industry sector, or null
size:
type: string
nullable: true
description: Company size band (e.g. "51-200"), or null
location:
type: string
nullable: true
description: Primary office location, or null
incorporation_country:
type: string
nullable: true
description: Country of incorporation, or null
incorporation_state:
type: string
nullable: true
description: State/province of incorporation, or null
description:
type: string
nullable: true
description: Short company description, or null
revenue:
type: string
nullable: true
description: Annual revenue band, or null
legal_matters:
type: string
nullable: true
description: Typical legal matters the company handles, or null
regulations:
type: string
nullable: true
description: Key regulations the company must comply with, or null
risk_tolerance:
type: string
nullable: true
description: Risk tolerance level (e.g. "Low"), or null
additional_info:
type: string
nullable: true
description: Free-form additional context for the AI, or null
customer_types:
type: array
nullable: true
items:
type: string
description: Types of customers the company serves, or null
created_at:
type: string
nullable: true
description: ISO 8601 creation timestamp
updated_at:
type: string
nullable: true
description: ISO 8601 last-update timestamp
required:
- id
- name
- dba_name
- industry
- size
- location
- incorporation_country
- incorporation_state
- description
- revenue
- legal_matters
- regulations
- risk_tolerance
- additional_info
- customer_types
- created_at
- updated_at
PersonalProfileResponse:
type: object
properties:
preferred_name:
type: string
nullable: true
description: Preferred name to use in chats, or null if unset
use_name_in_chats:
type: boolean
description: Whether the AI should address the user by name
role_title:
type: string
nullable: true
description: Job title or role (e.g. "General Counsel"), or null
jurisdiction_focus:
type: string
nullable: true
description: Primary jurisdiction the user practices in, or null
practice_areas:
type: array
items:
type: string
description: Practice areas the user focuses on (may be empty)
custom_instructions:
type: string
nullable: true
description: Custom instructions injected into every chat, or null
privilege_marking_enabled:
type: boolean
description: Whether AI responses include an attorney-client privilege disclaimer
privilege_marking_text:
type: string
nullable: true
description: The privilege disclaimer text, or null if unset
enter_to_submit:
type: boolean
description: Whether the chat composer submits on Enter instead of Cmd/Ctrl+Enter
document_author_name:
type: string
nullable: true
description: Name stamped on tracked changes when AI edits are applied, or null
enabled:
type: boolean
description: Whether the personal profile is active and applied to chats
created_at:
type: string
nullable: true
description: ISO 8601 creation timestamp, or null if never saved
updated_at:
type: string
nullable: true
description: ISO 8601 last-update timestamp, or null if never saved
required:
- preferred_name
- use_name_in_chats
- role_title
- jurisdiction_focus
- practice_areas
- custom_instructions
- privilege_marking_enabled
- privilege_marking_text
- enter_to_submit
- document_author_name
- enabled
- created_at
- updated_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
UpdatePersonalProfileRequest:
type: object
properties:
preferred_name:
type: string
nullable: true
maxLength: 100
description: Preferred name to use in chats. Send null to clear.
use_name_in_chats:
type: boolean
description: Whether the AI should address the user by name
role_title:
type: string
nullable: true
maxLength: 200
description: Job title or role. Send null to clear.
jurisdiction_focus:
type: string
nullable: true
maxLength: 255
description: Primary jurisdiction. Send null to clear.
practice_areas:
type: array
nullable: true
items:
type: string
maxLength: 100
maxItems: 20
description: Practice areas (max 20). Send null or [] to clear.
custom_instructions:
type: string
nullable: true
maxLength: 4000
description: Custom instructions for every chat. Send null to clear.
privilege_marking_enabled:
type: boolean
description: Whether AI responses include an attorney-client privilege disclaimer
privilege_marking_text:
type: string
nullable: true
maxLength: 200
description: Privilege disclaimer text. Send null to clear.
enter_to_submit:
type: boolean
description: Whether the chat composer submits on Enter instead of Cmd/Ctrl+Enter
document_author_name:
type: string
nullable: true
maxLength: 100
description: Name stamped on AI tracked changes. Send null to clear.
enabled:
type: boolean
description: Whether the personal profile is active
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.'