Opal Blocks API

openapi: 3.2.0
info:
  title: Opal Blocks API
  version: 3.0.0
  license:
    name: Opal API License
    url: https://www.workwithopal.com/api-license
  description: 'Operations tagged Blocks across 2 of this provider''s published API definitions: opal-asgard-bff-openapi.yml, opal-v3-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://login.ouropal.com
tags:
- name: Blocks
paths:
  /{workspace_id}/blocks/{block_id}:
    get:
      tags:
      - Blocks
      operationId: ReadBlockBFFV1
      summary: Get a Block.
      security:
      - oauth2:
        - offline_access
      - api_key:
        - Session-Token
      parameters:
      - name: workspace_id
        in: path
        required: true
        description: The ID of the Block's workspace.
        schema:
          type: string
          format: uuid
      - name: block_id
        in: path
        required: true
        description: The ID of the Block.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The requested Block
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - boards
                    - category
                    - category_type
                    - color
                    - connectors
                    - description
                    - effective_privacy
                    - last_updated_date
                    - id
                    - image_id
                    - is_private
                    - is_template
                    - is_workspace_wide_template
                    - owner_id
                    - paired_moment_id
                    - plan
                    - rich_text_document_id
                    - start_date
                    - template_description
                    - template_name
                    - title
                    - key_dates
                    - child_plan
                    - custom_fields
                    - custom_field_values
                    - inherited_custom_field_values
                    - in_support_of_category_type_ids
                    additionalProperties: false
                    properties:
                      boards:
                        type: array
                        description: Boards associated with this block.
                        items:
                          oneOf:
                          - type: object
                            title: Board
                            required:
                            - id
                            - creator
                            - description
                            - image_source
                            - is_public
                            - title
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                format: uuid
                              title:
                                type: string
                              description:
                                type:
                                - string
                                - 'null'
                              image_source:
                                type:
                                - string
                                - 'null'
                              is_public:
                                type: boolean
                              creator:
                                type: object
                                description: The user that created the board.
                                title: user
                                required:
                                - id
                                - full_name
                                - avatar_url
                                - legacy_id
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    format: uuid
                                  full_name:
                                    type: string
                                  avatar_url:
                                    type:
                                    - string
                                    - 'null'
                                    description: URL for the user's avatar.
                                  legacy_id:
                                    type: string
                                    description: The ID to be used with v2 APIs.
                      category:
                        description: Swimlane this block is placed in.
                        type:
                        - object
                        - 'null'
                        title: Swimlane
                        required:
                        - id
                        - ancestor_titles
                        - title
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            format: uuid
                          ancestor_titles:
                            type:
                            - array
                            - 'null'
                            items:
                              type:
                              - string
                              - 'null'
                            description: 'Titles of nested categories (''groups'') containing the swimlane, ordered from the root of the nesting to the swimlane''s parent. Categories without a title will be included as null. Currently our UI permits at most one ancestor, but consumers MUST be able to handle an arbitrary number of ancestors. (The specifics of how to present additional ancestors is up to the consumer.)

                              '
                          title:
                            type:
                            - string
                            - 'null'
                            description: 'Title of the swimlane; null if the swimlane doesn''t have a title.

                              '
                      category_type:
                        type:
                        - object
                        - 'null'
                        required:
                        - id
                        - name
                        - description
                        - deactivated_at
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            format: uuid
                          name:
                            type: string
                            description: The name that will be displayed in the Opal application UI.
                          description:
                            type:
                            - string
                            - 'null'
                            description: A description of the record.
                          deactivated_at:
                            type:
                            - string
                            - 'null'
                            format: date-time
                            description: The timestamp when the category type was deactivated, if it has been deactivated.
                          supported_paired_type:
                            type:
                            - string
                            - 'null'
                            default: null
                            enum:
                            - moment
                            - null
                            description: Whether blocks of this type will have resources of the given type paired with them. Moment pairing allows teams to work with the same resources from the Plan (via blocks) or from a Board or Calendar (via Moments). Once set to 'moment', this property cannot be set back to null. Blocks created with a type that supports moment pairing will always have paired moments. Conversely, blocks created with types that do not support moment pairing will not have paired moments (unless moment pairing support is added to the type later).
                      color:
                        type:
                        - string
                        - 'null'
                      connectors:
                        type: array
                        items:
                          type: object
                          required:
                          - id
                          - category
                          - parent_block
                          - view
                          properties:
                            id:
                              type: string
                              format: uuid
                            category:
                              allOf:
                              - type: object
                                required:
                                - id
                                - name
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    format: uuid
                                  name:
                                    type:
                                    - string
                                    - 'null'
                            parent_block:
                              type: object
                              required:
                              - id
                              - name
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                name:
                                  type:
                                  - string
                                  - 'null'
                            view:
                              type: object
                              required:
                              - id
                              - name
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                name:
                                  type:
                                  - string
                                  - 'null'
                      description:
                        type:
                        - string
                        - 'null'
                      duration:
                        type:
                        - string
                        - 'null'
                        description: ISO 8601 duration string (e.g. P10D, P5W, P3M). Clients compute end date as start_date + duration.
                      end_date:
                        type:
                        - string
                        - 'null'
                        format: date
                        deprecated: true
                        description: 'DEPRECATED: migrate to `duration`.

                          An ISO8601 date describing the end of the block.'
                      last_updated_date:
                        type: string
                        format: date-time
                        description: An ISO8601 datetime describing the last time the block or its related resources was updated.
                      effective_privacy:
                        type: string
                        enum:
                        - whole_workspace
                        - some_but_not_all
                        description: 'The effective privacy of a block is calculated based on all direct and

                          inherited access. If a block 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`.

                          '
                      id:
                        type: string
                        format: uuid
                      image_id:
                        type:
                        - string
                        - 'null'
                        format: uuid
                      is_private:
                        type: boolean
                        description: 'DEPRECATED: Prefer using `effective_privacy`.


                          Whether the block is private/invite-only (i.e. does not inherit from the workspace.)

                          '
                        deprecated: true
                      is_template:
                        type: boolean
                        description: Whether this block is a template.
                        default: false
                      is_workspace_wide_template:
                        type: boolean
                        description: Whether this template is available workspace-wide.
                        default: false
                      owner_id:
                        type: string
                        format: uuid
                      paired_moment_id:
                        type:
                        - string
                        - 'null'
                        format: uuid
                        description: The UUID of the paired moment, if one exists for this block.
                      plan:
                        description: Parent plan for this block.
                        type: object
                        title: Plan
                        required:
                        - id
                        - title
                        - start_at
                        - end_at
                        - start_month_index
                        - start_weekday_index
                        - colors
                        - swimlanes
                        - key_dates
                        - valid_end_at
                        - valid_start_at
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            format: uuid
                          title:
                            type: string
                          end_at:
                            type: string
                            format: date
                            description: An ISO8601 date describing the end of the plan.
                          start_at:
                            type: string
                            format: date
                            description: An ISO8601 date describing the start of the plan.
                          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.
                          colors:
                            type: array
                            description: List of colors present in the view.
                            items:
                              oneOf:
                              - type: object
                                required:
                                - id
                                - color
                                - label
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    format: uuid
                                  label:
                                    type:
                                    - string
                                    - 'null'
                                  color:
                                    type: string
                          swimlanes:
                            type: array
                            description: List of all swimlanes on this plan.
                            items:
                              type: object
                              title: Swimlane
                              required:
                              - id
                              - ancestor_titles
                              - title
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                ancestor_titles:
                                  type:
                                  - array
                                  - 'null'
                                  items:
                                    type:
                                    - string
                                    - 'null'
                                  description: 'Titles of nested categories (''groups'') containing the swimlane, ordered from the root of the nesting to the swimlane''s parent. Categories without a title will be included as null. Currently our UI permits at most one ancestor, but consumers MUST be able to handle an arbitrary number of ancestors. (The specifics of how to present additional ancestors is up to the consumer.)

                                    '
                                title:
                                  type:
                                  - string
                                  - 'null'
                                  description: 'Title of the swimlane; null if the swimlane doesn''t have a title.

                                    '
                          key_dates:
                            type: array
                            description: List of all the key dates on this plan.
                            items:
                              type: object
                              title: Key Date
                              required:
                              - id
                              - title
                              - start_date
                              - end_date
                              - color
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                title:
                                  type: string
                                  description: A descriptive name for the key date
                                start_date:
                                  type: string
                                  format: date
                                  description: The date that the key date begins to be observed.
                                end_date:
                                  type:
                                  - string
                                  - 'null'
                                  format: date
                                  description: The date that the key date ceases to be observed.
                                color:
                                  type:
                                  - string
                                  - 'null'
                                  description: A color for the key date. The value must be a HEX value in the format of '#FFF' or '#FFFFFF'
                          parent_block:
                            type:
                            - object
                            - 'null'
                            description: 'The parent block of this plan.

                              '
                            required:
                            - boards
                            - category
                            - category_type
                            - color
                            - custom_fields
                            - custom_field_values
                            - description
                            - inherited_custom_field_values
                            - in_support_of_category_type_ids
                            - is_private
                            - is_template
                            - is_workspace_wide_template
                            - last_updated_date
                            - id
                            - image_id
                            - owner_id
                            - paired_moment_id
                            - plan
                            - rich_text_document_id
                            - start_date
                            - template_description
                            - template_name
                            - title
                            - key_dates
                            - child_plan
                            - connectors
                            additionalProperties: true
                            properties:
                              boards:
                                type: array
                                description: Boards associated with this block.
                                items:
                                  oneOf:
                                  - type: object
                                    title: Board
                                    required:
                                    - id
                                    - creator
                                    - description
                                    - image_source
                                    - is_public
                                    - title
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        format: uuid
                                      title:
                                        type: string
                                      description:
                                        type:
                                        - string
                                        - 'null'
                                      image_source:
                                        type:
                                        - string
                                        - 'null'
                                      is_public:
                                        type: boolean
                                      creator:
                                        type: object
                                        description: The user that created the board.
                                        title: user
                                        required:
                                        - id
                                        - full_name
                                        - avatar_url
                                        - legacy_id
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            format: uuid
                                          full_name:
                                            type: string
                                          avatar_url:
                                            type:
                                            - string
                                            - 'null'
                                            description: URL for the user's avatar.
                                          legacy_id:
                                            type: string
                                            description: The ID to be used with v2 APIs.
                              category:
                                description: Swimlane this block is placed in.
                                type:
                                - object
                                - 'null'
                                title: Swimlane
                                required:
                                - id
                                - ancestor_titles
                                - title
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    format: uuid
                                  ancestor_titles:
                                    type:
                                    - array
                                    - 'null'
                                    items:
                                      type:
                                      - string
                                      - 'null'
                                    description: 'Titles of nested categories (''groups'') containing the swimlane, ordered from the root of the nesting to the swimlane''s parent. Categories without a title will be included as null. Currently our UI permits at most one ancestor, but consumers MUST be able to handle an arbitrary number of ancestors. (The specifics of how to present additional ancestors is up to the consumer.)

                                      '
                                  title:
                                    type:
                                    - string
                                    - 'null'
                                    description: 'Title of the swimlane; null if the swimlane doesn''t have a title.

                                      '
                              category_type:
                                type:
                                - object
                                - 'null'
                                required:
                                - id
                                - name
                                - description
                                - deactivated_at
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    format: uuid
                                  name:
                                    type: string
                                    description: The name that will be displayed in the Opal application UI.
                                  description:
                                    type:
                                    - string
                                    - 'null'
                                    description: A description of the record.
                                  deactivated_at:
                                    type:
                                    - string
                                    - 'null'
                                    format: date-time
                                    description: The timestamp when the category type was deactivated, if it has been deactivated.
                                  supported_paired_type:
                                    type:
                                    - string
                                    - 'null'
                                    default: null
                                    enum:
                                    - moment
                                    - null
                                    description: Whether blocks of this type will have resources of the given type paired with them. Moment pairing allows teams to work with the same resources from the Plan (via blocks) or from a Board or Calendar (via Moments). Once set to 'moment', this property cannot be set back to null. Blocks created with a type that supports moment pairing will always have paired moments. Conversely, blocks created with types that do not support moment pairing will not have paired moments (unless moment pairing support is added to the type later).
                              color:
                                type:
                                - string
                                - 'null'
                              connectors:
                                type: array
                                items:
                                  type: object
                                  required:
                                  - id
                                  - category
                                  - parent_block
                                  - view
                                  properties:
                                    id:
                                      type: string
                                      format: uuid
                                    category:
                                      allOf:
                                      - type: object
                                        required:
                                        - id
                                        - name
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            format: uuid
                                          name:
                                            type:
                                            - string
                                            - 'null'
                                    parent_block:
                                      type: object
                                      required:
                                      - id
                                      - name
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          format: uuid
                                        name:
                                          type:
                                          - string
                                          - 'null'
                                    view:
                                      type: object
                                      required:
                                      - id
                                      - name
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          format: uuid
                                        name:
                                          type:
                                          - string
                                          - 'null'
                              custom_fields:
                                type: array
    

# --- truncated at 32 KB (1013 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/opal/refs/heads/main/openapi/opal-blocks-api-openapi.yml