Sign in

v1

latestOpenAPI 3.0.2Apache-2.02026-07-142963051.0 MB
Search

Query files/folders by metadata

Create a search using SQL-like syntax to return items that match specific metadata.

By default, this endpoint returns only the most basic info about the items for which the query matches. To get additional fields for each item, including any of the metadata, use the fields attribute in the query.

post/metadata_queries/execute_read

Request body

fromstring required

Specifies the template used in the query. Must be in the form scope.templateKey. Not all templates can be used in this field, most notably the built-in, Box-provided classification templates can not be used in a query.

querystring

The query to perform. A query is a logical expression that is very similar to a SQL SELECT statement. Values in the search query can be turned into parameters specified in the query_param arguments list to prevent having to manually insert search values into the query string.

For example, a value of :amount would represent the amount value in query_params object.

query_paramsobject

Set of arguments corresponding to the parameters specified in the query. The type of each parameter used in the query_params must match the type of the corresponding metadata template field.

ancestor_folder_idstring required

The ID of the folder that you are restricting the query to. A value of zero will return results from all folders you have access to. A non-zero value will only return results found in the folder corresponding to the ID or in any of its subfolders.

limitinteger

A value between 0 and 100 that indicates the maximum number of results to return for a single request. This only specifies a maximum boundary and will not guarantee the minimum number of results returned.

markerstring

Marker to use for requesting the next page.

fieldsstring[]

By default, this endpoint returns only the most basic info about the items for which the query matches. This attribute can be used to specify a list of additional attributes to return for any item, including its metadata.

This attribute takes a list of item fields, metadata template identifiers, or metadata template field identifiers.

For example:

  • created_by will add the details of the user who created the item to the response.
  • metadata.<scope>.<templateKey> will return the mini-representation of the metadata instance identified by the scope and templateKey.
  • metadata.<scope>.<templateKey>.<field> will return all the mini-representation of the metadata instance identified by the scope and templateKey plus the field specified by the field name. Multiple fields for the same scope and templateKey can be defined.

Example request

{
  "from": "enterprise_123456.someTemplate",
  "query": "value >= :amount",
  "query_params": {
    "amount": "100"
  },
  "ancestor_folder_id": "0",
  "order_by": [
    {
      "field_key": "amount",
      "direction": "asc"
    }
  ],
  "limit": 50,
  "marker": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff",
  "fields": [
    "extension",
    "created_at",
    "item_status",
    "metadata.enterprise_1234.contracts",
    "metadata.enterprise_1234.regions.location"
  ]
}

Response

Returns a list of files and folders that match this metadata query.

limitinteger

The limit that was used for this search. This will be the same as the limit query parameter unless that value exceeded the maximum value allowed.

next_markerstring

The marker for the start of the next page of results.

Example response

