{
  "swagger": "2.0",
  "info": {
    "title": "Resource metadata service",
    "version": "0.1507.0",
    "description": "Send your API key as a bearer token: `Authorization: Bearer <api key>`."
  },
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "securityDefinitions": {
    "ApiKey": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization",
      "description": "Your API key as a bearer token: `Authorization: Bearer <api key>`."
    }
  },
  "security": [
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/scout/v1/metadata/list-properties-labels": {
      "post": {
        "operationId": "ResourceMetadataService_listPropertiesAndLabels",
        "summary": "List properties and labels",
        "tags": [
          "ResourceMetadataService"
        ],
        "description": "Returns all existing properties (key value pairs) and labels, which can be used to organize resources such as runs and videos. This legacy bulk-list surface returns string property values only. Use searchPropertyKeys for numeric keys.",
        "parameters": [
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/ListPropertiesAndLabelsRequest"
            },
            "required": true,
            "x-example": {
              "resourceTypes": [
                "RUN"
              ],
              "workspaces": [
                "<workspace rid>"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/ListPropertiesAndLabelsResponse"
            },
            "x-example": {
              "properties": {
                "<key>": [
                  "<property value>"
                ]
              },
              "labels": [
                "<label>"
              ]
            }
          }
        }
      }
    },
    "/scout/v1/metadata/usage-count": {
      "post": {
        "operationId": "ResourceMetadataService_getMetadataUsageCount",
        "summary": "Get metadata usage count",
        "tags": [
          "ResourceMetadataService"
        ],
        "description": "Returns the count of resources that use a given label or property. The query can match by label, property name (key only), or a full property key+value pair. Counts are scoped to the caller's accessible workspaces unless specific workspaces are provided.",
        "parameters": [
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/GetMetadataUsageCountRequest"
            },
            "required": true,
            "x-example": {
              "query": {
                "type": "label",
                "label": "<label>"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/GetMetadataUsageCountResponse"
            },
            "x-example": {
              "count": 1
            }
          }
        }
      }
    },
    "/scout/v1/metadata/label/find-similar": {
      "post": {
        "operationId": "ResourceMetadataService_findSimilarLabelMatches",
        "summary": "Find similar label matches",
        "tags": [
          "ResourceMetadataService"
        ],
        "description": "Given a set of labels, finds similar labels across the specified workspaces and resource types. Includes document count. Useful for detecting unintentional duplicate labels.",
        "parameters": [
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/FindSimilarLabelMatchesRequest"
            },
            "required": true,
            "x-example": {
              "resourceTypes": [
                "RUN"
              ],
              "workspaces": [
                "<workspace rid>"
              ],
              "labels": [
                "<label>"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/FindSimilarLabelMatchesResponse"
            },
            "x-example": {
              "matches": {
                "<key>": [
                  {
                    "value": "<value>",
                    "documentCount": 1
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/scout/v1/metadata/property/find-similar": {
      "post": {
        "operationId": "ResourceMetadataService_findSimilarPropertyKeyMatches",
        "summary": "Find similar property key matches",
        "tags": [
          "ResourceMetadataService"
        ],
        "description": "Given a set of property keys, finds similar property keys across the specified workspaces and resource types. Includes document count. Useful for detecting unintentional duplicate property keys.",
        "parameters": [
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/FindSimilarPropertyKeyMatchesRequest"
            },
            "required": true,
            "x-example": {
              "resourceTypes": [
                "RUN"
              ],
              "workspaces": [
                "<workspace rid>"
              ],
              "propertyKeys": [
                "<property name>"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/FindSimilarPropertyKeyMatchesResponse"
            },
            "x-example": {
              "keyMatches": {
                "<key>": [
                  {
                    "value": "<value>",
                    "documentCount": 1
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/scout/v1/metadata/search-labels": {
      "post": {
        "operationId": "ResourceMetadataService_searchLabels",
        "summary": "Search labels",
        "tags": [
          "ResourceMetadataService"
        ],
        "description": "Returns a paginated list of labels with document usage counts, filterable by resource type, workspace, and search text.",
        "parameters": [
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/SearchMetadataRequest"
            },
            "required": true,
            "x-example": {
              "sortBy": "ALPHABETICAL"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/SearchLabelsResponse"
            },
            "x-example": {
              "labels": [
                {
                  "label": "<label>",
                  "documentCount": 1
                }
              ],
              "nextPageToken": "<token>"
            }
          }
        }
      }
    },
    "/scout/v1/metadata/search-property-keys": {
      "post": {
        "operationId": "ResourceMetadataService_searchPropertyKeys",
        "summary": "Search property keys",
        "tags": [
          "ResourceMetadataService"
        ],
        "description": "Returns a paginated list of string and numeric property keys with typed statistics, filterable by resource type, workspace, and search text. ALPHABETICAL sort pages efficiently at any workspace size. USAGE_COUNT and PROPERTY_VALUE_COUNT rank every key in the workspace, so on large workspaces pass searchText or the request may fail with a 400 MetadataQueryTooBroad error.",
        "parameters": [
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/SearchMetadataRequest"
            },
            "required": true,
            "x-example": {
              "sortBy": "ALPHABETICAL"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/SearchPropertyKeysResponse"
            },
            "x-example": {
              "propertyKeys": [
                {
                  "propertyKey": "<property name>",
                  "documentCount": 1,
                  "valueCount": 1,
                  "string": {
                    "documentCount": 1,
                    "distinctValueCount": 1
                  },
                  "numeric": {
                    "documentCount": 1,
                    "mean": 1
                  }
                }
              ],
              "nextPageToken": "<token>"
            }
          }
        }
      }
    },
    "/scout/v1/metadata/search-property-values": {
      "post": {
        "operationId": "ResourceMetadataService_searchPropertyValues",
        "summary": "Search property values",
        "tags": [
          "ResourceMetadataService"
        ],
        "description": "Returns a paginated list of string property values for a given property key with document usage counts, filterable by resource type, workspace, and search text. Numeric values are intentionally excluded; their summary is returned by searchPropertyKeys.",
        "parameters": [
          {
            "name": "request",
            "in": "body",
            "schema": {
              "$ref": "#/definitions/SearchPropertyValuesRequest"
            },
            "required": true,
            "x-example": {
              "search": {
                "sortBy": "ALPHABETICAL"
              },
              "propertyKey": "<property name>"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful response.",
            "schema": {
              "$ref": "#/definitions/SearchPropertyValuesResponse"
            },
            "x-example": {
              "propertyValues": [
                {
                  "propertyValue": "<property value>",
                  "documentCount": 1
                }
              ],
              "nextPageToken": "<token>"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "Property": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "x-alias": "PropertyName"
        },
        "value": {
          "type": "string",
          "x-alias": "PropertyValue"
        }
      },
      "required": [
        "name",
        "value"
      ]
    },
    "FindSimilarLabelMatchesRequest": {
      "type": "object",
      "properties": {
        "resourceTypes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ResourceType"
          },
          "uniqueItems": true,
          "description": "If omitted, all resource types are included."
        },
        "workspaces": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "rid",
            "x-alias": "WorkspaceRid"
          },
          "uniqueItems": true,
          "description": "If omitted, results will come from all workspaces the user belongs to."
        },
        "labels": {
          "type": "array",
          "items": {
            "type": "string",
            "x-alias": "Label"
          },
          "uniqueItems": true
        }
      },
      "example": {
        "resourceTypes": [
          "RUN"
        ],
        "workspaces": [
          "<workspace rid>"
        ],
        "labels": [
          "<label>"
        ]
      }
    },
    "FindSimilarLabelMatchesResponse": {
      "type": "object",
      "properties": {
        "matches": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "$ref": "#/definitions/MatchCount"
            }
          },
          "x-map-key": "Label"
        }
      }
    },
    "FindSimilarPropertyKeyMatchesRequest": {
      "type": "object",
      "properties": {
        "resourceTypes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ResourceType"
          },
          "uniqueItems": true,
          "description": "If omitted, all resource types are included."
        },
        "workspaces": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "rid",
            "x-alias": "WorkspaceRid"
          },
          "uniqueItems": true,
          "description": "If omitted, results will come from all workspaces the user belongs to."
        },
        "propertyKeys": {
          "type": "array",
          "items": {
            "type": "string",
            "x-alias": "PropertyName"
          },
          "uniqueItems": true
        }
      },
      "example": {
        "resourceTypes": [
          "RUN"
        ],
        "workspaces": [
          "<workspace rid>"
        ],
        "propertyKeys": [
          "<property name>"
        ]
      }
    },
    "FindSimilarPropertyKeyMatchesResponse": {
      "type": "object",
      "properties": {
        "keyMatches": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "$ref": "#/definitions/MatchCount"
            }
          },
          "x-map-key": "PropertyName"
        }
      }
    },
    "GetMetadataUsageCountRequest": {
      "type": "object",
      "properties": {
        "query": {
          "$ref": "#/definitions/MetadataUsageQuery"
        },
        "resourceTypes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ResourceType"
          },
          "uniqueItems": true,
          "description": "If omitted, all resource types are included."
        },
        "workspaces": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "rid",
            "x-alias": "WorkspaceRid"
          },
          "uniqueItems": true,
          "description": "If omitted, results will come from all workspaces the user belongs to."
        }
      },
      "required": [
        "query"
      ],
      "example": {
        "query": {
          "type": "label",
          "label": "<label>"
        }
      }
    },
    "GetMetadataUsageCountResponse": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "format": "int32"
        }
      },
      "required": [
        "count"
      ]
    },
    "LabelWithCount": {
      "type": "object",
      "properties": {
        "label": {
          "type": "string",
          "x-alias": "Label"
        },
        "documentCount": {
          "type": "integer",
          "format": "int32"
        }
      },
      "required": [
        "label",
        "documentCount"
      ]
    },
    "ListPropertiesAndLabelsRequest": {
      "type": "object",
      "properties": {
        "resourceTypes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ResourceType"
          },
          "uniqueItems": true,
          "description": "If omitted, all resource types are included."
        },
        "workspaces": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "rid",
            "x-alias": "WorkspaceRid"
          },
          "uniqueItems": true,
          "description": "If omitted, results will come from all workspaces the user belongs to."
        }
      },
      "example": {
        "resourceTypes": [
          "RUN"
        ],
        "workspaces": [
          "<workspace rid>"
        ]
      }
    },
    "ListPropertiesAndLabelsResponse": {
      "type": "object",
      "properties": {
        "properties": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string",
              "x-alias": "PropertyValue"
            },
            "uniqueItems": true
          },
          "x-map-key": "PropertyName",
          "description": "Legacy string-only property values.",
          "x-deprecated": "Use the paginated searchPropertyKeys and searchPropertyValues methods instead."
        },
        "labels": {
          "type": "array",
          "items": {
            "type": "string",
            "x-alias": "Label"
          },
          "uniqueItems": true
        }
      }
    },
    "MatchCount": {
      "type": "object",
      "properties": {
        "value": {
          "type": "string"
        },
        "documentCount": {
          "type": "integer",
          "format": "int32"
        }
      },
      "required": [
        "value",
        "documentCount"
      ]
    },
    "MetadataSortField": {
      "type": "string",
      "enum": [
        "ALPHABETICAL",
        "USAGE_COUNT",
        "PROPERTY_VALUE_COUNT"
      ]
    },
    "MetadataUsageQuery": {
      "description": "Specifies what metadata to count usage for. Exactly one of: a label, a property name (counts all resources with any value for that key), or a full property key+value pair.\n\nSet `type` to the name of one of the other fields, and set only that field.",
      "type": "object",
      "x-union": true,
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "label",
            "propertyName",
            "property"
          ]
        },
        "label": {
          "type": "string",
          "x-alias": "Label"
        },
        "propertyName": {
          "type": "string",
          "x-alias": "PropertyName"
        },
        "property": {
          "$ref": "#/definitions/Property"
        }
      },
      "required": [
        "type"
      ],
      "example": {
        "type": "label",
        "label": "string"
      }
    },
    "NumericPropertySummary": {
      "type": "object",
      "properties": {
        "documentCount": {
          "type": "integer",
          "format": "int32"
        },
        "mean": {
          "type": "number",
          "format": "double"
        }
      },
      "required": [
        "documentCount",
        "mean"
      ]
    },
    "PropertyKeyWithCount": {
      "type": "object",
      "properties": {
        "propertyKey": {
          "type": "string",
          "x-alias": "PropertyName"
        },
        "documentCount": {
          "type": "integer",
          "format": "int32",
          "description": "Number of documents with either a string or numeric value for this key."
        },
        "valueCount": {
          "type": "integer",
          "format": "int32",
          "description": "Number of distinct string values. Numeric values are intentionally excluded.",
          "x-deprecated": "Retained for backward compatibility. Use string.distinctValueCount instead."
        },
        "string": {
          "allOf": [
            {
              "$ref": "#/definitions/StringPropertySummary"
            }
          ],
          "description": "Present when this key has string values."
        },
        "numeric": {
          "allOf": [
            {
              "$ref": "#/definitions/NumericPropertySummary"
            }
          ],
          "description": "Present when this key has numeric values."
        }
      },
      "required": [
        "propertyKey",
        "documentCount",
        "valueCount"
      ]
    },
    "PropertyValueWithCount": {
      "type": "object",
      "properties": {
        "propertyValue": {
          "type": "string",
          "x-alias": "PropertyValue"
        },
        "documentCount": {
          "type": "integer",
          "format": "int32"
        }
      },
      "required": [
        "propertyValue",
        "documentCount"
      ]
    },
    "ResourceType": {
      "type": "string",
      "enum": [
        "RUN",
        "VIDEO",
        "ASSET",
        "EVENT",
        "DATASET",
        "MODULE",
        "PROCEDURE_EXECUTION",
        "PROCEDURE",
        "SAVED_VIEW"
      ]
    },
    "SearchLabelsResponse": {
      "type": "object",
      "properties": {
        "labels": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/LabelWithCount"
          }
        },
        "nextPageToken": {
          "type": "string",
          "x-alias": "Token"
        }
      }
    },
    "SearchMetadataRequest": {
      "type": "object",
      "properties": {
        "resourceTypes": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/ResourceType"
          },
          "uniqueItems": true,
          "description": "If omitted, all resource types are included."
        },
        "workspaces": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "rid",
            "x-alias": "WorkspaceRid"
          },
          "uniqueItems": true,
          "description": "If omitted, results will come from all workspaces the user belongs to."
        },
        "searchText": {
          "type": "string",
          "description": "Case-insensitive substring filter."
        },
        "pageSize": {
          "type": "integer",
          "format": "int32",
          "description": "Maximum number of items per page. Defaults to 1000 if not specified."
        },
        "pageToken": {
          "type": "string",
          "x-alias": "Token",
          "description": "Token for fetching the next page of results."
        },
        "sortBy": {
          "$ref": "#/definitions/MetadataSortField"
        },
        "descending": {
          "type": "boolean",
          "description": "If true, sort in descending order. Defaults to false."
        }
      },
      "required": [
        "sortBy"
      ],
      "example": {
        "sortBy": "ALPHABETICAL"
      }
    },
    "SearchPropertyKeysResponse": {
      "type": "object",
      "properties": {
        "propertyKeys": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PropertyKeyWithCount"
          }
        },
        "nextPageToken": {
          "type": "string",
          "x-alias": "Token"
        }
      }
    },
    "SearchPropertyValuesRequest": {
      "type": "object",
      "properties": {
        "search": {
          "$ref": "#/definitions/SearchMetadataRequest"
        },
        "propertyKey": {
          "type": "string",
          "x-alias": "PropertyName"
        }
      },
      "required": [
        "search",
        "propertyKey"
      ],
      "example": {
        "search": {
          "sortBy": "ALPHABETICAL"
        },
        "propertyKey": "<property name>"
      }
    },
    "SearchPropertyValuesResponse": {
      "type": "object",
      "properties": {
        "propertyValues": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/PropertyValueWithCount"
          }
        },
        "nextPageToken": {
          "type": "string",
          "x-alias": "Token"
        }
      }
    },
    "StringPropertySummary": {
      "type": "object",
      "properties": {
        "documentCount": {
          "type": "integer",
          "format": "int32"
        },
        "distinctValueCount": {
          "type": "integer",
          "format": "int32"
        }
      },
      "required": [
        "documentCount",
        "distinctValueCount"
      ]
    }
  },
  "tags": [
    {
      "name": "ResourceMetadataService",
      "x-displayName": "Resource metadata service",
      "description": "The Resource Metadata Service provides common metadata about resources."
    }
  ]
}