openapi: 3.0.0
info:
title: ThoughtSpot Public REST 10.1.0.cl Custom Calendars API
version: '2.0'
servers:
- url: '{base-url}'
variables:
base-url:
default: https://localhost:443
security:
- bearerAuth: []
tags:
- name: Custom Calendars
paths:
/api/rest/2.0/calendars/create:
post:
operationId: createCalendar
description: "\n <span class=\"since-beta-tag\">Version: 10.12.0.cl or later</span>\n\nCreates a new [custom calendar](https://docs.thoughtspot.com/cloud/latest/connections-cust-cal).\n\nRequires `DATAMANAGEMENT` (**Can manage data**) or `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your ThoughtSpot instance, the `CAN_MANAGE_CUSTOM_CALENDAR` (**Can manage custom calendars**) privilege is required.\n\n\n#### Usage guidelines\n\nYou can create a custom calendar from scratch or an existing Table in ThoughtSpot. For both methods of calendar creation, the following parameters are required:\n\n* Name of the custom calendar.\n* Calendar creation method. To create a calendar from an existing table, specify the method:\n\n - `FROM_EXISTING_TABLE` - Creates calendar from the table reference provided in the API request.\n - `FROM_INPUT_PARAMS` - Creates a calendar from the parameters defined in the API request.\n\n* Connection ID and Table name\n* Database and schema name attributes:\n For most Cloud Data Warehouse (CDW) connectors, both `database_name` and `schema_name` attributes are required. \n However, the attribute requirements are conditional and vary based on the connector type and its metadata structure. For example, for connectors such as Teradata, MySQL, SingleSore, Amazon Aurora MySQL, Amazon RDS MySQL, Oracle, and GCP_MYSQL, the `schema_name` is required, whereas the `database_name` attribute is not.\n Similarly, connectors such as ClickHouse require you to specify the `database_name` and the schema specification in such cases is optional.\n\n**NOTE**: If you are creating a calendar from an existing table, ensure that the referenced table matches the required DDL for custom calendars. If the schema does not match, the API returns an error.\n\n##### Calendar type\nThe API allows you to create the following types of calendars:\n\n* `MONTH_OFFSET`. The default calendar type. A `MONTH_OFFSET` calendar is offset by a few months from the standard calendar months (January to December) and the year begins with the month defined in the request. For example, if the `month_offset` value is set as `April`, the calendar year begins in April.\n\n* `4-4-5`. Each quarter in the calendar will include two 4-week months followed by one 5-week month.\n* `4-5-4`. Each quarter in the calendar will include two 4-week months with a 5-week month between.\n* `5-4-4`. Each quarter begins with a 5-week month, followed by two 4-week months.\n\nTo start and end the calendar on a specific date, specify the dates in the `MM/DD/YYYY` format. For `MONTH_OFFSET` calendars, ensure that the `start_date` matches the month specified in the `month_offset` attribute.\n\nYou can also set the starting day of the week and customize the prefixes for year and quarter labels.\n\n#### Examples\n\nTo create a calendar from an existing table:\n\n```\n{\n \"name\": \"MyCustomCalendar1\",\n \"table_reference\": {\n \"connection_identifier\": \"4db8ea22-2ff4-4224-b05a-26674717e468\",\n \"table_name\": \"MyCalendarTable\",\n \"database_name\": \"RETAILAPPAREL\",\n \"schema_name\": \"PUBLIC\"\n },\n \"creation_method\": \"FROM_EXISTING_TABLE\",\n}\n```\n\nTo create a calendar from scratch:\n\n```\n{\n \"name\": \"MyCustomCalendar1\",\n \"table_reference\": {\n \"connection_identifier\": \"4db8ea22-2ff4-4224-b05a-26674717e468\",\n \"table_name\": \"MyCalendarTable\",\n \"database_name\": \"RETAILAPPAREL\",\n \"schema_name\": \"PUBLIC\"\n },\n \"creation_method\": \"FROM_INPUT_PARAMS\",\n \"calendar_type\": \"MONTH_OFFSET\",\n \"month_offset\": \"April\",\n \"start_day_of_week\": \"Monday\",\n \"quarter_name_prefix\": \"Q\",\n \"year_name_prefix\": \"FY\",\n \"start_date\": \"04/01/2025\",\n \"end_date\": \"04/31/2025\"\n}\n```\n\n\n\n\n#### Endpoint URL\n"
tags:
- Custom Calendars
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCalendarRequest'
required: true
parameters: []
responses:
'200':
description: Custom calendar created successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CalendarResponse'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/calendars/{calendar_identifier}/delete:
post:
operationId: deleteCalendar
description: "\n <span class=\"since-beta-tag\">Version: 10.12.0.cl or later</span>\n\nDeletes a [custom calendar](https://docs.thoughtspot.com/cloud/latest/connections-cust-cal).\n\nRequires `DATAMANAGEMENT` (**Can manage data**) or `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your ThoughtSpot instance, the `CAN_MANAGE_CUSTOM_CALENDAR` (**Can manage custom calendars**) privilege is required.\n\n#### Usage guidelines\nTo delete a custom calendar, specify the calendar ID as a path parameter in the request URL. \n\n\n\n\n#### Endpoint URL\n"
tags:
- Custom Calendars
parameters:
- in: path
name: calendar_identifier
required: true
schema:
type: string
description: Unique ID or name of the Calendar.
responses:
'204':
description: Custom calendar successfully deleted.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/calendars/generate-csv:
post:
operationId: generateCSV
description: "\n <span class=\"since-beta-tag\">Version: 10.12.0.cl or later</span>\n\nExports a [custom calendar](https://docs.thoughtspot.com/cloud/latest/connections-cust-cal) in the CSV format.\n\nRequires `DATAMANAGEMENT` (**Can manage data**) or `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your ThoughtSpot instance, the `CAN_MANAGE_CUSTOM_CALENDAR` (**Can manage custom calendars**) privilege is required.\n\n#### Usage guidelines\n\nUse this API to download a custom calendar in the CSV file format. In your API request, specify the following parameters.\n\n* Start and end date of the calendar. For \"month offset\" calendars, the start date must match the month defined in the `month_offset` attribute.\n\nYou can also specify optional parameters such as the starting day of the week and prefixes for the quarter and year labels.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Custom Calendars
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/GenerateCSVRequest'
required: true
parameters: []
responses:
'200':
description: Generate custom calendar data based on specifications, as a CSV file.
content:
application/json:
schema:
type: object
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/calendars/search:
post:
operationId: searchCalendars
description: "\n <span class=\"since-beta-tag\">Version: 10.12.0.cl or later</span>\n\nGets a list of [custom calendars](https://docs.thoughtspot.com/cloud/latest/connections-cust-cal).\n\nRequires `DATAMANAGEMENT` (**Can manage data**) or `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your ThoughtSpot instance, the `CAN_MANAGE_CUSTOM_CALENDAR` (**Can manage custom calendars**) privilege is required.\n\n#### Usage guidelines\n\nBy default, the API returns a list of custom calendars for all connection objects. To retrieve custom calendar details for a particular connection, specify the connection ID. You can also use other search parameters such as `name_pattern` and `sort_options` as search filters.\n\nThe `name_pattern` parameter filters and returns only those objects that match the specified pattern. Use `%` as a wildcard for pattern matching.\n\n\n\n\n#### Endpoint URL\n"
tags:
- Custom Calendars
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchCalendarsRequest'
required: true
parameters: []
responses:
'200':
description: Custom calendar fetched successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CalendarResponse'
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/rest/2.0/calendars/{calendar_identifier}/update:
post:
operationId: updateCalendar
description: "\n <span class=\"since-beta-tag\">Version: 10.12.0.cl or later</span>\n\nUpdates the properties of a [custom calendar](https://docs.thoughtspot.com/cloud/latest/connections-cust-cal).\n\nRequires `DATAMANAGEMENT` (**Can manage data**) or `ADMINISTRATION` (**Can administer ThoughtSpot**) privilege.\nIf [Role-Based Access Control (RBAC)](https://developers.thoughtspot.com/docs/rbac) is enabled on your ThoughtSpot instance, the `CAN_MANAGE_CUSTOM_CALENDAR` (**Can manage custom calendars**) privilege is required.\n\n#### Usage guidelines\n\nYou can update the properties of a calendar using one of the following methods:\n* `FROM_INPUT_PARAMS` to update the calendar properties with the values defined in the API request.\n* `FROM_EXISTING_TABLE` Creates a calendar from the parameters defined in the API request.\n\nTo update a custom calendar, specify the calendar ID as a path parameter in the request URL and the following parameters in the request body: \n\n* Connection ID and Table name\n* Database and schema name attributes:\n For most Cloud Data Warehouse (CDW) connectors, both `database_name` and `schema_name` attributes are required. \n However, the attribute requirements are conditional and vary based on the connector type and its metadata structure. For example, for connectors such as Teradata, MySQL, SingleSore, Amazon Aurora MySQL, Amazon RDS MySQL, Oracle, and GCP_MYSQL, the `schema_name` is required, whereas the `database_name` attribute is not.\n Similarly, connectors such as ClickHouse require you to specify the `database_name` and the schema specification in such cases is optional.\n\nThe API allows you to modify the calendar type, month offset value, start and end date, starting day of the week, and prefixes assigned to the year and quarter labels. \n\n#### Examples\n\nUpdate a custom calendar using an existing Table in ThoughtSpot:\n\n```\n{\n \"update_method\": \"FROM_EXISTING_TABLE\",\n \"table_reference\": {\n \"connection_identifier\": \"Connection1\",\n \"database_name\": \"db1\",\n \"table_name\": \"custom_calendar_2025\",\n \"schame_name\": \"schemaVar\"\n }\n}\n```\n\nUpdate a custom calendar with the attributes defined in the API request:\n\n```\n{\n \"update_method\": \"FROM_INPUT_PARAMS\",\n \"table_reference\": {\n \"connection_identifier\": \"Connection1\",\n \"database_name\": \"db1\",\n \"table_name\": \"custom_calendar_2025\",\n \"schame_name\": \"schemaVar\"\n },\n \"month_offset\": \"August\",\n \"start_day_of_week\": \"Monday\",\n \"start_date\": \"08/01/2025\",\n \"end_date\": \"07/31/2026\"\n}\n```\n\n\n\n\n#### Endpoint URL\n"
tags:
- Custom Calendars
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCalendarRequest'
required: true
parameters:
- in: path
name: calendar_identifier
required: true
schema:
type: string
description: Unique Id or name of the calendar.
responses:
'204':
description: Custom calendar updated successfully.
'400':
description: Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Forbidden access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ExternalTableInput:
type: object
required:
- connection_identifier
- table_name
properties:
connection_identifier:
type: string
description: Unique ID or name of the connection.
database_name:
type: string
default: ''
description: Name of the database.
nullable: true
schema_name:
type: string
default: ''
description: Name of the schema.
nullable: true
table_name:
type: string
description: Name of the table. Table names may be case-sensitive depending on the database system.
UpdateCalendarRequest:
type: object
properties:
update_method:
description: Type of update operation.
default: FROM_INPUT_PARAMS
type: string
enum:
- FROM_INPUT_PARAMS
- FROM_EXISTING_TABLE
table_reference:
description: 'Table reference containing connection identifier and table details in this format: `{"connection_identifier":"conn1", "database_name":"db1", "schema_name":"sc1", "table_name":"tb1"}`.'
allOf:
- $ref: '#/components/schemas/ExternalTableInput'
start_date:
description: Start date for the calendar in `MM/dd/yyyy` format. This parameter is mandatory if `update_method` is set as `FROM_INPUT_PARAMS`.
type: string
end_date:
description: End date for the calendar in `MM/dd/yyyy` format. This parameter is mandatory if `update_method` is set as `FROM_INPUT_PARAMS`.
type: string
calendar_type:
description: Type of the calendar.
default: MONTH_OFFSET
type: string
enum:
- MONTH_OFFSET
- FOUR_FOUR_FIVE
- FOUR_FIVE_FOUR
- FIVE_FOUR_FOUR
month_offset:
description: Specify the month in which the fiscal or custom calendar year should start. For example, if you set `month_offset` to "April", the custom calendar will treat "April" as the first month of the year, and the related attributes such as quarters and start date will be based on this offset. The default value is `January`, which represents the standard calendar year (January to December).
default: January
type: string
enum:
- January
- February
- March
- April
- May
- June
- July
- August
- September
- October
- November
- December
start_day_of_week:
description: Specify the starting day of the week
default: Sunday
type: string
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
quarter_name_prefix:
description: Prefix to add before the quarter.
default: ''
type: string
year_name_prefix:
description: Prefix to add before the year.
default: ''
type: string
required:
- table_reference
CalendarResponse:
type: object
properties:
calendar_name:
type: string
description: Name of the calendar
nullable: true
connection_name:
type: string
description: Name of the connection
nullable: true
data_warehouse_type:
type: string
description: Type of data warehouse
nullable: true
modification_time_in_millis:
type: string
description: Last modification time in milliseconds
nullable: true
author_name:
type: string
description: Name of the author who created the calendar
nullable: true
connection_id:
type: string
description: Unique ID of the connection
nullable: true
calendar_id:
type: string
description: Unique ID of the calendar
nullable: true
CreateCalendarRequest:
type: object
properties:
name:
description: Name of the custom calendar.
type: string
creation_method:
description: Type of create operation.
type: string
enum:
- FROM_INPUT_PARAMS
- FROM_EXISTING_TABLE
table_reference:
description: 'Table reference containing connection identifier and table details in this format: `{"connection_identifier":"conn1", "database_name":"db1", "schema_name":"sc1", "table_name":"tb1"}`. The given table will be created if `creation_method` is set as `FROM_INPUT_PARAMS`.'
allOf:
- $ref: '#/components/schemas/ExternalTableInput'
start_date:
description: Start date for the calendar in `MM/dd/yyyy` format. This parameter is mandatory if `creation_method` is set as `FROM_INPUT_PARAMS`.
type: string
end_date:
description: End date for the calendar in `MM/dd/yyyy` format. This parameter is mandatory if `creation_method` is set as `FROM_INPUT_PARAMS`.
type: string
calendar_type:
description: Type of the calendar.
default: MONTH_OFFSET
type: string
enum:
- MONTH_OFFSET
- FOUR_FOUR_FIVE
- FOUR_FIVE_FOUR
- FIVE_FOUR_FOUR
month_offset:
description: Specify the month in which the fiscal or custom calendar year should start. For example, if you set `month_offset` to "April", the custom calendar will treat "April" as the first month of the year, and the related attributes such as quarters and start date will be based on this offset. The default value is `January`, which represents the standard calendar year (January to December).
default: January
type: string
enum:
- January
- February
- March
- April
- May
- June
- July
- August
- September
- October
- November
- December
start_day_of_week:
description: Specify the starting day of the week.
default: Sunday
type: string
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
quarter_name_prefix:
description: Prefix to add before the quarter.
default: ''
type: string
year_name_prefix:
description: Prefix to add before the year.
default: ''
type: string
required:
- name
- creation_method
- table_reference
ErrorResponse:
type: object
properties:
error:
type: object
nullable: true
GenerateCSVRequest:
type: object
properties:
start_date:
description: Start date for the calendar in `MM/dd/yyyy` format.
type: string
end_date:
description: End date for the calendar in `MM/dd/yyyy` format.
type: string
calendar_type:
description: Type of the calendar.
default: MONTH_OFFSET
type: string
enum:
- MONTH_OFFSET
- FOUR_FOUR_FIVE
- FOUR_FIVE_FOUR
- FIVE_FOUR_FOUR
month_offset:
description: Month offset to start calendar from `January`.
default: January
type: string
enum:
- January
- February
- March
- April
- May
- June
- July
- August
- September
- October
- November
- December
start_day_of_week:
description: Specify the starting day of the week.
default: Sunday
type: string
enum:
- Sunday
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
quarter_name_prefix:
description: Prefix to add before the quarter.
type: string
year_name_prefix:
description: Prefix to add before the year.
type: string
required:
- start_date
- end_date
SearchCalendarsRequest:
type: object
properties:
connection_identifier:
description: Unique ID or name of the connection.
type: string
name_pattern:
description: Pattern to match for calendar names (use '%' for wildcard match).
type: string
record_offset:
description: The starting record number from where the records should be included.
default: 0
type: integer
format: int32
record_size:
description: The number of records that should be included.
default: 10
type: integer
format: int32
sort_options:
description: Sort options.
allOf:
- $ref: '#/components/schemas/SortOption'
SortOption:
type: object
properties:
field_name:
type: string
enum:
- DEFAULT
- NAME
- DISPLAY_NAME
- AUTHOR
- CREATED
- MODIFIED
default: DEFAULT
description: Name of the field to apply the sort on.
nullable: true
order:
type: string
enum:
- ASC
- DESC
default: ASC
description: 'Sort order : ASC(Ascending) or DESC(Descending).'
nullable: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
x-roles:
- name: 26.2.0.cl
id: 26.2.0.cl
tags:
- 26.2.0.cl
description: Roles for version 26.2.0.cl
- name: 10.4.0.cl
id: 10.4.0.cl
tags:
- 10.4.0.cl
description: Roles for version 10.4.0.cl
- name: 26.7.0.cl
id: 26.7.0.cl
tags:
- 26.7.0.cl
description: Roles for version 26.7.0.cl
- name: 26.8.0.cl
id: 26.8.0.cl
tags:
- 26.8.0.cl
description: Roles for version 26.8.0.cl
- name: 26.6.0.cl
id: 26.6.0.cl
tags:
- 26.6.0.cl
description: Roles for version 26.6.0.cl
- name: 10.15.0.cl
id: 10.15.0.cl
tags:
- 10.15.0.cl
description: Roles for version 10.15.0.cl
- name: 10.13.0.cl
id: 10.13.0.cl
tags:
- 10.13.0.cl
description: Roles for version 10.13.0.cl
- name: 26.9.0.cl
id: 26.9.0.cl
tags:
- 26.9.0.cl
description: Roles for version 26.9.0.cl
- name: 10.7.0.cl
id: 10.7.0.cl
tags:
- 10.7.0.cl
description: Roles for version 10.7.0.cl
- name: 26.5.0.cl
id: 26.5.0.cl
tags:
- 26.5.0.cl
description: Roles for version 26.5.0.cl
- name: 9.0.0.cl
id: 9.0.0.cl
tags:
- 9.0.0.cl
description: Roles for version 9.0.0.cl
- name: 9.4.0.cl
id: 9.4.0.cl
tags:
- 9.4.0.cl
description: Roles for version 9.4.0.cl
- name: 9.12.0.cl
id: 9.12.0.cl
tags:
- 9.12.0.cl
description: Roles for version 9.12.0.cl
- name: 26.4.0.cl
id: 26.4.0.cl
tags:
- 26.4.0.cl
description: Roles for version 26.4.0.cl
- name: 10.12.0.cl
id: 10.12.0.cl
tags:
- 10.12.0.cl
description: Roles for version 10.12.0.cl
- name: 9.2.0.cl
id: 9.2.0.cl
tags:
- 9.2.0.cl
description: Roles for version 9.2.0.cl
- name: 9.9.0.cl
id: 9.9.0.cl
tags:
- 9.9.0.cl
description: Roles for version 9.9.0.cl
- name: 9.6.0.cl
id: 9.6.0.cl
tags:
- 9.6.0.cl
description: Roles for version 9.6.0.cl
- name: 10.10.0.cl
id: 10.10.0.cl
tags:
- 10.10.0.cl
description: Roles for version 10.10.0.cl
- name: 10.6.0.cl
id: 10.6.0.cl
tags:
- 10.6.0.cl
description: Roles for version 10.6.0.cl
- name: 10.3.0.cl
id: 10.3.0.cl
tags:
- 10.3.0.cl
description: Roles for version 10.3.0.cl
- name: 10.1.0.cl
id: 10.1.0.cl
tags:
- 10.1.0.cl
description: Roles for version 10.1.0.cl
- name: 10.9.0.cl
id: 10.9.0.cl
tags:
- 10.9.0.cl
description: Roles for version 10.9.0.cl
- name: 10.8.0.cl
id: 10.8.0.cl
tags:
- 10.8.0.cl
description: Roles for version 10.8.0.cl
- name: 9.5.0.cl
id: 9.5.0.cl
tags:
- 9.5.0.cl
description: Roles for version 9.5.0.cl
- name: 26.3.0.cl
id: 26.3.0.cl
tags:
- 26.3.0.cl
description: Roles for version 26.3.0.cl
- name: 10.14.0.cl
id: 10.14.0.cl
tags:
- 10.14.0.cl
description: Roles for version 10.14.0.cl
- name: 9.7.0.cl
id: 9.7.0.cl
tags:
- 9.7.0.cl
description: Roles for version 9.7.0.cl