Box Metadata Queries API
The Box Metadata Queries API enables executing structured queries against metadata applied to files and folders, allowing applications to search for and filter content based on custom metadata field values.
OpenAPI Specification
openapi: 3.1.0
info:
title: Box Metadata Queries API
description: Needs a description.
paths:
/metadata_queries/execute_read:
post:
operationId: post_metadata_queries_execute_read
summary: Box Query files/folders by metadata
tags:
- Metadata Queries
x-box-tag: search
x-box-sanitized: true
x-box-enable-explorer: true
description: >-
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.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataQuery'
responses:
'200':
description: Returns a list of files and folders that match this metadata query.
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataQueryResults'
'400':
description: >-
Returns an error when the request body is not valid.
* `invalid_query` - Any of the provided body parameters might be
incorrect. This can mean the `query` is incorrect, as well as some
cases
where the `from` value does not represent a valid template.
* `unexpected_json_type` - An argument from the `query` string is
not
present in `query_param`. For example, `query` of `name = :name`
requires
the `query_param` to include a value for the `name` argument, for
example
`{ "name": "Box, Inc" }`.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: >-
Returns an error when a metadata template with the given `scope` and
`templateKey` can not be found. The error response will include
extra
details.
* `instance_not_found` - The template was not found. Please make
sure
to use the full template scope including the enterprise ID, like
`enterprise_12345`.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
MetadataQueryResults:
title: Metadata query search results
type: object
x-box-tag: search
x-box-resource-id: metadata_query_results
description: A page of files and folders that matched the metadata query.
properties:
entries:
description: >-
The mini representation of the files and folders that match the
search
terms.
By default, this endpoint returns only the most basic info about the
items. To get additional fields for each item, including any of the
metadata, use the `fields` attribute in the query.
type: array
x-box-resource-variant: 1
items:
oneOf:
- $ref: '#/components/schemas/File'
- $ref: '#/components/schemas/Folder'
limit:
description: >-
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.
default: 100
example: 100
type: integer
format: int64
next_marker:
description: The marker for the start of the next page of results.
example: >-
0!-M7487OpVfBTNBV-XsQjU50gQFlbFFu5nArMWD7Ck61GH_Qo40M1S2xN5zWZPBzEjaQS1SOjJiQoo5BsXEl1bCVLRZ2pTqo4SKp9tyqzWQK2L51KR_nC1EgF5I_TJSFw7uO2Bx4HweGETOjh5_2oPSWw5iMkM-OvGApeR0lGFO48FDKoyzJyLgz5aogxoKd8VE09CesOOnTnmZvrW0puylDc-hFjY5YLmWFBKox3SOWiSDwKFkmZGNHyjEzza1nSwbZg6CYsAdGsDwGJhuCeTNsFzP5Mo5qx9wMloS0lSPuf2CcBInbIJzl2CKlXF3FvqhANttpm2nzdBTQRSoJyJnjVBpf4Q_HjV2eb4KIZBBlLy067UCVdv2AAWQFd5E2i6s1YiGRTtgMEZntOSUYD4IYLMWWm5Ra7ke_SP32SL3GSjbBQYIyCVQ..
type: string
ClientError:
title: Client error
type: object
x-box-resource-id: client_error
description: A generic error
properties:
type:
description: error
example: error
type: string
enum:
- error
nullable: false
status:
description: The HTTP status of the response.
example: 400
type: integer
format: int32
nullable: false
code:
description: A Box-specific error code
example: item_name_invalid
type: string
enum:
- created
- accepted
- no_content
- redirect
- not_modified
- bad_request
- unauthorized
- forbidden
- not_found
- method_not_allowed
- conflict
- precondition_failed
- too_many_requests
- internal_server_error
- unavailable
- item_name_invalid
- insufficient_scope
message:
description: A short message describing the error.
example: Method Not Allowed
type: string
nullable: false
context_info:
description: |-
A free-form object that contains additional context
about the error. The possible fields are defined on
a per-endpoint basis. `message` is only one example.
type: object
nullable: true
properties:
message:
type: string
description: More details on the error.
example: Something went wrong.
help_url:
description: A URL that links to more information about why this error occurred.
example: >-
https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
type: string
nullable: false
request_id:
description: |-
A unique identifier for this response, which can be used
when contacting Box support.
type: string
example: abcdef123456
nullable: false
tags:
- name: Metadata Queries