LLMs.txt: Complete documentation index for AI agents
Spotter agent conversation sharing APIs
Cloud
26.9.0.clCloud (Latest)
26.8.0.clCloud
26.7.0.clCloud
Software
26.3.0.swSoftware (Latest)
10.10.0.swSoftware
10.1.0.swSoftware
GitHub

Spotter agent conversation sharing APIs

You can share a Spotter conversation with other users and groups and manage shared content programmatically using REST API endpoints.

Supported endpoints🔗

POST /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share
Shares a saved Spotter conversation, grants or revokes access to a shared conversation for one or more principals.
Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.

GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content
Returns the read-only view of the shared conversation, including messages and associated answers.
Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.

GET /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info
Returns sharing state and metadata, and the list of principals that can access the shared content.
Available on ThoughtSpot Cloud instances from 26.9.0.cl onwards.

For information about creating, saving, and managing saved conversation, see Spotter agent conversation APIs and APIs for managing saved conversations.

Required privileges🔗

  • To use these APIs, you need the CAN_USE_SPOTTER (Can use Spotter) privilege.

  • To share a conversation or view the sharing status, you must be the owner of the conversation. Only the user who created the conversation can manage its share access.

  • To retrieve shared content, you must be the conversation owner or a principal (user or group) that has been granted access.

Note

The shared view is a read-only snapshot of the conversation at the time of sharing. Recipients cannot send messages or modify the conversation.

Share a conversation🔗

To share a conversation with other ThoughtSpot users and groups, refresh shared content, or revoke access, send a POST request to the /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share endpoint. When principals are added, ThoughtSpot creates a read-only shared view of the conversation from its current state.

The conversation to share is identified by the conversation_identifier URL path parameter. In your API request, you must include the GUID of the saved Spotter conversation as a path parameter and add the attributes to grant or revoke access in the request body.

Note

Do not include the same principal identifiers in both grant and revoke arrays in the same request.

Request parameters🔗

ParameterDescription

grant

Array of strings. Array of principals to grant access to the conversation specified in the request. Specify principal_identifier and principal_type. Specify the principal type, name or GUID of the intended recipients. All recipients are granted a READ_ONLY access.

revoke

Array of strings. Principals to revoke access from. Specify principal_identifier and principal_type. Specify the principal type, name or GUID of the recipients to revoke access from.

refresh_shared_content

Boolean. When set to true, ThoughtSpot regenerates the shared view from the latest conversation state, even if a shared view already exists. When false, reuses the existing shared view. Default is false.

Request examples🔗

Grant access to a conversation
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "refresh_shared_content": false,
  "grant": [
    { "principal_identifier": "user-001", "principal_type": "USER" },
    { "principal_identifier": "group-001", "principal_type": "USER_GROUP" }
  ],
  "revoke": []
}'
Revoke access granted to a shared conversation
curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "refresh_shared_content": false,
  "grant": [],
  "revoke": [
    { "principal_identifier": "user-001", "principal_type": "USER" },
    { "principal_identifier": "group-001", "principal_type": "USER_GROUP" }
  ]
}'
Refresh shared content

To regenerate the shared snapshot for existing recipients without changing access, set refresh_shared_content to true with empty grant and revoke arrays.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "refresh_shared_content": true,
  "grant": [],
  "revoke": []
}'
Refresh shared content and update access details

To update access and refresh the snapshot in a single call, combine refresh_shared_content: true with the recipient details in the grant or revoke array.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/share' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "refresh_shared_content": true,
  "grant": [
    { "principal_identifier": "user-002", "principal_type": "USER" },
    { "principal_identifier": "group-002", "principal_type": "USER_GROUP" }
  ]
}'

API response🔗

If the request is successful, ThoughtSpot returns a 204 response code.

Get shared conversation content🔗

To retrieve the full read-only view of a shared conversation, including ordered messages and data source metadata, send a GET request to the /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content endpoint. This endpoint is accessible to the conversation owner and any principal that has been granted access.

Use this endpoint to render a shared conversation in a UI or to retrieve its content for post-processing.

Request parameters🔗

ParameterTypeDescription

conversation_identifier

String

The unique ID of the source conversation.

Example request🔗

curl -X GET \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-shared-content' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json'

API response🔗

If the request is successful, the API returns the shared conversation content with the following fields:

{
  "conversation_id": "conv-abc-123",
  "shared_conversation_id": "snap-xyz-456",
  "conversation_title": "Sales by Region Q1",
  "creator_user_id": "5d3e6cc7-2f4a-4b0e-9a1c-8f2b6d4e7a10",
  "data_sources": [{ "id": "ds-001", "name": "Retail Sales" }],
  "analyst_ids": ["spot-7f2a"],
  "messages": [
    {
      "message_id": "node-u-01",
      "timestamp_in_millis": 1744000000000,
      "user_prompt": {
        "message": {
          "message_id": "msg-u-01",
          "content": "Show me revenue by region."
        },
        "attachments": []
      },
      "response_items": [
        {
          "type": "tool_call",
          "tool_call_id": "toolu-01",
          "tool_name": "search_datasets",
          "step_title": "Searching datasets",
          "arguments": { "query": "revenue by region" },
          "timestamp_in_millis": 1744000001000,
          "is_thinking": false
        },
        {
          "type": "answer",
          "answer_id": "ans-01",
          "tool_call_id": "toolu-02",
          "tool_name": "fetch_and_visualize",
          "step_title": "Visualizing",
          "timestamp_in_millis": 1744000004000,
          "is_thinking": false
        },
        {
          "type": "text",
          "content": "Revenue is highest in APAC.",
          "content_type": "TEXT_MARKDOWN",
          "timestamp_in_millis": 1744000005000,
          "is_thinking": false,
          "step_title": null,
          "file_reference": null
        }
      ]
    }
  ],
  "code_execution_files": [
    {
      "file_id": "revenue_by_region.csv",
      "display_name": "revenue_by_region.csv",
      "file_type": "csv",
      "created_time_in_millis": 1744027200000,
      "expired": false
    }
  ]
}