{
  "entries": [
    {
      "id": "12345",
      "etag": "1",
      "type": "file",
      "sequence_id": "3",
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "file_version": {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      },
      "description": "Contract for Q1 renewal",
      "size": 629644,
      "path_collection": {
        "total_count": 1,
        "entries": [
          {
            "id": "12345",
            "etag": "1",
            "type": "folder",
            "sequence_id": "3",
            "name": "Contracts"
          }
        ]
      },
      "created_at": "2012-12-12T10:53:43-08:00",
      "modified_at": "2012-12-12T10:53:43-08:00",
      "trashed_at": "2012-12-12T10:53:43-08:00",
      "purged_at": "2012-12-12T10:53:43-08:00",
      "content_created_at": "2012-12-12T10:53:43-08:00",
      "content_modified_at": "2012-12-12T10:53:43-08:00",
      "created_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "modified_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "owned_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": "https://acme.app.box.com/v/my_url/",
        "vanity_name": "my_url",
        "access": "open",
        "effective_access": "company",
        "effective_permission": "can_download",
        "unshared_at": "2018-04-13T13:53:23-07:00",
        "is_password_enabled": true,
        "permissions": {
          "can_download": true,
          "can_preview": true
        },
        "download_count": 3,
        "preview_count": 3
      },
      "parent": {
        "id": "12345",
        "etag": "1",
        "type": "folder",
        "sequence_id": "3",
        "name": "Contracts"
      },
      "item_status": "active",
      "version_number": "1",
      "comment_count": 10,
      "permissions": {
        "can_delete": true,
        "can_download": true,
        "can_invite_collaborator": true,
        "can_rename": true,
        "can_set_share_access": true,
        "can_share": true,
        "can_annotate": true,
        "can_comment": true,
        "can_preview": true,
        "can_upload": true,
        "can_view_annotations_all": true,
        "can_view_annotations_self": true,
        "can_apply_watermark": true
      },
      "tags": [
        "approved"
      ],
      "lock": {
        "id": "11446498",
        "type": "lock",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "expired_at": "2012-12-12T10:53:43-08:00",
        "is_download_prevented": true,
        "app_type": "office_wopiplus"
      },
      "extension": "pdf",
      "is_package": true,
      "expiring_embed_link": {
        "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
        "expires_in": 3600,
        "token_type": "bearer",
        "restricted_to": [
          {
            "scope": "item_download",
            "object": {
              "id": "12345",
              "etag": "1",
              "type": "folder",
              "sequence_id": "3",
              "name": "Contracts"
            }
          }
        ],
        "url": "https://cloud.app.box.com/preview/expiring_embed/..."
      },
      "watermark_info": {
        "is_watermarked": true
      },
      "is_accessible_via_shared_link": true,
      "allowed_invitee_roles": [
        "editor"
      ],
      "is_externally_owned": true,
      "has_collaborations": true,
      "metadata": {
        "enterprise_27335": {
          "marketingCollateral": {
            "$canEdit": true,
            "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
            "$parent": "folder_59449484661",
            "$scope": "enterprise_27335",
            "$template": "marketingCollateral",
            "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
            "$typeVersion": 2,
            "$version": 1
          }
        }
      },
      "expires_at": "2012-12-12T10:53:43-08:00",
      "representations": {
        "entries": [
          {
            "content": {
              "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
            },
            "info": {
              "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
            },
            "properties": {
              "dimensions": "2048x2048",
              "paged": "true",
              "thumb": "true"
            },
            "representation": "png",
            "status": {
              "state": "success"
            }
          }
        ]
      },
      "classification": {
        "name": "Top Secret",
        "definition": "Content that should not be shared outside the company.",
        "color": "#FF0000"
      },
      "uploader_display_name": "Ellis Wiggins",
      "disposition_at": "2012-12-12T10:53:43-08:00",
      "shared_link_permission_options": [
        "can_preview"
      ],
      "is_associated_with_app_item": true
    }
  ],
  "limit": 100,
  "next_marker": "0!-M7487OpVfBTNBV-XsQjU50gQFlbFFu5nArMWD7Ck61GH_Qo40M1S2xN5zWZPBzEjaQS1SOjJiQoo5BsXEl1bCVLRZ2pTqo4SKp9tyqzWQK2L51KR_nC1EgF5I_TJSFw7uO2Bx4HweGETOjh5_2oPSWw5iMkM-OvGApeR0lGFO48FDKoyzJyLgz5aogxoKd8VE09CesOOnTnmZvrW0puylDc-hFjY5YLmWFBKox3SOWiSDwKFkmZGNHyjEzza1nSwbZg6CYsAdGsDwGJhuCeTNsFzP5Mo5qx9wMloS0lSPuf2CcBInbIJzl2CKlXF3FvqhANttpm2nzdBTQRSoJyJnjVBpf4Q_HjV2eb4KIZBBlLy067UCVdv2AAWQFd5E2i6s1YiGRTtgMEZntOSUYD4IYLMWWm5Ra7ke_SP32SL3GSjbBQYIyCVQ.."
}