Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
All 92 tools →
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/opal-smart-blocks-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no email required.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
version: 3.0.0
title: Asgard BFF Smart Blocks 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: Smart Blocks
paths:
/{workspace_id}/smart_blocks:
get:
tags:
- Smart Blocks
operationId: ReadSmartBlocksBFFV1
summary: Get a collection of blocks.
security:
- oauth2:
- offline_access
- api_key:
- Session-Token
parameters:
- name: workspace_id
in: path
required: true
description: The ID of the current workspace to pull blocks from.
schema:
type: string
format: uuid
- name: filter
in: query
description: 'Filters for limiting the results.
'
required: true
schema:
type: object
properties:
plan_ids:
type: array
description: 'A comma separated list of Plan Ids.
If provided, only blocks from these plans will be returned.
'
items:
type: string
format: uuid
grandparent_plan_ids:
type: array
description: 'A list of plan ids to aggregate sub-plan blocks from. e.g. a plan in this list will not return its directly associated blocks, but instead all of the blocks found on the sub-plans of its directly associated blocks.
'
items:
type: string
format: uuid
type_ids:
type: array
description: 'A comma-separated list of type ids (also known as `category_type`) to filter down the collection of blocks.
'
items:
type: string
format: uuid
start_at:
description: 'Filter by the block’s scheduled `start_at` date. Supports the `gteq` (greater than or equal to) and `lteq` (less than or equal to) operators, e.g. `filter[start_at][lteq]=2026-07-31`, with `YYYY-MM-DD` values.
Blocks without a `start_at` are never returned when this filter is set (a null date satisfies no comparison).'
type: object
additionalProperties: false
properties:
gteq:
type: string
format: date
lteq:
type: string
format: date
end_at:
description: 'Filter by the block’s derived active-period end date. A block’s active period runs from its `start_at` to its effective end date — `start_at` plus `duration`, or `start_at` for blocks with no `duration`. `end_at` is not a stored attribute; it is computed for comparison purposes.
Supports the `gteq` (greater than or equal to) and `lteq` (less than or equal to) operators, e.g. `filter[end_at][gteq]=2026-07-01`, with `YYYY-MM-DD` values.
Combine `filter[end_at][gteq]` with `filter[start_at][lteq]` to return only blocks whose active period intersects a window (e.g. “what is happening in July?”). Blocks without a `start_at` are never returned when this filter is set (a null date satisfies no comparison).'
type: object
additionalProperties: false
properties:
gteq:
type: string
format: date
lteq:
type: string
format: date
custom_fields:
description: 'An object keyed by custom field ids.
For singleSelect and multiSelect fields the value is an array of custom field option ids. For usersSelect (People) fields the value is an object with `user_ids` and `group_ids` arrays.
Acts as an inclusive filter within a field and exclusive across fields. In other words, blocks must match on at least one selected value for every custom field in the filter.'
type: object
additionalProperties:
oneOf:
- type: array
items:
type: string
format: uuid
- type: object
additionalProperties: false
required:
- user_ids
- group_ids
properties:
user_ids:
type: array
items:
type: string
format: uuid
group_ids:
type: array
items:
type: string
format: uuid
style: deepObject
explode: true
- name: group_by
in: query
description: 'Controls the grouping of the returned blocks. One of the `group_by` parameters is required for this endpoint.
'
required: true
schema:
type: object
required:
- strategy
properties:
custom_field_id:
type:
- string
- 'null'
format: uuid
description: 'ID of a custom field. Must be a "Single Select" or "Multi Select" custom field type.
When using a custom field for grouping, the blocks will be collected by the options defined on that field as they are set on the block. That is - blocks with an option or options set for this field will be collected in a group for that option''s name. In the case of a "Multi Select" custom field, a block with multiple options selected will appear in multiple collections.
Blocks without any relevant options selected for the given field will be collected under a "no_value" collection.
'
strategy:
type: string
enum:
- category_type
- custom_field
description: 'Strategy used to group blocks. If set to `category_type`, the blocks will be organized according to their category_type relationship.
If set to `custom_field`, then the `group_by[custom_field_id]` should have a custom_field''s `id` set to indicate which custom field the blocks should be grouped by.
'
exclude_empty_groupings:
type: boolean
default: true
description: 'Dictates whether to return data for group_by fields that do not have any corresponding blocks. These empty fields will be excluded by default and will only be returned when this value is set to false.
'
style: deepObject
explode: true
responses:
'200':
description: The requested blocks
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: object
required:
- datasource
- categories
- blocks
additionalProperties: false
properties:
datasource:
type: object
required:
- filter
- group_by_strategy
- group_by_custom_field
- group_by_exclude_empty_groupings
additionalProperties: false
properties:
filter_set_id:
type: string
format: uuid
filter:
type: object
description: 'The filter setting of the returned collection.
'
additionalProperties: false
properties:
custom_field_options:
type: array
items:
type: object
required:
- id
- name
additionalProperties: false
properties:
id:
type: string
format: uuid
name:
type:
- string
- 'null'
plans:
type: array
items:
type: object
required:
- id
- name
additionalProperties: false
properties:
id:
type: string
format: uuid
name:
type:
- string
- 'null'
grandparent_plans:
type: array
items:
type: object
required:
- id
- name
additionalProperties: false
properties:
id:
type: string
format: uuid
name:
type:
- string
- 'null'
types:
type: array
items:
allOf:
- type: object
required:
- id
- name
additionalProperties: false
properties:
id:
type: string
format: uuid
name:
type:
- string
- 'null'
- required:
- name
properties:
name:
type: string
users_select:
type: object
description: Tracks the users and groups selected for each usersSelect. Only present if there's a smart swimlane filter for at least one usersSelect (People) field.
additionalProperties:
type: object
additionalProperties: false
required:
- users
- groups
properties:
users:
type: array
items:
allOf:
- type: object
required:
- id
- name
additionalProperties: false
properties:
id:
type: string
format: uuid
name:
type:
- string
- 'null'
- required:
- name
properties:
name:
type: string
groups:
type: array
items:
allOf:
- type: object
required:
- id
- name
additionalProperties: false
properties:
id:
type: string
format: uuid
name:
type:
- string
- 'null'
- required:
- name
properties:
name:
type: string
group_by_custom_field:
type:
- object
- 'null'
description: 'Details about the custom field this Smart Swimlane is grouped by.
'
required:
- id
- name
- type
additionalProperties: false
properties:
id:
type: string
format: uuid
name:
type: string
type:
type:
- string
- 'null'
description: The field's `custom_field_type.system_type`. Allows the frontend to customize how data is presented.
group_by_strategy:
type: string
description: Strategy for grouping blocks.
enum:
- category_type
- custom_field
group_by_exclude_empty_groupings:
type: boolean
default: true
description: 'Dictates whether to return data for group_by fields that do not have any corresponding blocks. These empty fields will be excluded by default and will only be returned when this value is set to false.
'
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
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:
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/opal/refs/heads/main/openapi/opal-smart-blocks-api-openapi.yml