openapi: 3.2.0 info: version: 3.0.0 title: Asgard BFF Experimental 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](https://tools.ietf.org/html/bcp14) [[RFC2119](https://tools.ietf.org/html/rfc2119)] [[RFC8174](https://tools.ietf.org/html/rfc8174)] when, and only when, they appear in all capitals, as shown here.\n\n# Design Principles\n\n## Firehose Rule\n\nBy default endpoints include all the relevant data that’s accessible to the authenticated user. Clients **MAY** specify filters, ordering, pagination, sparse fields, and other limiting mechanisms to pare down the desired data.\n\n*Note:* Existing endpoints **MAY NOT** follow this maximalist approach, but new endpoints will, and we **MAY** enhance existing endpoints.\n\n## Obscurity\n\nIn order to provide customers with as much privacy as possible, many API calls that fail authorization will return `404 Not Found` rather than `403 Forbidden`. Do not design frontends around the expectation that a `404 Not Found` status code means a resource would not be returned given different authentication credentials.\n\n# Authentication Strategies\n## OAuth 2.0\nOpal uses OAuth 2.0 (https://oauth.net/2) to authenticate users and grant access to protected resources. After registering your application as an OAuth client, you must get permission from each user before accessing their account.\n\nThe main steps are:\n\n1. Register your application\n2. Direct the user to Opal, to authorize your application\n3. Opal confirm's user identity, and asks the user to grant your application permissions\n4. Opal issues tokens your application can use to access the user's Opal resources\n5. Your application can begin making requests to the Opal API on behalf of the user\n\n### Registering your application\nApplication registration is currently a manual process.\n\nTo begin, you will need to provide the following information to the Opal integrations team:\n\n- Application name\n- Logo URI\n- Redirect URI\n\nIn return, expect to receive:\n\n- Client ID\n - public\n- Application secret\n - keep this private\n - keep this written down someplace safe. Opal cannot retrieve this for you if it is lost.\n\n### Authorization\nFor a Client to make API requests on behalf of Users, the User must first give consent.\nHere is an overview of the consent flow:\n\n1. Direct the User to grant access in Opal\n\n```\nhttps://login.ouropal.com/oauth2/auth?grant_type=authorization_code&scope=offline_access&response_type=code&client_id={client_id}&state={state}&redirect_uri={url_encoded_redirect}\n```\n\nParameters:\n- `client_id`: Provided by Opal.\n- `grant_type`: Set the value to authorization_code to receive a code string that can be exchanged for an access token.\n- `redirect_uri`: Defined by Client. After authentication, the user will be directed to this location.\n- `response_type`: The value code should be set for refresh tokens to be issued.\n- `scope`: The value offline_access must be present if you wish to use refresh tokens.\n- `state`: Defined by the Client. A unique value used to validate the response.\n\n\n2. If logged out, User is directed to log in to Opal\n\n3. User is redirected to consent page (if the User has not already given consent)\n\n```\nhttps://login.ouropal.com/oauth2/consent?consent_challenge=abc123\n```\n\n4. If the User grants permission, User is sent to the specified `redirect_uri`\n\n```\nhttps://example.com/defined-by-client?code=Mu9z2DndN7TfXSLaf99O8ReqqXqMabXhSqP5e0jlx_Q.naLKbko-GyfPJRGYcWyclxU0sBGwygPy05OSFww0XZ8&scope=offline_access&state={state}\n```\n\nParameters:\n- `code`: The Client may use this to get an access token.\n- `scope`: API permissions granted to the Client by the User.\n- `state`: The validation string provided by the Client in step 1.\n\nIf the User declines the consent prompt, User will be sent to the same `redirect_uri`, but with an error parameter :\n\n```\nhttps://example.com/defined-by-client?error=consent+request+denied&state={state}\n```\n\nParameters:\n- `error`: A brief description of the issue.\n- `state`: The validation string provided by the Client in step 1.\n\n### Retrieving Access Token\nYou must make a POST request to the token endpoint to get an access token, before the code expires:\n\n```\ncurl -X POST \\\n https://login.ouropal.com/oauth2/token \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'code={code}&client_id={client_id}&redirect_uri={url_encoded_redirect}&client_secret={client_secret}&grant_type=authorization_code'\n```\n\nParameters:\n- `code`\n- `client_id`: Client ID provided by Opal.\n- `client_secret`: Client secret provided by Opal.\n- `grant_type`: Set value to authorization_code .\n- `redirect_uri`: Optional.\n\nIf successful, a JSON-formatted response body will contain the access_token and refresh_token:\n\n```json\n{\n \"access_token\":\"ABC123\",\n \"token_type\":\"bearer\",\n \"expires_in\":3600,\n \"refresh_token\":\"DEF456\",\n \"scope\":\"offline_access\"\n}\n```\n\n### Refreshing an Access Token\nOnce the access_token expires, you may generate a new one at the same token endpoint, but with different parameters.\nNote that in this request, a \"refresh_token\" parameter is used instead of \"code\", and the \"grant_type\" value is now \"refresh_token\" instead of \"authorization_code\".\n\n```\ncurl -X POST \\\n https://login.ouropal.com/oauth2/token \\\n -H 'Content-Type: application/x-www-form-urlencoded' \\\n -d 'refresh_token={refresh_token}&client_id={client_id}&redirect_uri={url_encoded_redirect}&client_secret={secret}&grant_type=refresh_token'\n```\n\nParameters:\n- `client_id`: Client ID provided by Opal.\n- `client_secret`: Client secret provided by Opal.\n- `grant_type`: Set value to refresh_token .\n- `redirect_uri`: Optional.\n- `refresh_token`: Refresh token value\n\n### Making Authenticated Requests\n\nSet an authorization header in your requests, specifying your access token as documented here: https://tools.ietf.org/html/rfc6750#section-2.1.\n\n**NOTE** that the `Authorization` header supercedes the `Session-Token` header described in the documentation for many endpoints. Specifying an `Authorization` header means you do not need to specify a `Session-Token` header.\n\n```\nAuthorization: Bearer ACCESS_TOKEN\n```\n\nFor example:\n```\n GET /resource HTTP/1.1\n Host: server.example.com\n Authorization: Bearer mF_9.B5f-4.1JqM\n```\n\n### Client Revoke/Rolling OAuth secrets\nClient secrets must be kept secret and not exposed outside of the token retrieval requests. If a secret has been potentially compromised, please notify Opal as soon as possible and let us know the OAuth client id associated with the secret. We will roll/update the secret, which will invalidate all existing access and refresh tokens. Invalidating tokens will cause users to need to reauthenticate, but consent should be remembered.\n" servers: - url: https://login.ouropal.com tags: - name: Experimental paths: /{workspace_id}/experimental/plans/{plan_id}: get: tags: - Experimental operationId: ExperimentalReadPlanBFFV1 description: Experimental endpoint to get a Plan, assuming block/plan rearchitecture. summary: Get a Plan. 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: plan_id in: path required: true description: The ID of the Plan. schema: type: string format: uuid responses: '200': description: The requested Plan content: application/json: schema: type: object required: - data properties: data: type: object required: - blocks - categories - charts - created_at - custom_field_values - description - effective_privacy - id - is_private - key_dates - kind - owner_id - parent_block_id - parent_block_view_id - settings - title - updated_at additionalProperties: false properties: blocks: type: object required: - by_id - by_category_with_position additionalProperties: false properties: by_category_with_position: type: object description: 'An object where the keys represent a Category `id` and the value is a list of objects describing the positions of block within the category. ' additionalProperties: type: array items: type: object additionalProperties: false required: - duration - end_at - id - row_index - start_at properties: duration: type: - string - 'null' description: 'ISO 8601 duration in days (P{n}D). Week and month durations are normalized to days when start_at is set. ' end_at: type: - string - 'null' format: ISO8601 deprecated: true description: 'DEPRECATED: migrate to `duration`.' id: type: string format: uuid row_index: type: integer description: 'Signifies the vertical row offset within a swimlane. ' start_at: type: - string - 'null' format: ISO8601 description: The starting date of the block as an ISO8601 date with no timestamp. by_id: type: object description: 'An object where the keys represent a Block `id` and the value is a full Block object. Used for fast access to a block by its `id` when used in conjunction with the `by_category_with_position` structure. ' additionalProperties: type: object required: - category_id - category_type - child_plan_id - color - connectors - created_at - description - duration - end_date - id - image_id - is_template - is_workspace_wide_template - owner_id - paired_moment_board_object_ids - paired_moment_id - row_index - start_at - template_description - template_name - title - y_scale additionalProperties: false properties: category_id: type: - string - 'null' format: uuid category_type: allOf: - 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). child_plan_id: type: - string - 'null' color: type: - string - 'null' connectors: type: array items: type: object required: - id - view_id - category_id additionalProperties: false properties: id: type: string format: uuid view_id: type: string format: uuid category_id: type: - string - 'null' format: uuid created_at: type: string format: ISO8601 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: ISO8601 deprecated: true description: 'DEPRECATED: migrate to `duration`.' id: type: string format: uuid image_id: type: - string - 'null' format: uuid is_template: type: boolean is_workspace_wide_template: type: boolean owner_id: type: string format: uuid paired_moment_board_object_ids: type: array items: 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. row_index: type: integer start_at: type: - string - 'null' format: ISO8601 template_description: type: - string - 'null' template_name: type: - string - 'null' title: type: string y_scale: type: integer categories: type: object required: - by_id - hierarchy additionalProperties: false properties: by_id: type: object description: 'An object where the keys represent a Category `id` and the value is a timeline_category object. Used for fast access to a category by its `id` when used in conjunction with the `hierarchy` structure. ' additionalProperties: type: object required: - chart_id - id - image_url - kind - position - settings - title additionalProperties: false properties: chart_id: type: - string - 'null' format: uuid id: type: string format: uuid image_url: type: - string - 'null' kind: type: string description: 'Indicates the variant of category this is. In the case of a smart collection, this the top level container is always "smart_swimlane" while its child categories are always "derived_swimlane" ' enum: - derived_swimlane - graph_swimlane - group - smart_swimlane - swimlane position: type: integer settings: oneOf: - type: object additionalProperties: false required: - row_size - template_id - type - view_mode properties: type: allOf: - 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). row_size: type: string enum: - small - medium - large template_id: type: - string - 'null' format: uuid view_mode: type: string enum: - default - condensed - type: object additionalProperties: false required: - resource_type properties: resource_type: type: string enum: - user - user_group title: type: - string - 'null' hierarchy: type: array items: type: object required: - id - children additionalProperties: false properties: id: type: string format: uuid description: The ID of a category. children: type: array items: type: object required: - id - children additionalProperties: false properties: id: type: string format: uuid description: The ID of a category. children: type: array maxItems: 0 charts: type: object required: - by_id properties: by_id: type: object description: 'An object where the keys represent a Chart `id` and the value is a full Chart object. Used for fast access to a chart by its `id` when used in conjunction with category''s chart_id property. ' additionalProperties: type: object required: - data - id - title additionalProperties: false properties: data: type: - object - 'null' required: - seriesData - seriesKeys additionalProperties: false properties: seriesData: type: array items: type: object required: - epochDate properties: epochDate: type: integer seriesKeys: type: array items: type: string id: type: string format: uuid title: type: - string - 'null' created_at: type: string format: date-time description: The timestamp when the plan was created. custom_field_values: type: object description: 'An object keyed by Block `id`. Each value is an object keyed by custom field `id`, allowing an O(1) lookup of a block''s value for a particular custom field. Each entry carries an `association` discriminator (`"direct"` or `"inherited"`) indicating whether the value is set directly on the block or cascaded from a parent block; a directly-set value takes precedence over an inherited one for the same custom field. An empty object is emitted for blocks with no custom field values set. ' additionalProperties: type: object additionalProperties: type: object title: Custom Field Value required: - id - custom_field_id - value - type - association additionalProperties: false properties: id: type: string format: uuid description: The unique id of the block_custom_field_value record. custom_field_id: type: string format: uuid description: The id of the custom field this value is for. type: type: string enum: - textarea - singleSelect - date - multiSelect - url - usersSelect description: The `system_type` of the underlying custom field. association: type: string enum: - direct - inherited description: '`"direct"` if the value is set directly on the block; `"inherited"` if the value cascades from a parent block. ' value: description: The shape of this field varies by `type`. oneOf: - title: Textarea type: object required: - value properties: value: type: - string - 'null' description: The text content. - title: Single Select type: object required: - id properties: id: type: - string - 'null' format: uuid description: The selected option ID. - title: Multi Select type: object required: - ids properties: ids: type: array description: List of selected option IDs. items: type: string format: uuid - title: Date type: object required: - value properties: value: type: - string - 'null' format: date-time description: The selected date. - title: URL type: object required: - url - label properties: url: type: string format: uri description: The URL value. label: type: - string - 'null' description: Display label for the URL. - title: Users Select type: object required: - user_ids - group_ids properties: user_ids: type: array description: User UUIDs selected for this field. items: type: string format: uuid group_ids: type: array description: User group UUIDs selected for this field. items: type: string format: uuid description: type: string description: Description of the plan. effective_privacy: type: string enum: - whole_workspace - some_but_not_all description: 'The effective privacy of a plan is calculated based on all direct and inherited access. If a plan 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`. ' id: type: string format: uuid is_private: type: boolean description: 'DEPRECATED: Prefer using `effective_privacy`. Whether the plan is private/invite-only (i.e. does not inherit from the workspace.) ' deprecated: true owner_id: type: string format: uuid description: The UUID of the view resource's owner. parent_block_id: type: string format: uuid description: The UUID of the parent block associated with the view. parent_block_view_id: type: - string - 'null' format: uuid description: The plan ID that the parent block belongs to. Present when the plan is nested inside another plan's block, null for root plans. key_dates: type: array description: Key Dates on the Plan which have a `start_date` within the Block's date range (start_date to start_date + duration). items: oneOf: - type: object required: - color - end_date - id - start_date - title additionalProperties: false properties: color: type: - string - 'null' end_date: type: - string - 'null' format: ISO8601 id: type: string format: uuid start_date: type: string format: ISO8601 title: type: string kind: type: string enum: - plan description: Describes the type of view this object is. settings: type: object additionalProperties: false required: - category_type - colors - default_timescale - end_at - start_at - start_month_index - start_weekday_index - valid_end_at - valid_start_at - show_smart_swimlane_datasource - swimlane_title_column_width properties: category_type: allOf: - type: object required: - deactivated_at - description - id - name - supported_paired_type additionalProperties: false properties: deactivated_at: type: - string - 'null' format: ISO8601 description: type: - string - 'null' id: type: string format: uuid name: type: string 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). colors: type: array description: List of colors present in the view. items: oneOf: - type: object required: - color - id - label additionalProperties: false properties: color: type: string id: type: string format: uuid label: type: - string - 'null' default_timescale: type: string enum: - day - week - month - quarter description: Describes the default fidelity of the plan's layout. 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 to, 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. valid_start_at: type: string format: date description: 'Specifies the minimum start_at block value if the plan contains blocks. A plan cannot start_at at a value later than this date. ' valid_end_at: type: string format: date description: 'Specifies the maximum end_at block value if the plan contains blocks. A plan cannot end_at at a value earlier than this date. ' 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. title: type: string updated_at: type: string format: date-time description: The timestamp when the plan was last updated. example: data: id: 573138cf-f5bf-44da-b81b-afbe54139915 kind: plan parent_block_id: a2e88637-09ee-427e-8672-93efc47e46dd created_at: '2023-01-01T00:00:00.000Z' updated_at: '2023-06-01T00:00:00.000Z' custom_field_values: 4d22b564-1d93-41ef-be0a-3a41b11df73b: cf-1: id: bcfv-1 custom_field_id: cf-1 type: textarea value: value: Some notes association: direct cf-2: id: bcfv-2 custom_field_id: cf-2 type: usersSelect value: user_ids: - user-uuid-1 group_ids: - group-uuid-1 association: inherited 15e34c9f-1d93-41ef-be0a-3a41b11df73b: {} blocks: by_id: 4d22b564-1d93-41ef-be0a-3a41b11df73b: category_id: 41c71117-0d45-4d60-a5de-4abd60f881cf category_type: null child_plan: id: cf95f72d-cfa6-4856-a1fc-cddbcea34e04 valid_end_at: null valid_start_at: null color: null end_at: '2024-07-01T00:00:00.000Z' duration: P150D id: 4d22b564-1d93-41ef-be0a-3a41b11df73b image_id: 15e34c9f-827f-4f10-b6d7-7b725767a945 is_template: false is_workspace_wide_template: false owner_id: 4eea039c-3f5d-4f2d-baa3-126b2933a024 paired_moment_board_object_ids: [] paired_moment_id: null row_index: 0 start_at: '2024-02-01T00:00:00.000Z' template_description: null template_name: null title: Block in Swimlane A y_scale: 1 15e34c9f-1d93-41ef-be0a-3a41b11df73b: category_id: 41c71117-0d45-4d60-a5de-4abd60f881cf category_type: null child_plan: null color: null end_at: '2024-07-01T00:00:00.000Z' duration: P150D id: 15e34c9f-1d93-41ef-be0a-3a41b11df73b image_id: 4eea039c-3f5d-4f2d-baa3-126b2933a024 is_template: false is_workspace_wide_template: false owner_id: 15e34c9f-827f-4f10-b6d7-7b725767a945 paired_moment_board_object_ids: [] paired_moment_id: null row_index: 0 start_at: '2024-02-01T00:00:00.000Z' template_description: null template_name: null title: Block in Swimlane A y_scale: 1 0c642685-e2bb-42da-ac29-54091cde4d29: category_id: null category_type: null child_plan: null color: null end_at: null duration: null id: 0c642685-e2bb-42da-ac29-54091cde4d29 image_id: 15e34c9f-827f-4f10-b6d7-7b725767a945 is_template: false is_workspace_wide_template: false owner_id: 4eea039c-3f5d-4f2d-baa3-126b2933a024 paired_moment_board_object_ids: [] paired_moment_id: null row_index: 0 start_at: '2024-02-01T00:00:00.000Z' swimlane_id: null template_description: null template_name: null title: Pre-Planning Block y_scale: 1 by_category_with_position: 41c71117-0d45-4d60-a5de-4abd60f881cf: - id: 4d22b564-1d93-41ef-be0a-3a41b11df73b end_at: '2024-07-01T00:00:00.000Z' duration: P150D row_index: 0 start_at: '2024-02-01T00:00:00.000Z' a72afbb8-7091-4570-ae21-411fe1a47800: - id: 15e34c9f-1d93-41ef-be0a-3a41b11df73b end_at: '2024-07-01T00:00:00.000Z' duration: P150D row_index: 0 start_at: '2024-02-01T00:00:00.000Z' preplanning_blocks: - id: 0c642685-e2bb-42da-ac29-54091cde4d29 end_at: '2024-07-01T00:00:00.000Z' duration: P150D row_index: 0 start_at: '2024-02-01T00:00:00.000Z' categories: by_id: c83f3530-4853-4b62-850b-dff1cc0532e3: id: c83f3530-4853-4b62-850b-dff1cc0532e3 title: Swimlane Group 1 kind: group position: 0 settings: row_size: medium type: null 41c71117-0d45-4d60-a5de-4abd60f881cf: id: 41c71117-0d45-4d60-a5de-4abd60f881cf title: Swimlane A kind: swimlane position: 0 settings: row_size: medium type: null 91dcf3ea-e74b-4d45-9b89-085d933b7c39: id: 91dcf3ea-e74b-4d45-9b89-085d933b7c39 title: Swimlane B kind: swimlane position: 1 settings: row_size: medium type: null a72afbb8-7091-4570-ae21-411fe1a47800: id: a72afbb8-7091-4570-ae21-411fe1a47800 title: Swimlane C kind: swimlane position: 1 settings: row_size: medium type: null aa4f2f2e-b548-4a42-9135-66490d48c85e: id: aa4f2f2e-b548-4a42-9135-66490d48c85e title: Chart kind: chart position: 2 settings: row_size: medium type: null hierarchy: - id: c83f3530-4853-4b62-850b-dff1cc0532e3 children: - id: 41c71117-0d45-4d60-a5de-4abd60f881cf children: [] - id: 91dcf3ea-e74b-4d45-9b89-085d933b7c39 children: [] - id: a72afbb8-7091-4570-ae21-411fe1a47800 children: [] - id: aa4f2f2e-b548-4a42-9135-66490d48c85e children: [] charts: by_category: aa4f2f2e-b548-4a42-9135-66490d48c85e: - 4875ec67-0b25-4f0c-9558-22b99d887c32 by_id: 4875ec67-0b25-4f0c-9558-22b99d887c32: id: 4875ec67-0b25-4f0c-9558-22b99d887c32 title: A chart! data: headers: - Date - Series A data: - Date: '2027-07-01T00:00:00.000Z' Series A: 100 - Date: '2027-08-01T00:00:00.000Z' Series A: 150 key_dates: - id: ec697303-3586-4352-927f-66736ccbc9ea title: Halloween color: '#FF0000' start_date: '2024-10-31' end_date: null settings: category_type: null colors: - id: c558f617-c9d1-4ff6-ad4c-c0f90c863d38 label: pink color: '#facade' - id: bdd034ca-fa91-4c37-b0f8-1cee912bb0db label: null color: '#ff0000' default_timescale: month end_at: '2024-12-31T00:00:00.000Z' start_at: '2024-01-01T00:00:00.000Z' start_month_index: 0 start_weekday_index: 0 valid_start_at: '2024-02-01T00:00:00.000Z' valid_end_at: '2024-12-01T00:00:00.000Z' '401': description: Unauthorized content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: status: type: string title: type: string detail: type: string required: - status '403': description: Forbidden content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: status: type: string title: type: string detail: type: string 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 title: type: string detail: type: string required: - status /{workspace_id}/experimental/blocks/{block_id}: get: tags: - Experimental operationId: ExperimentalReadBlockBFFV1 description: Experimental endpoint to get a Block, assuming block/plan rearchitecture. 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 - details - effective_privacy - id - is_private - is_template - is_workspace_wide_template - child_plan_id - owner_id - paired_moment_id - rich_text_document_id - start_date - template_description - template_name - title - view_id 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. details: type: object additionalProperties: false required: - color - connectors - description - last_updated_date - image_id - category - category_type - custom_fields - custom_field_values - inherited_custom_field_values - in_support_of_category_type_ids properties: 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' last_updated_date: type: string format: date-time description: An ISO8601 datetime describing the last time the block or its related resources was updated. image_id: type: - string - 'null' format: uuid custom_fields: type: array description: Custom fields associated with this block. items: oneOf: - type: object required: - id - display_name - type - options - deactivated_options - association_type - data additionalProperties: false properties: id: type: string format: uuid description: The ID of the custom field. display_name: type: string description: The display name for this custom field. type: type: string enum: - textarea - singleSelect - date - multiSelect - url - usersSelect association_type: type: string enum: - direct - inherited description: Indicates whether the field is directly associated with the block or inherited from another source. options: type: array description: Active options for this custom field (for select types). items: type: object required: - id - display_name - position properties: id: type: string format: uuid display_name: type: string position: type: integer deactivated_options: type: array description: Deactivated options for this custom field (for select types). items: type: object required: - id - display_name - position properties: id: type: string format: uuid display_name: type: string position: type: integer data: type: - object - 'null' required: - id - value properties: id: type: string format: uuid value: oneOf: - title: Textarea type: object required: - value properties: value: type: string description: The text content. - title: Multi Select type: object required: - ids properties: ids: type: array description: List of selected option IDs. items: type: string format: uuid - title: Single Select type: object required: - id properties: id: type: string format: uuid description: The selected option ID. - title: Date type: object required: - value properties: value: type: string format: date-time description: The selected date. - title: URL type: object required: - url - label properties: url: type: string format: uri description: The URL value. label: type: - string - 'null' description: Display label for the URL. - title: Users Select type: object properties: user_ids: type: array items: type: string format: uuid description: An array of user UUID strings representing the selected users. group_ids: type: array items: type: string format: uuid description: An array of user group UUID strings representing the selected groups. custom_field_values: type: array description: Custom field values associated with this block. items: oneOf: - type: object required: - id - display_name - type - options - deactivated_options - association_type - data additionalProperties: false properties: id: type: string format: uuid description: The ID of the custom field. display_name: type: string description: The display name for this custom field. type: type: string enum: - textarea - singleSelect - date - multiSelect - url - usersSelect association_type: type: string enum: - direct - inherited description: Indicates whether the field is directly associated with the block or inherited from another source. options: type: array description: Active options for this custom field (for select types). items: type: object required: - id - display_name - position properties: id: type: string format: uuid display_name: type: string position: type: integer deactivated_options: type: array description: Deactivated options for this custom field (for select types). items: type: object required: - id - display_name - position properties: id: type: string format: uuid display_name: type: string position: type: integer data: type: - object - 'null' required: - id - value properties: id: type: string format: uuid value: oneOf: - title: Textarea type: object required: - value properties: value: type: string description: The text content. - title: Multi Select type: object required: - ids properties: ids: type: array description: List of selected option IDs. items: type: string format: uuid - title: Single Select type: object required: - id properties: id: type: string format: uuid description: The selected option ID. - title: Date type: object required: - value properties: value: type: string format: date-time description: The selected date. - title: URL type: object required: - url - label properties: url: type: string format: uri description: The URL value. label: type: - string - 'null' description: Display label for the URL. - title: Users Select type: object properties: user_ids: type: array items: type: string format: uuid description: An array of user UUID strings representing the selected users. group_ids: type: array items: type: string format: uuid description: An array of user group UUID strings representing the selected groups. inherited_custom_field_values: type: array description: Custom field values cascaded down from a parent block type. items: oneOf: - type: object required: - id - display_name - type - options - deactivated_options - association_type - data additionalProperties: false properties: id: type: string format: uuid description: The ID of the custom field. display_name: type: string description: The display name for this custom field. type: type: string enum: - textarea - singleSelect - date - multiSelect - url - usersSelect association_type: type: string enum: - direct - inherited description: Indicates whether the field is directly associated with the block or inherited from another source. options: type: array description: Active options for this custom field (for select types). items: type: object required: - id - display_name - position properties: id: type: string format: uuid display_name: type: string position: type: integer deactivated_options: type: array description: Deactivated options for this custom field (for select types). items: type: object required: - id - display_name - position properties: id: type: string format: uuid display_name: type: string position: type: integer data: type: - object - 'null' required: - id - value properties: id: type: string format: uuid value: oneOf: - title: Textarea type: object required: - value properties: value: type: string description: The text content. - title: Multi Select type: object required: - ids properties: ids: type: array description: List of selected option IDs. items: type: string format: uuid - title: Single Select type: object required: - id properties: id: type: string format: uuid description: The selected option ID. - title: Date type: object required: - value properties: value: type: string format: date-time description: The selected date. - title: URL type: object required: - url - label properties: url: type: string format: uri description: The URL value. label: type: - string - 'null' description: Display label for the URL. - title: Users Select type: object properties: user_ids: type: array items: type: string format: uuid description: An array of user UUID strings representing the selected users. group_ids: type: array items: type: string format: uuid description: An array of user group UUID strings representing the selected groups. in_support_of_category_type_ids: type: array description: A list of IDs that the block's category_type has been configured to support. items: type: string format: uuid 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.' 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 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. is_workspace_wide_template: type: boolean description: Whether this template is available workspace-wide. default: false child_plan_id: type: - string - 'null' format: uuid description: The UUID of the child plan, if one exists for this block. owner_id: type: string format: uuid description: The UUID of the block owner. paired_moment_id: type: - string - 'null' format: uuid description: The UUID of the paired moment, if one exists for this block. rich_text_document_id: type: string format: uuid view_id: type: - string - 'null' format: uuid description: The UUID of the view (plan) associated with the block, if one exists for this block. start_date: type: - string - 'null' format: date description: An ISO8601 date describing the start of the block. template_description: type: - string - 'null' description: Description of the template when `is_template` is `true`. template_name: type: - string - 'null' description: Name of the template when `is_template` is `true`. title: type: string example: data: boards: - id: a9f38c4d-8a3c-439c-8344-aaed38e659ca description: null title: A New Board creator: id: 4eea039c-3f5d-4f2d-baa3-126b2933a024 legacy_id: '30' full_name: Gaylene Treutel avatar_url: null image_source: null is_public: false details: category: id: 8d3e65de-d457-4653-a859-45d4867cb1cd ancestor_titles: - Swimlane Group A title: Swimlane A1 category_type: deactivated_at: null description: Cost Centers id: 3757333e-109a-4365-81c2-50a957f13477 name: Department supported_paired_type: null color: '#00A148' custom_field_values: - association_type: inherited data: null deactivated_options: - display_name: drive id: 6f245196-df88-447b-8130-8a058625c88e position: 0 display_name: Multi Select Dropdown visionary id: 70d42722-8f7a-402d-a5ce-3858d664e360 options: - display_name: enable id: 2719868e-7660-4229-a3f8-7dbb330f5fb4 position: 1 - display_name: engage id: 63e3e818-8f39-4726-8cb5-27822aede64b position: 2 type: multiSelect - association_type: inherited data: null deactivated_options: - display_name: monetize id: b197ecb6-b24f-4bbb-b758-a150c28aeea8 position: 0 display_name: Single Select Dropdown efficient id: f697098b-c2cb-4429-b564-7905fca0e1fa options: - display_name: engineer id: bff8566c-5ad3-4f50-a43d-b73718dd8e38 position: 1 - display_name: envisioneer id: 9deb3a0a-3b5f-445a-95d0-3b13defb37be position: 2 type: singleSelect inherited_custom_field_values: [] in_support_of_category_type_ids: - b69138d6-be91-44f7-b6ef-6e9c5abed51d description: Halloween Fun image_id: 3e5b8ba4f763-959d-433d-bd8c-a299d65c last_updated_date: '2024-06-02T08:14:23.345Z' end_date: '2024-10-31T00:00:00.000Z' id: a299d65c-959d-433d-bd8c-3e5b8ba4f763 is_private: true is_template: false is_workspace_wide_template: false template_description: null template_name: null owner: id: 4eea039c-3f5d-4f2d-baa3-126b2933a024 legacy_id: '30' full_name: Gaylene Treutel avatar_url: null paired_moment_id: ca065865-5edc-4246-8fa7-97bb98a23307 title: Halloween 2024 rich_text_document_id: c5f3e736-a506-4328-8d53-31fc055aafea start_date: '2024-10-01T00:00:00.000Z' view_id: e01b9a23-01f4-447d-96fd-03188fc9edd1 '401': description: Unauthorized content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: status: type: string title: type: string detail: type: string required: - status '403': description: Forbidden content: application/json: schema: type: object required: - errors properties: errors: type: array items: type: object properties: status: type: string title: type: string detail: type: string 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 title: type: string detail: type: string required: - status components: securitySchemes: 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 x-tagGroups: - name: ⚠️ Unstable tags: - Plans - Blocks - Custom Fields - name: ℹ️ Proposed tags: - Moments - Smart Blocks - In Market - name: 🔮 Experimental tags: - Experimental