Opal Label Sets API

openapi: 3.2.0
info:
  version: 2.0.0
  title: Opal Label Sets API
  license:
    name: Opal API License
    url: https://www.workwithopal.com/api-license
  description: The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
servers:
- url: https://login.ouropal.com
tags:
- name: Label Sets
paths:
  /label_sets/v2:
    get:
      tags:
      - Label Sets
      operationId: ReadLabelSetsV2
      summary: Get label sets available to the authenticated user
      security:
      - oauth2:
        - offline_access
      - api_key:
        - Session-Token
      parameters:
      - name: page
        in: query
        required: false
        description: 'Request a particular page using `offset` and `limit`. When not specified, the `offset` defaults to 0 and the `limit` defaults to 150.

          '
        schema:
          type: object
          properties:
            offset:
              type: integer
              minimum: 0
            limit:
              type: integer
              minimum: 0
              maximum: 800
        style: deepObject
        explode: true
      - name: fields
        in: query
        description: A JSON:API [sparse fieldset](https://jsonapi.org/format/#fetching-sparse-fieldsets) declaration.
        required: false
        schema:
          type: object
          properties:
            label:
              type: string
            label_set:
              type: string
        style: deepObject
        explode: true
      - name: filter
        in: query
        description: Filters for limiting the results.
        required: false
        schema:
          type: object
          properties:
            is_active:
              type: boolean
              description: 'By default, endpoint will show only active label sets. Specify `filter[is_active]=false` to only return inactive label sets. Specify `filter[is_active]=true,false` to return all label sets.

                '
            brand_id:
              type: array
              description: 'The IDs of the workspaces to which results should be filtered.

                "Workspace ID" and "Brand ID" are synonymous.

                Comma separated list of IDs. If included, will only fetch resources associated with these brands. If not included, will return resources associated with all brands that the user belongs to. For example, `filter[brand_id]=1` will fetch all resources associated with brand 1, while `filter[brand_id]=1,2,3` will fetch any resources associated with brands 1, 2, or 3.

                '
              items:
                type: integer
        style: deepObject
        explode: true
      - name: include
        in: query
        required: false
        description: A comma separated list of related objects to include
        schema:
          type: array
          items:
            type: string
            enum:
            - labels
            - parent_label
        style: form
        explode: false
      responses:
        '200':
          description: A collection of label sets.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      title: label_set
                      type: object
                      required:
                      - id
                      - type
                      - attributes
                      - relationships
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          pattern: ^[0-9]+$
                        type:
                          type: string
                          enum:
                          - label_set
                        attributes:
                          type: object
                          required:
                          - name
                          - label_sort_method
                          - is_active
                          - is_shared
                          - uuid
                          additionalProperties: false
                          properties:
                            name:
                              type: string
                            uuid:
                              type: string
                              format: uuid
                              description: A unique identifier for the label set.
                            is_active:
                              type: boolean
                              description: 'Determines whether the label set will be available to use in the Opal platform. Note that inactive label sets are only even exposed via API when specifically filtered for.

                                '
                            is_shared:
                              type: boolean
                              description: 'True when the label set is shared across workspaces.

                                '
                            label_sort_method:
                              type: string
                              default: oldest_first
                              enum:
                              - alphabetical
                              - newest_first
                              - oldest_first
                              - manual
                        relationships:
                          type: object
                          required:
                          - labels
                          - paired_custom_field
                          - parent_label
                          additionalProperties: false
                          properties:
                            labels:
                              type: object
                              required:
                              - data
                              additionalProperties: false
                              properties:
                                data:
                                  type: array
                                  items:
                                    type: object
                                    required:
                                    - id
                                    - type
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                      type:
                                        type: string
                                        enum:
                                        - label
                            paired_custom_field:
                              type: object
                              required:
                              - data
                              additionalProperties: false
                              properties:
                                data:
                                  type:
                                  - object
                                  - 'null'
                                  required:
                                  - id
                                  - type
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      format: uuid
                                    type:
                                      type: string
                                      enum:
                                      - custom_field
                            parent_label:
                              type: object
                              required:
                              - data
                              additionalProperties: false
                              properties:
                                data:
                                  type:
                                  - object
                                  - 'null'
                                  required:
                                  - id
                                  - type
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                    type:
                                      type: string
                                      enum:
                                      - label
                  included:
                    type: array
                    items:
                      oneOf:
                      - title: label
                        type: object
                        required:
                        - id
                        - type
                        - attributes
                        - relationships
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^[0-9]+$
                          type:
                            type: string
                            enum:
                            - label
                          attributes:
                            type: object
                            required:
                            - name
                            - color
                            - is_active
                            - uuid
                            additionalProperties: false
                            properties:
                              name:
                                type: string
                                description: The label's name. This value must be unique within the label's label set.
                              uuid:
                                type: string
                                format: uuid
                                description: A unique identifier for the label.
                              color:
                                type: string
                                description: The label's color. A hex color code without the '#' prefix. The color is settable on any non-shared label set, but today it is only rendered by the Opal platform when the label belongs to the workspace's primary label set. Broader rendering across non-primary label sets is upcoming.
                              is_active:
                                type: boolean
                                description: Enable or disable this label. Note that this is different than deleting and it is probably generally advisable to set is_active to false rather than deleting a label because deactivating can be undone via the API.
                              position:
                                type: integer
                                description: By default, the label position is not used and labels are sorted by creation date from oldest to newest. By request, Opal employees can set the sort order of labels within any label set to be `manual` which causes the labels to be sorted by their `position` instead.
                          relationships:
                            type: object
                            additionalProperties: false
                            properties:
                              label_set:
                                type: object
                                required:
                                - data
                                additionalProperties: false
                                properties:
                                  data:
                                    type: object
                                    required:
                                    - id
                                    - type
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                      type:
                                        type: string
                                        enum:
                                        - label_set
                  meta:
                    type: object
                    required:
                    - total
                    - page
                    - resource_type
                    properties:
                      resource_type:
                        type: string
                      total:
                        type: integer
                      page:
                        type: object
                        required:
                        - limit
                        - offset
                        properties:
                          limit:
                            type: integer
                          offset:
                            type: integer
        '400':
          description: Bad request
          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
        '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
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: This API uses OAuth 2.0 with the authorization code grant flow. You can find more detailed authentication instructions in the [Authentication Strategies](/api/documentation#section/Authentication-Strategies/OAuth-2.0) section.
      flows:
        authorizationCode:
          authorizationUrl: /oauth2/auth
          tokenUrl: /oauth2/token
          scopes:
            offline_access: Include this scope if you wish to receive a refresh token
    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: JSON:API
  tags:
  - Accounts
  - Activities
  - Annotations
  - Asset Reference Options
  - Asset Reference Usage Rights Options
  - Asset References
  - Assets
  - Brand Settings
  - Brands
  - Checkpoints
  - Content
  - Delivery Records
  - Label Sets
  - Labels
  - Messages
  - Moments
  - Phase Items
  - Placements
  - Post Types
  - Privacy
  - Reactions
  - Rich Texts
  - Services
  - Stamps
  - Stories
  - Url Uploads
  - User Domain Views
  - Users
  - Workflows
- name: Other
  tags:
  - Budgets
  - URL Previews
  - Search
  - Stories V1
- name: ⚠️  Unstable
  tags: []
- name: Additional Resources
  tags:
  - secondary_resources