Opal View Colors API

openapi: 3.2.0
info:
  version: 3.0.0
  title: Opal API (⚠️ WIP) View Colors API
  license:
    name: Opal API License
    url: https://www.workwithopal.com/api-license
  description: The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
servers:
- url: https://login.ouropal.com
tags:
- name: View Colors
paths:
  /loupe/v3/view_colors:
    post:
      tags:
      - View Colors
      operationId: CreateViewColorV3
      summary: Create a new View Color
      security:
      - oauth2:
        - offline_access
      - api_key: []
      parameters:
      - name: include
        in: query
        required: false
        description: A comma separated value of related objects to include.
        schema:
          type: array
          items:
            type: string
            enum:
            - view
        style: form
        explode: false
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - type
                  - attributes
                  - relationships
                  properties:
                    type:
                      type: string
                      enum:
                      - view_color
                    attributes:
                      type: object
                      required:
                      - color
                      additionalProperties: false
                      properties:
                        color:
                          type: string
                          description: A color in hex format. Currently only supports hex values in the format of '#FFF' or '#FFFFFF'.
                        label:
                          type:
                          - string
                          - 'null'
                          description: A descriptive name for the color.
                    relationships:
                      type: object
                      required:
                      - view
                      properties:
                        view:
                          type: object
                          required:
                          - data
                          additionalProperties: false
                          properties:
                            data:
                              type: object
                              required:
                              - id
                              - type
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                type:
                                  type: string
                                  enum:
                                  - view
      responses:
        '201':
          description: A newly created view color resource.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    title: view_color
                    type: object
                    required:
                    - id
                    - type
                    - attributes
                    - relationships
                    additionalProperties: false
                    properties:
                      id:
                        type: string
                        format: uuid
                      type:
                        type: string
                        enum:
                        - view_color
                      attributes:
                        type: object
                        required:
                        - label
                        - color
                        - created_at
                        - updated_at
                        additionalProperties: false
                        properties:
                          label:
                            type:
                            - string
                            - 'null'
                            description: A descriptive name for the color.
                          color:
                            type: string
                            description: A color in hex format. Currently only supports hex values in the format of '#FFF' or '#FFFFFF'.
                          created_at:
                            type: string
                            readOnly: true
                            format: date-time
                            description: An ISO 8601-formatted datetime indicating when the resource was created.
                          updated_at:
                            type: string
                            readOnly: true
                            format: date-time
                            description: An ISO 8601-formatted datetime indicating when the resource was last updated.
                      relationships:
                        type: object
                        additionalProperties: false
                        required:
                        - view
                        properties:
                          view:
                            type: object
                            required:
                            - data
                            additionalProperties: false
                            properties:
                              data:
                                type: object
                                required:
                                - id
                                - type
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    format: uuid
                                  type:
                                    type: string
                                    enum:
                                    - view
                  included:
                    type: array
                    items:
                      oneOf:
                      - title: view
                        type: object
                        required:
                        - id
                        - type
                        - attributes
                        - relationships
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            format: uuid
                          type:
                            type: string
                            enum:
                            - view
                          meta:
                            type:
                            - object
                            - 'null'
                            description: 'Optionally calculated view metadata which are not part of responses by default.

                              '
                            additionalProperties: false
                            properties:
                              effective_privacy:
                                type: string
                                enum:
                                - whole_workspace
                                - some_but_not_all
                                description: 'The effective privacy of a resource is calculated based on all direct and

                                  inherited access. If a resource or any of its parents that it inherits

                                  access from are accessible to the entire workspace, the effective privacy

                                  is `whole_workspace`. Otherwise, the effective privacy is

                                  `some_but_not_all`.

                                  '
                          attributes:
                            type: object
                            required:
                            - title
                            - kind
                            - start_at
                            - end_at
                            - description
                            - default_timescale
                            - created_at
                            - updated_at
                            - start_month_index
                            - start_weekday_index
                            - show_smart_swimlane_datasource
                            - swimlane_title_column_width
                            additionalProperties: false
                            properties:
                              title:
                                type: string
                                description: A descriptive name for the view.
                              description:
                                type:
                                - string
                                - 'null'
                                description: A field allowing for additional descriptive text.
                              kind:
                                type: string
                                description: An enumeration representing the view type. Currently only supports Plan views.
                                enum:
                                - plan
                              default_timescale:
                                type: string
                                description: An enumeration representing the timescale of this view.
                                enum:
                                - day
                                - week
                                - month
                                - quarter
                              start_at:
                                type: string
                                description: An ISO 8601-formatted ('YYYY-MM-DD') date marking the beginning of the span of time that this view resource respresents. The start_at value must be a date ocurring before the end_at value.
                              end_at:
                                type: string
                                description: An ISO 8601-formatted ('YYYY-MM-DD') date marking the end of the span of time that this view resource respresents. The start_at value must be a date ocurring before the end_at value.
                              created_at:
                                type: string
                                format: date-time
                                description: An ISO 8601-formatted datetime indicating when the resource was created.
                                readOnly: true
                              updated_at:
                                type: string
                                format: date-time
                                description: An ISO 8601-formatted datetime indicating when the resource was last updated.
                                readOnly: true
                              start_month_index:
                                type: number
                                enum:
                                - 0
                                - 1
                                - 2
                                - 3
                                - 4
                                - 5
                                - 6
                                - 7
                                - 8
                                - 9
                                - 10
                                - 11
                                description: Start month index for the plan. Specifies the number of months, 0 to 11, to offset from January. 0 by default, meaning no offset. If set, e.g., 1, start in February.
                              start_weekday_index:
                                type: number
                                enum:
                                - 0
                                - 1
                                - 2
                                - 3
                                - 4
                                - 5
                                - 6
                                description: Start weekday index for the plan. Specifies the days in a week, 0 to 6 (Sunday to Saturday). 0 (Sunday) is the default. If set to, e.g., 1, weeks will start on Monday.
                              show_smart_swimlane_datasource:
                                type: boolean
                                description: Whether to display the datasource filter information on smart swimlanes. Defaults to true.
                              swimlane_title_column_width:
                                type: integer
                                description: The width in pixels of the swimlane title column from 200 to 800 for persistence across sessions. Defaults to 200.
                          relationships:
                            type: object
                            additionalProperties: false
                            required:
                            - categories
                            - blocks
                            - owner
                            - creator
                            - workspace
                            - colors
                            - key_dates
                            - parent_block
                            properties:
                              categories:
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type: array
                                    items:
                                      type: object
                                      required:
                                      - id
                                      - type
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          format: uuid
                                        type:
                                          type: string
                                          enum:
                                          - category
                              category_type:
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type:
                                    - object
                                    - 'null'
                                    required:
                                    - id
                                    - type
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                      type:
                                        type: string
                                        enum:
                                        - category_type
                              blocks:
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type: array
                                    items:
                                      type: object
                                      required:
                                      - id
                                      - type
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          format: uuid
                                        type:
                                          type: string
                                          enum:
                                          - block
                              owner:
                                title: User
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type: object
                                    required:
                                    - id
                                    - type
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                      type:
                                        type: string
                                        enum:
                                        - user
                              creator:
                                title: User
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type: object
                                    required:
                                    - id
                                    - type
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                      type:
                                        type: string
                                        enum:
                                        - user
                              workspace:
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type: object
                                    required:
                                    - id
                                    - type
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                      type:
                                        type: string
                                        enum:
                                        - workspace
                              colors:
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type: array
                                    items:
                                      type: object
                                      required:
                                      - id
                                      - type
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          format: uuid
                                        type:
                                          type: string
                                          enum:
                                          - view_color
                              key_dates:
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type: array
                                    items:
                                      type: object
                                      required:
                                      - id
                                      - type
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          format: uuid
                                        type:
                                          type: string
                                          enum:
                                          - key_date
                              parent_block:
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type: object
                                    required:
                                    - id
                                    - type
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                      type:
                                        type: string
                                        enum:
                                        - block
              example:
                data:
                  id: e3eb630a-4e04-4f1b-b0b0-3f7695766913
                  type: view_color
                  attributes:
                    label: Pink
                    color: '#facade'
                    created_at: '2020-09-11T15:27:01.881-08:00'
                    updated_at: '2020-09-11T15:27:01.881-08:00'
                  relationships:
                    view:
                      data:
                        id: c75ffeda-cff8-47ca-aa90-f562a2bfefa2
                        type: view
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          description: The http status code of the error response.
                        title:
                          type: string
                          description: A short, human-readable summary of the error.
                        detail:
                          type: string
                          description: A human-readable explanation of the error.
                        code:
                          type: string
                          description: 'An system-readable error code to provide additional specificity for

                            the error.

                            '
                      required:
                      - status
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          description: The http status code of the error response.
                        title:
                          type: string
                          description: A short, human-readable summary of the error.
                        detail:
                          type: string
                          description: A human-readable explanation of the error.
                        code:
                          type: string
                          description: 'An system-readable error code to provide additional specificity for

                            the error.

                            '
                      required:
                      - status
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          description: The http status code of the error response.
                        title:
                          type: string
                          description: A short, human-readable summary of the error.
                        detail:
                          type: string
                          description: A human-readable explanation of the error.
                        code:
                          type: string
                          description: 'An system-readable error code to provide additional specificity for

                            the error.

                            '
                      required:
                      - status
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          description: The http status code of the error response.
                        title:
                          type: string
                          description: A short, human-readable summary of the error.
                        detail:
                          type: string
                          description: A human-readable explanation of the error.
                        code:
                          type: string
                          description: 'An system-readable error code to provide additional specificity for

                            the error.

                            '
                      required:
                      - status
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'This API uses OAuth 2.0 with the authorization code grant flow. You can

        find more detailed authentication instructions in the [Authentication

        Strategies](/api/documentation#section/Authentication-Strategies/OAuth-2.0)

        section.

        '
      flows:
        authorizationCode:
          authorizationUrl: /oauth2/auth
          tokenUrl: /oauth2/token
          scopes:
            offline_access: Include this scope if you wish to receive a refresh token
    anonymous_oauth:
      type: oauth2
      description: 'The OAuth 2.0 client credentials flow is used for secure server-server

        requests when Opal does not need to associate a request with a particular

        Opal user. These anonymous requests are instead authorized based on the

        OAuth scope.

        '
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes:
            write:onboarding: Include this scope if you wish to make API requests to onboard new Opals.
    api_key:
      type: apiKey
      description: '(Deprecated) This API also supports authentication via an API or session

        token set in the request headers.

        '
      in: header
      name: Session-Token
    presentation_share_cookie:
      type: apiKey
      description: 'A cookie set and read by the Monolith service that authorizes a non-opal

        user to view a presentation and the resources within it. Other services

        can rely on this cookie by asking Monolith to authenticate it.

        '
      in: cookie
      name: share_token
x-tagGroups:
- name: Stable
  tags:
  - Board Collaborators
  - Board Objects
  - Boards
  - Content Schedules
  - Moment Schedules
  - Moments
  - Onboarding
- name: ⚠️  Unstable
  tags:
  - Block Connectors
  - Board Columns
  - Board Duplication
  - Board Standard Columns
  - Channels
  - Custom Field Options
  - Custom Field Types
  - Custom Fields
  - Moment Assignees
  - Moment Custom Fields
  - Planning Status
  - Rich Text Documents
  - User Groups
  - Users
  - Workspaces
- name: ℹ️ Proposed
  tags:
  - Bulk Operations
  - Gem Chats
  - Gem Files
  - Moment Duplication
  - Presentation Themes
  - Workflows
  - Workflow Contexts
  - Workflow Stages
  - Workflow Assignments
  - Workflow Responses
- name: ⚛️ Experimental
  tags:
  - Blocks
  - Block Custom Field Values
  - Block Duplication
  - Board User Settings
  - Categories
  - Category Types
  - Charts
  - Content
  - Custom Field Colors
  - Filter Sets
  - Key Dates
  - View Columns
  - View Standard Columns
  - Views
  - View Colors
  - Stories
- name: Additional Resources
  tags:
  - secondary_resources