{
  "swagger": "2.0",
  "info": {
    "title": "Marking service",
    "version": "0.1507.0",
    "description": "Send your API key as a bearer token: `Authorization: Bearer <api key>`."
  },
  "tags": [
    {
      "name": "MarkingService",
      "x-displayName": "Marking service",
      "description": "This service manages Markings, which are a mechanism to restrict access to data sources."
    }
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/authorization/markings/v1": {
      "post": {
        "operationId": "MarkingService_CreateMarking",
        "responses": {
          "200": {
            "schema": {
              "$ref": "#/definitions/Marking"
            },
            "x-example": {
              "rid": "<rid>",
              "id": "<id>",
              "description": "<description>",
              "authorizedGroups": {
                "groupRids": [
                  "<group rids>"
                ]
              },
              "symbol": {
                "icon": "<icon>"
              },
              "color": {
                "hexCode": "<hex code>"
              },
              "createdAt": "2026-01-01T00:00:00Z",
              "updatedAt": "2026-01-01T00:00:00Z",
              "isArchived": true
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/CreateMarkingRequest"
            },
            "x-example": {
              "id": "<id>",
              "description": "<description>",
              "authorizedGroups": {
                "groupRids": [
                  "<group rids>"
                ]
              },
              "symbol": {
                "icon": "<icon>"
              },
              "color": {
                "hexCode": "<hex code>"
              }
            }
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Create marking",
        "description": "Creates a marking. Throws HTTP 409 / gRPC 6 if a marking with the same ID already exists. Throws HTTP 403 / gRPC 7 if the user does not have permission to create a marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to read some of the specified groups."
      }
    },
    "/authorization/markings/v1/archive-batch": {
      "post": {
        "operationId": "MarkingService_ArchiveMarkings",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/ArchiveMarkingsResponse"
            },
            "x-example": {}
          }
        },
        "parameters": [
          {
            "name": "markingRids",
            "in": "body",
            "required": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "example": [
                "string"
              ]
            },
            "x-example": [
              "string"
            ]
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Archive markings",
        "description": "Archives markings. Archiving a marking is an idempotent operation that prevents further changes or applications of the marking. Archived markings will not appear in search but can be retrieved by `get` endpoints. Throws HTTP 403 / gRPC 7 if the user does not have permission to archive one or more of the markings or if any of the markings are not found. Throws HTTP 400 / gRPC 3 if the archived marking is currently applied to one or more resources."
      }
    },
    "/authorization/markings/v1/authorized-groups-by-marking": {
      "post": {
        "operationId": "MarkingService_GetAuthorizedGroupsByMarking",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/GetAuthorizedGroupsByMarkingResponse"
            },
            "x-example": {
              "authorizedGroupsByMarking": {
                "<key>": {
                  "groupRids": [
                    "<group rids>"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/GetAuthorizedGroupsByMarkingRequest"
            },
            "x-example": {
              "markingRids": [
                "<marking rids>"
              ]
            }
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Get authorized groups by marking",
        "description": "Gets the authorized Groups for each of a set of Markings. Markings that are not found or for which the user does not have permission to read will be filtered from the response. Groups for which the user does not have permission to read will be filtered from the response."
      }
    },
    "/authorization/markings/v1/batch-get": {
      "post": {
        "operationId": "MarkingService_BatchGetMarkings",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/BatchGetMarkingsResponse"
            },
            "x-example": {
              "markings": [
                {
                  "rid": "<rid>",
                  "id": "<id>",
                  "description": "<description>",
                  "authorizedGroups": {
                    "groupRids": [
                      "<group rids>"
                    ]
                  },
                  "symbol": {
                    "icon": "<icon>"
                  },
                  "color": {
                    "hexCode": "<hex code>"
                  },
                  "createdAt": "2026-01-01T00:00:00Z",
                  "updatedAt": "2026-01-01T00:00:00Z",
                  "isArchived": true
                }
              ]
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BatchGetMarkingsRequest"
            },
            "x-example": {
              "markingRids": [
                "<marking rids>"
              ]
            }
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Batch get markings",
        "description": "Gets multiple markings by RID. If a marking is not found or the user doesn't have permission to read it, it will not be included in the response."
      }
    },
    "/authorization/markings/v1/batch-get-metadata": {
      "post": {
        "operationId": "MarkingService_BatchGetMarkingMetadata",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/BatchGetMarkingMetadataResponse"
            },
            "x-example": {
              "markingMetadatas": [
                {
                  "rid": "<rid>",
                  "id": "<id>",
                  "description": "<description>",
                  "symbol": {
                    "icon": "<icon>"
                  },
                  "color": {
                    "hexCode": "<hex code>"
                  },
                  "createdAt": "2026-01-01T00:00:00Z",
                  "updatedAt": "2026-01-01T00:00:00Z",
                  "isArchived": true
                }
              ]
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/BatchGetMarkingMetadataRequest"
            },
            "x-example": {
              "markingRids": [
                "<marking rids>"
              ]
            }
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Batch get marking metadata",
        "description": "Gets metadata for multiple markings by RID. Metadata does not include the authorized groups. If a marking is not found or the user doesn't have permission to read it, it will not be included in the response."
      }
    },
    "/authorization/markings/v1/id/{id}": {
      "get": {
        "operationId": "MarkingService_GetMarkingById",
        "responses": {
          "200": {
            "schema": {
              "$ref": "#/definitions/Marking"
            },
            "x-example": {
              "rid": "<rid>",
              "id": "<id>",
              "description": "<description>",
              "authorizedGroups": {
                "groupRids": [
                  "<group rids>"
                ]
              },
              "symbol": {
                "icon": "<icon>"
              },
              "color": {
                "hexCode": "<hex code>"
              },
              "createdAt": "2026-01-01T00:00:00Z",
              "updatedAt": "2026-01-01T00:00:00Z",
              "isArchived": true
            }
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "type": "string",
            "pattern": "^[a-z][a-z0-9-]*$",
            "x-constraints": [
              "Matches `^[a-z][a-z0-9-]*$`."
            ]
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Get marking by ID",
        "description": "Gets a marking by its ID, a human-readable identifier unique within the org. Throws HTTP 403 / gRPC 7 if the user does not have permission to read the marking. Throws HTTP 403 / gRPC 5 if the marking is not found."
      }
    },
    "/authorization/markings/v1/markings-for-resources": {
      "post": {
        "operationId": "MarkingService_GetMarkingsForResources",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/GetMarkingsForResourcesResponse"
            },
            "x-example": {
              "resourceToMarkings": {
                "<key>": {
                  "appliedMarkings": [
                    {
                      "markingRid": "<marking rid>",
                      "appliedAt": "2026-01-01T00:00:00Z"
                    }
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/GetMarkingsForResourcesRequest"
            },
            "x-example": {
              "resources": [
                "<resources>"
              ]
            }
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Get markings for resources",
        "description": "Gets the requested resources and the markings applied to them. Since the number of markings applied to a resource is typically small, this endpoint will return all markings for each resource. Any unauthorized resources or markings will be filtered from the response."
      }
    },
    "/authorization/markings/v1/resource/{resource}/markings": {
      "post": {
        "operationId": "MarkingService_UpdateMarkingsOnResource",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/UpdateMarkingsOnResourceResponse"
            },
            "x-example": {}
          }
        },
        "parameters": [
          {
            "name": "resource",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/UpdateMarkingsOnResourceBody"
            },
            "x-example": {
              "markingsToApply": [
                "<markings to apply>"
              ],
              "markingsToRemove": [
                "<markings to remove>"
              ]
            }
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Update markings on resource",
        "description": "Update the markings that are applied on a resource. Supports applying and removing markings at once. This endpoint can be used to atomically replace the markings on a resource, or bulk apply/remove markings. This operation is idempotent and will not throw an error if the marking is already applied/removed on the resource. If a resource marking pair is present in both `markings_to_apply` and `markings_to_remove`, this will throw. Throws HTTP 403 / gRPC 7 if the user does not have permission to change the markings on the resource. Throws HTTP 400 / gRPC 3 if trying to apply an archived marking."
      }
    },
    "/authorization/markings/v1/search": {
      "post": {
        "operationId": "MarkingService_SearchMarkings",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/SearchMarkingsResponse"
            },
            "x-example": {
              "markingMetadatas": [
                {
                  "rid": "<rid>",
                  "id": "<id>",
                  "description": "<description>",
                  "symbol": {
                    "icon": "<icon>"
                  },
                  "color": {
                    "hexCode": "<hex code>"
                  },
                  "createdAt": "2026-01-01T00:00:00Z",
                  "updatedAt": "2026-01-01T00:00:00Z",
                  "isArchived": true
                }
              ],
              "nextPageToken": "<next page token>"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/SearchMarkingsRequest"
            },
            "x-example": {
              "query": {
                "idExactSubstringSearch": "<id exact substring search>"
              },
              "pageSize": 1,
              "nextPageToken": "<next page token>"
            }
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Search markings",
        "description": "Search Markings, returning paged results. Throws HTTP 400 / gRPC 3 if the query is incorrectly formed."
      }
    },
    "/authorization/markings/v1/unarchive-batch": {
      "post": {
        "operationId": "MarkingService_UnarchiveMarkings",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/UnarchiveMarkingsResponse"
            },
            "x-example": {}
          }
        },
        "parameters": [
          {
            "name": "markingRids",
            "in": "body",
            "required": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "example": [
                "string"
              ]
            },
            "x-example": [
              "string"
            ]
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Unarchive markings",
        "description": "Unarchives markings. Restores ability to apply and modify marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to unarchive one or more of the markings or if any of the markings are not found."
      }
    },
    "/authorization/markings/v1/{markingRid}/resources": {
      "post": {
        "operationId": "MarkingService_GetResourcesForMarking",
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/GetResourcesForMarkingResponse"
            },
            "x-example": {
              "resources": [
                {
                  "resource": "<resource>",
                  "appliedAt": "2026-01-01T00:00:00Z"
                }
              ],
              "nextPageToken": "<next page token>"
            }
          }
        },
        "parameters": [
          {
            "name": "markingRid",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/GetResourcesForMarkingBody"
            },
            "x-example": {
              "pageSize": 1,
              "nextPageToken": "<next page token>"
            }
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Get resources for marking",
        "description": "Gets the resources that a Marking is applied to. This endpoint is paginated. Any unauthorized resources will be filtered from the response. Throws HTTP 403 / gRPC 7 if the user does not have permission to read the marking."
      }
    },
    "/authorization/markings/v1/{rid}": {
      "get": {
        "operationId": "MarkingService_GetMarking",
        "responses": {
          "200": {
            "schema": {
              "$ref": "#/definitions/Marking"
            },
            "x-example": {
              "rid": "<rid>",
              "id": "<id>",
              "description": "<description>",
              "authorizedGroups": {
                "groupRids": [
                  "<group rids>"
                ]
              },
              "symbol": {
                "icon": "<icon>"
              },
              "color": {
                "hexCode": "<hex code>"
              },
              "createdAt": "2026-01-01T00:00:00Z",
              "updatedAt": "2026-01-01T00:00:00Z",
              "isArchived": true
            }
          }
        },
        "parameters": [
          {
            "name": "rid",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Get marking",
        "description": "Gets a marking by its RID. Throws HTTP 403 / gRPC 7 if the user does not have permission to read the marking. Throws HTTP 403 / gRPC 5 if the marking is not found."
      },
      "put": {
        "operationId": "MarkingService_UpdateMarking",
        "responses": {
          "200": {
            "schema": {
              "$ref": "#/definitions/Marking"
            },
            "x-example": {
              "rid": "<rid>",
              "id": "<id>",
              "description": "<description>",
              "authorizedGroups": {
                "groupRids": [
                  "<group rids>"
                ]
              },
              "symbol": {
                "icon": "<icon>"
              },
              "color": {
                "hexCode": "<hex code>"
              },
              "createdAt": "2026-01-01T00:00:00Z",
              "updatedAt": "2026-01-01T00:00:00Z",
              "isArchived": true
            }
          }
        },
        "parameters": [
          {
            "name": "rid",
            "in": "path",
            "required": true,
            "type": "string"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/UpdateMarkingBody"
            },
            "x-example": {
              "id": "<id>",
              "description": "<description>",
              "authorizedGroups": {
                "groupRids": [
                  "<group rids>"
                ]
              },
              "symbol": {
                "value": {
                  "icon": "<icon>"
                }
              },
              "color": {
                "value": {
                  "hexCode": "<hex code>"
                }
              }
            }
          }
        ],
        "tags": [
          "MarkingService"
        ],
        "summary": "Update marking",
        "description": "Updates a marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to update the marking. Throws HTTP 403 / gRPC 7 if the user does not have permission to read any of the specified groups. Throws HTTP 403 / gRPC 5 if the marking is not found. Throws HTTP 409 / gRPC 6 if trying to update the ID of a marking to an ID that already exists. Throws HTTP 400 / gRPC 3 if trying to update an archived marking."
      }
    }
  },
  "definitions": {
    "ArchiveMarkingsResponse": {
      "type": "object",
      "title": "intentionally empty"
    },
    "AuthorizedGroups": {
      "type": "object",
      "properties": {
        "groupRids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "BatchGetMarkingMetadataRequest": {
      "type": "object",
      "properties": {
        "markingRids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "example": {
        "markingRids": [
          "<marking rids>"
        ]
      }
    },
    "BatchGetMarkingMetadataResponse": {
      "type": "object",
      "properties": {
        "markingMetadatas": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/MarkingMetadata"
          }
        }
      }
    },
    "BatchGetMarkingsRequest": {
      "type": "object",
      "properties": {
        "markingRids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "example": {
        "markingRids": [
          "<marking rids>"
        ]
      }
    },
    "BatchGetMarkingsResponse": {
      "type": "object",
      "properties": {
        "markings": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/Marking"
          }
        }
      }
    },
    "CreateMarkingRequest": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens.",
          "pattern": "^[a-z][a-z0-9-]*$",
          "x-constraints": [
            "Matches `^[a-z][a-z0-9-]*$`."
          ]
        },
        "description": {
          "type": "string"
        },
        "authorizedGroups": {
          "$ref": "#/definitions/AuthorizedGroups",
          "description": "Group RIDs that are authorized to access data sources with this marking."
        },
        "symbol": {
          "$ref": "#/definitions/Symbol"
        },
        "color": {
          "$ref": "#/definitions/Color"
        }
      },
      "example": {
        "id": "<id>",
        "description": "<description>",
        "authorizedGroups": {
          "groupRids": [
            "<group rids>"
          ]
        },
        "symbol": {
          "icon": "<icon>"
        },
        "color": {
          "hexCode": "<hex code>"
        }
      }
    },
    "GetAuthorizedGroupsByMarkingRequest": {
      "type": "object",
      "properties": {
        "markingRids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "example": {
        "markingRids": [
          "<marking rids>"
        ]
      }
    },
    "GetAuthorizedGroupsByMarkingResponse": {
      "type": "object",
      "properties": {
        "authorizedGroupsByMarking": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/AuthorizedGroups"
          }
        }
      }
    },
    "GetMarkingsForResourcesRequest": {
      "type": "object",
      "properties": {
        "resources": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The resources to get the markings for."
        }
      },
      "example": {
        "resources": [
          "<resources>"
        ]
      }
    },
    "GetMarkingsForResourcesResponse": {
      "type": "object",
      "properties": {
        "resourceToMarkings": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/definitions/ResourceMarkingsList"
          },
          "description": "A map from resource ID to the markings applied to them."
        }
      }
    },
    "ResourceMarkingsList": {
      "type": "object",
      "properties": {
        "appliedMarkings": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/AppliedMarking"
          }
        }
      }
    },
    "AppliedMarking": {
      "type": "object",
      "properties": {
        "markingRid": {
          "type": "string"
        },
        "appliedAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "GetResourcesForMarkingResponse": {
      "type": "object",
      "properties": {
        "resources": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/MarkedResource"
          }
        },
        "nextPageToken": {
          "type": "string"
        }
      }
    },
    "MarkedResource": {
      "type": "object",
      "properties": {
        "resource": {
          "type": "string"
        },
        "appliedAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "Marking": {
      "type": "object",
      "properties": {
        "rid": {
          "type": "string"
        },
        "id": {
          "type": "string",
          "description": "Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens.",
          "pattern": "^[a-z][a-z0-9-]*$",
          "x-constraints": [
            "Matches `^[a-z][a-z0-9-]*$`."
          ]
        },
        "description": {
          "type": "string"
        },
        "authorizedGroups": {
          "$ref": "#/definitions/AuthorizedGroups",
          "description": "Group RIDs that are authorized to access data sources with this marking."
        },
        "symbol": {
          "$ref": "#/definitions/Symbol",
          "title": "Symbol and color to identify markings"
        },
        "color": {
          "$ref": "#/definitions/Color"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "isArchived": {
          "type": "boolean"
        }
      }
    },
    "MarkingMetadata": {
      "type": "object",
      "properties": {
        "rid": {
          "type": "string"
        },
        "id": {
          "type": "string",
          "description": "Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens.",
          "pattern": "^[a-z][a-z0-9-]*$",
          "x-constraints": [
            "Matches `^[a-z][a-z0-9-]*$`."
          ]
        },
        "description": {
          "type": "string"
        },
        "symbol": {
          "$ref": "#/definitions/Symbol",
          "title": "Symbol and color to identify markings"
        },
        "color": {
          "$ref": "#/definitions/Color"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time"
        },
        "isArchived": {
          "type": "boolean"
        }
      },
      "description": "A leaner representation of a Marking that doesn't include the authorized groups."
    },
    "GetResourcesForMarkingBody": {
      "type": "object",
      "properties": {
        "pageSize": {
          "type": "integer",
          "format": "int32",
          "description": "Page sizes greater than 1_000 will be rejected. Default pageSize is 100.",
          "minimum": 1,
          "maximum": 1000,
          "x-constraints": [
            "From 1 to 1,000."
          ]
        },
        "nextPageToken": {
          "type": "string"
        }
      },
      "example": {
        "pageSize": 1,
        "nextPageToken": "<next page token>"
      }
    },
    "UpdateMarkingBody": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Human-readable identifier for this marking. Must be unique within the organization. Must be lower case alphanumeric characters, optionally separated by hyphens.",
          "pattern": "^[a-z][a-z0-9-]*$",
          "x-constraints": [
            "Matches `^[a-z][a-z0-9-]*$`."
          ]
        },
        "description": {
          "type": "string"
        },
        "authorizedGroups": {
          "$ref": "#/definitions/AuthorizedGroups",
          "description": "Group RIDs that are authorized to access data sources with this marking."
        },
        "symbol": {
          "$ref": "#/definitions/UpdateMarkingSymbolWrapper"
        },
        "color": {
          "$ref": "#/definitions/UpdateMarkingColorWrapper"
        }
      },
      "example": {
        "id": "<id>",
        "description": "<description>",
        "authorizedGroups": {
          "groupRids": [
            "<group rids>"
          ]
        },
        "symbol": {
          "value": {
            "icon": "<icon>"
          }
        },
        "color": {
          "value": {
            "hexCode": "<hex code>"
          }
        }
      }
    },
    "UpdateMarkingsOnResourceBody": {
      "type": "object",
      "properties": {
        "markingsToApply": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "markingsToRemove": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "example": {
        "markingsToApply": [
          "<markings to apply>"
        ],
        "markingsToRemove": [
          "<markings to remove>"
        ]
      }
    },
    "SearchMarkingsQuery": {
      "type": "object",
      "properties": {
        "idExactSubstringSearch": {
          "type": "string",
          "description": "Search for markings with an ID that contains the given query as a substring."
        },
        "and": {
          "$ref": "#/definitions/SearchMarkingsQueryList"
        },
        "or": {
          "$ref": "#/definitions/SearchMarkingsQueryList"
        }
      },
      "x-oneofs": [
        {
          "fields": [
            "idExactSubstringSearch",
            "and",
            "or"
          ],
          "required": true
        }
      ],
      "description": "Set exactly one of the fields below.",
      "example": {
        "idExactSubstringSearch": "string"
      }
    },
    "SearchMarkingsQueryList": {
      "type": "object",
      "properties": {
        "queries": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/SearchMarkingsQuery"
          }
        }
      }
    },
    "SearchMarkingsRequest": {
      "type": "object",
      "properties": {
        "query": {
          "$ref": "#/definitions/SearchMarkingsQuery"
        },
        "pageSize": {
          "type": "integer",
          "format": "int32",
          "description": "Page sizes greater than 1_000 will be rejected. Default pageSize is 100.",
          "minimum": 1,
          "maximum": 1000,
          "x-constraints": [
            "From 1 to 1,000."
          ]
        },
        "nextPageToken": {
          "type": "string"
        }
      },
      "example": {
        "query": {
          "idExactSubstringSearch": "<id exact substring search>"
        },
        "pageSize": 1,
        "nextPageToken": "<next page token>"
      }
    },
    "SearchMarkingsResponse": {
      "type": "object",
      "properties": {
        "markingMetadatas": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/definitions/MarkingMetadata"
          }
        },
        "nextPageToken": {
          "type": "string"
        }
      }
    },
    "UnarchiveMarkingsResponse": {
      "type": "object",
      "title": "intentionally empty"
    },
    "UpdateMarkingColorWrapper": {
      "type": "object",
      "properties": {
        "value": {
          "$ref": "#/definitions/Color"
        }
      }
    },
    "UpdateMarkingSymbolWrapper": {
      "type": "object",
      "properties": {
        "value": {
          "$ref": "#/definitions/Symbol"
        }
      }
    },
    "UpdateMarkingsOnResourceResponse": {
      "type": "object",
      "title": "intentionally empty"
    },
    "Color": {
      "type": "object",
      "properties": {
        "hexCode": {
          "type": "string",
          "title": "hex color",
          "pattern": "^#[0-9a-f]{6}$",
          "x-constraints": [
            "Matches `^#[0-9a-f]{6}$`."
          ]
        }
      },
      "x-oneofs": [
        {
          "fields": [
            "hexCode"
          ],
          "required": true
        }
      ],
      "example": {
        "hexCode": "string"
      }
    },
    "Symbol": {
      "type": "object",
      "properties": {
        "icon": {
          "type": "string",
          "title": "Icon name (e.g. castle)"
        },
        "emoji": {
          "type": "string",
          "title": "Emoji name (e.g. :castle:)"
        },
        "image": {
          "type": "string",
          "title": "Image url (e.g. https://example.com/image.png)"
        }
      },
      "x-oneofs": [
        {
          "fields": [
            "icon",
            "emoji",
            "image"
          ],
          "required": true
        }
      ],
      "description": "Set exactly one of the fields below.",
      "example": {
        "icon": "string"
      }
    }
  },
  "securityDefinitions": {
    "ApiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization",
      "description": "Your API key as a bearer token: `Authorization: Bearer <api key>`."
    }
  },
  "security": [
    {
      "ApiKey": []
    }
  ]
}