Response fields🔗

FieldDescription

conversation_id

String. Conversation ID sent in the request parameter.

shared_conversation_id

String. Id of the shared snapshot. This is not the same as conversation_id. Pass this value as the conversation_identifier parameter in loadAnswer calls. This value changes each time the snapshot is refreshed via the share endpoint with refresh_shared_content: true.

conversation_title

String. Display title of the conversation. null if no title was set.

creator_user_id

String. Id of the user who created and shared the conversation. This is the original creator, not the caller retrieving the shared content.

data_sources

Array of strings. Array of data sources used by the conversation. Each entry includes the id and display name of the data source.

analyst_ids

Array of strings. Array of the identifiers of the AI analysts the conversation ran against. An analyst is a purpose-built agent configured over a set of data sources, with its own instructions and access rules. An empty array is returned if the conversation is not associated with any analyst.

messages

Array of conversation messages. Ordered conversation messages, from oldest to newest. The structure is the same as returned by the get conversation endpoint. An empty array is returned when the conversation has no messages.

code_execution_files

Array of code execution files. Sanitized metadata for files generated by the code execution tool. Each entry in the code_execution_files array contains the following attributes:

* file_id. String. Unique identifier of the file. * display_name. String. Name of the file. * file_type. String. File type, such as csv, pdf, or png. * created_time_in_millis. Long. Milliseconds since Unix epoch when the file was created. * expired.Boolean. When true, the underlying file is no longer retrievable from code execution storage. Disable download and preview options in your UI for expired files.

If there are no code execution steps, an empty array is returned.

Load answer payloads from a shared view🔗

The full answer payload is not embedded in messages. Each answer response item in messages[].response_items contains an answer_id field. To retrieve the full answer payload, call loadAnswer with:

  • conversation_identifier: the shared_conversation_id value from this response.

  • answer_id: the answer_id from the answer response item.

Important

shared_conversation_id is not the same as conversation_id. It identifies the shared snapshot, which is a separate internal object from the source conversation. Always use the shared_conversation_id value as the conversation_identifier parameter when calling loadAnswer to hydrate answers from a shared view. Because this value changes each time the snapshot is refreshed, re-fetch the shared content to get the current value before calling loadAnswer.

Get share information🔗

To view the current share state of a conversation you own, send a GET request to the /api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info endpoint. The response shows whether the shared view reflects the latest conversation content and lists the principals that currently have access.

Use this endpoint to render a share management UI, audit who has access to a conversation, or determine whether the shared view needs to be refreshed before sending a link.

Request parameters🔗

ParameterDescription

conversation_identifier

String. The unique ID of the conversation, as returned when creating a conversation or listing conversations.

Example request🔗

curl -X GET \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversations/{conversation_identifier}/get-share-info' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json'

API response🔗

The following example shows the response for a conversation that is shared and current:

{
  "conversation_id": "conv-abc-123",
  "is_shared_content_outdated": false,
  "principals": [
    {
      "id": "user-001",
      "type": "USER",
      "display_name": "Alice Example",
      "name": "alice.example",
      "permission": "READ_ONLY"
    },
    {
      "id": "group-001",
      "type": "USER_GROUP",
      "display_name": "Sales Team",
      "name": "sales-team",
      "permission": "READ_ONLY"
    }
  ]
}

The following example shows the response for a conversation that has never been shared:

{
  "conversation_id": "conv-abc-123",
  "is_shared_content_outdated": null,
  "principals": []
}

When is_shared_content_outdated is true, call the share endpoint with refresh_shared_content: true to update the shared view with the latest conversation content.

Response fields🔗

FieldDescription

conversation_id

String. Echoes the request parameter.

is_shared_content_outdated

Boolean.

  • true, if the shared view was generated before the last edit to the conversation and does not reflect the latest content

  • false when the shared view is current.

  • null when the conversation has never been shared.

principals

Array of strings. List of principals with access. Empty when no access has been granted. The conversation owner is never included. Each entry in the principals array contains the following attributes:

* id. String. Unique identifier of the user or group. * type. String. USER for individual users, USER_GROUP for groups. * display_name. String. Display name as shown in the ThoughtSpot UI. * name. String. Internal name of the user or group. * permission. String. Access level. Always READ_ONLY for shared conversations.

Additional resources🔗

© 2026 ThoughtSpot Inc. All Rights Reserved.