Copilot API Documentation
- Last updated
- Save as PDF
This article describes a GA-ready feature, but the feature is not enabled by default. If you would like early access, please submit a support ticket. If you choose not to access this feature early, they will be available in your tenants automatically with the upcoming major release.
This article helps Admins integrate Gainsight Copilot with external systems using REST APIs.
Overview
The Copilot External API lets you send natural language queries to Gainsight Copilot from any external application and receive AI-generated answers in real time.
Use this API to connect external systems or AI platforms to Gainsight. For example, you can integrate this API with an AI agent platform such as Microsoft Copilot Studio to allow users to ask customer-related questions and retrieve insights from Gainsight data such as Timeline activities, Company records, CTAs and Tasks (Cockpit), Success Plans, and Scorecards.
When a query is sent, the API returns:
- A natural language answer.
- Structured data (if the query requires tabular output).
- A success or failure status.
- Returns the complete response in a single request.
- Does not remember previous requests.
- Executes all queries using the Super Admin’s permissions rather than individual user permissions.
- Works only with the access key created for your Gainsight instance.
Prerequisites
Before making your first API call, confirm the following with your Gainsight Super Admin:
- The feature flag is enabled for your Gainsight environment.
- A Super Admin has generated a valid Gainsight Access Key. For more information on generating a valid Gainsight Access Key, refer to the Generate REST API Key article.
- You have the correct base URL for your Gainsight environment.
- You have network access to call Gainsight REST APIs.
- Before enabling this feature, ensure that Gainsight Copilot or Gainsight's AI Agent in Slack is already enabled in your Gainsight instance. If it is not enabled, navigate to Administration > Gainsight AI > AI Settings. The new feature works only after one of these capabilities is enabled.
- To enable Copilot, turn on the Gainsight Copilot toggle.
- To enable Gainsight's AI Agent in Slack, turn on the Gainsight's AI Agent in Slack toggle.
Authentication
The Copilot External API uses Access Key authentication. Every request must include a valid Gainsight Access Key in the request header. The access key is generated by a Super Admin and authenticates requests at the Gainsight instance level. All queries execute using the Super Admin’s permissions, and user-level permissions or portfolio filters are not applied.
Headers
Include the following headers in every request to authenticate and format the API call correctly.
| Key | Value |
|---|---|
| accesskey | <gainsight-access-key> |
| Content-Type | application/json |
Throttling Limits
Copilot External API follows the standard throttling limits for synchronous Gainsight APIs.
For detailed rate limits and throttling behavior, refer to the Throttling Limits section in the Gainsight Custom Object API article.
Base URL
All Copilot External API requests are scoped to your Gainsight instance. You must use the base URL associated with your Gainsight environment when sending API requests.
There is no global or shared endpoint for Copilot External API. Using an incorrect base URL results in authentication or authorization errors.
Format
https://<your-gainsight-base-url>
Example Base URL
https://integration-demo-xyz.develgs.com:9015
All API endpoints described in this document must be appended to your base URL.
Example Endpoint: POST https://<your-gainsight-base-url>/v1/copilot-external/chat_sync
IMPORTANT
- Each Gainsight instance has its own base URL.
- The access key works only with the base URL of the instance where it was created.
- Ensure the base URL matches your production or sandbox environment as applicable.
Chat Sync API
The Chat Sync API is the only endpoint exposed for Copilot as an External API.
Method
POST
Endpoint URL
/v1/copilot-external/chat_sync
Example: POST https://<your-gainsight-base-url>/v1/copilot-external/chat_sync
Sample Request Body
{
"query": "what is a cta"
}
Request Parameters
Only the query parameter is required. No additional parameters such as conversation ID or pagination settings are supported.
| Field | Type | Required | Description |
|---|---|---|---|
| query | String | Yes | The user query sent to Copilot |
Sample Success Response
{
"result": true,
"answer": "...",
"data": {}
}
Sample Failure Response
{
"result": false,
"answer": "",
"data": {}
}
Response Fields
| Field | Description |
|---|---|
| result | Indicates whether the request executed successfully (true or false) |
| answer | Natural language response generated by Copilot |
| data | Structured dataset returned when the query requires tabular output |
Sample cURL Request
curl --location 'https://integration-demo-copilot3.develgs.com:9015/v1/copilot-external/chat_sync' \
--header 'accesskey: <gainsight-access-key>' \
--header 'Accept: application/json, text/event-stream' \
--header 'Content-Type: application/json' \
--data '{
"query": "what is a cta"
}'
Sample Response
{
"result": true,
"answer": "A CTA (Call to Action) in Gainsight is a system alert—either created manually or automatically—that drives work for Customer Success...",
"data": {},
"query_id": "c1266e0d-4aa4-453e-930e-30088c5148d8"
}
Response Behavior and Limitations
The Copilot External API returns responses based on the type and complexity of the query. The response format may include natural language output, structured data, or both.
Response Behavior
- The answer field contains the AI-generated natural language response.
- The data field contains structured output when the query requires tabular results, such as lists of CTAs or company records.
- Both answers and data may be populated for complex queries.
- The API returns only the final response and does not expose internal reasoning steps.
- Citations or UI references displayed in the Gainsight application are not included in the API response.
- Each request is processed independently.
- A query_id is included in the response to help track and identify specific queries. This is useful for logging support tickets and debugging in case of issues with a response.
Limitations
- Pagination and record streaming are not supported.
- The API does not remember previous requests.