openapi: 3.2.0
info:
  title: DoiT Settings API
  description: Programmatic access to DoiT Platform
  version: v1
servers:
- url: https://api.doit.com
security:
- api_key: []
- tenantId: []
  api_key: []
tags:
- name: Settings
paths:
  /analytics/v1/settings/themes:
    get:
      tags:
      - Settings
      summary: List custom themes
      description: Returns the list of custom color themes defined for your account.
      operationId: listCustomThemes
      responses:
        '200':
          description: OK - The request succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  rowCount:
                    type: integer
                    description: Total number of custom themes in the result set.
                  themes:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomTheme'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
    post:
      tags:
      - Settings
      summary: Create a custom theme
      description: Creates a new custom color theme. Requires Cloud Analytics Admin permission.
      operationId: createCustomTheme
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomThemeRequest'
        required: true
      responses:
        '201':
          description: Created - Custom theme created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomTheme'
          links:
            getCustomTheme:
              operationId: getCustomTheme
              parameters:
                id: $response.body#/id
            updateCustomTheme:
              operationId: updateCustomTheme
              parameters:
                id: $response.body#/id
            deleteCustomTheme:
              operationId: deleteCustomTheme
              parameters:
                id: $response.body#/id
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
      x-codegen-request-body-name: Body
  /analytics/v1/settings/themes/{id}:
    get:
      tags:
      - Settings
      summary: Retrieve a custom theme
      description: Returns a custom theme by the specified Id.
      operationId: getCustomTheme
      parameters:
      - name: id
        in: path
        description: Custom theme ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK - Custom theme returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomTheme'
          links:
            updateCustomTheme:
              operationId: updateCustomTheme
              parameters:
                id: $request.path.id
            deleteCustomTheme:
              operationId: deleteCustomTheme
              parameters:
                id: $request.path.id
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
    patch:
      tags:
      - Settings
      summary: Update a custom theme
      description: Updates the custom theme specified by the Id. Requires Cloud Analytics Admin permission.
      operationId: updateCustomTheme
      parameters:
      - name: id
        in: path
        description: Custom theme ID
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomThemeRequest'
        required: true
      responses:
        '200':
          description: OK - Custom theme updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomTheme'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
      x-codegen-request-body-name: Body
    delete:
      tags:
      - Settings
      summary: Delete a custom theme
      description: Deletes the custom theme specified by the Id. Requires Cloud Analytics Admin permission.
      operationId: deleteCustomTheme
      parameters:
      - name: id
        in: path
        description: Custom theme ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK - Custom theme deleted.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
              example: {}
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /analytics/v1/settings/active-theme:
    get:
      tags:
      - Settings
      summary: Get the active theme
      description: 'Returns the theme currently active for the authenticated user.

        `themeId` is the reserved sentinel `"default"` when no custom or

        preset theme is selected and the user is on the built-in default.'
      operationId: getActiveTheme
      responses:
        '200':
          description: OK - The request succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveTheme'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
    put:
      tags:
      - Settings
      summary: Set the active theme
      description: 'Sets the theme active for the authenticated user. Send the reserved

        sentinel `themeId: "default"` to clear the active theme and fall back

        to the built-in default. Returns the updated active theme.'
      operationId: setActiveTheme
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetActiveThemeRequest'
        required: true
      responses:
        '200':
          description: OK - Active theme updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActiveTheme'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
      x-codegen-request-body-name: Body
components:
  responses:
    '400':
      description: Bad Request - The server cannot process the request, often due to a malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized - Invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not Found - The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: Forbidden - The client is not authorized to perform the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    UpdateCustomThemeRequest:
      type: object
      description: Request body for updating a custom theme. Only provided fields are modified.
      properties:
        name:
          type:
          - string
          - 'null'
          description: The display name of the custom theme.
          maxLength: 200
        primaryColor:
          $ref: '#/components/schemas/HexColor'
        colors:
          $ref: '#/components/schemas/ThemeColors'
    ThemeColors:
      type: object
      required:
      - light
      - dark
      description: Palettes for light and dark display modes. Each palette must contain between 1 and 32 hex colors.
      properties:
        light:
          type: array
          minItems: 1
          maxItems: 32
          items:
            $ref: '#/components/schemas/HexColor'
          description: Colors used when the report is displayed in light mode.
        dark:
          type: array
          minItems: 1
          maxItems: 32
          items:
            $ref: '#/components/schemas/HexColor'
          description: Colors used when the report is displayed in dark mode.
    Error:
      type: object
      description: Standard error response structure.
      properties:
        error:
          type: string
          description: Detailed error message.
    CustomTheme:
      required:
      - id
      - name
      - primaryColor
      - colors
      type: object
      description: A custom color theme applied to Cloud Analytics reports.
      properties:
        id:
          type: string
          description: The unique identifier of the custom theme.
        name:
          type: string
          description: The display name of the custom theme.
          maxLength: 200
        primaryColor:
          $ref: '#/components/schemas/HexColor'
        colors:
          $ref: '#/components/schemas/ThemeColors'
        createTime:
          type: string
          format: date-time
          description: The creation time of the custom theme.
        updateTime:
          type: string
          format: date-time
          description: The time when the custom theme was last updated.
    SetActiveThemeRequest:
      type: object
      required:
      - themeId
      description: Request body for setting the active custom or preset theme for the authenticated user.
      properties:
        themeId:
          type: string
          default: default
          description: 'Identifier of the theme to activate. Send the reserved sentinel

            `"default"` to clear the active theme and fall back to the built-in

            default.'
    CreateCustomThemeRequest:
      required:
      - name
      - primaryColor
      - colors
      type: object
      description: Request body for creating a custom theme.
      properties:
        name:
          type: string
          description: The display name of the custom theme.
          maxLength: 200
        primaryColor:
          $ref: '#/components/schemas/HexColor'
        colors:
          $ref: '#/components/schemas/ThemeColors'
    HexColor:
      type: string
      description: A color in hex notation. Accepts `#RGB`, `#RRGGBB`, or `#RRGGBBAA`.
      pattern: ^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$
      example: '#1A73E8'
    ActiveTheme:
      type: object
      required:
      - themeId
      description: The theme currently active for the authenticated user.
      properties:
        themeId:
          type: string
          default: default
          description: 'Identifier of the active theme. The reserved sentinel `"default"` is

            returned when the user is using the built-in default (no custom or

            preset theme stored).'
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      description: Use the "Bearer <API_KEY>" format or sign in for autofill
      in: header
    tenantId:
      type: apiKey
      name: X-Tenant-Id
      description: 'Tenant (customer) ID that sets the request''s customer context.


        Required when the credential can access more than one tenant; omit when the

        credential is scoped to exactly one tenant (the server resolves that tenant

        automatically). If omitted for a multi-tenant credential, the request fails

        with `400` and code `tenant_id_required`. If the value conflicts with the

        credential''s tenant scope, the request fails with `400` and code

        `tenant_id_mismatch`.


        Use this header over the legacy `customerContext` query parameter, which

        only applies to legacy API keys and is ignored by personal and service-account

        API tokens.

        '
      in: header
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://console.doit.com/sign-in/oauth
          tokenUrl: https://console.doit.com/api/auth/token
          scopes:
            dci: Access All Data
x-samples-languages:
- curl
- go
- node
- python
x-cli-config:
  security: oauth2
  params:
    client_id: cli