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 Version: 10.12.0.cl or later\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 Version: 10.12.0.cl or later\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 Version: 10.12.0.cl or later\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 Version: 10.12.0.cl or later\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 Version: 10.12.0.cl or later\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