---
title: "Search files and folders"
method: POST
path: "/documents/v1/search"
tags: ["Documents"]
---

# Search files and folders

`POST /documents/v1/search`

## Request

- Base URL: `https://api.mitti.com`
- URL: `https://api.mitti.com/documents/v1/search`
- Auth: HTTP bearer

Search for files and folders in Documents.

## Request body

- S12DocumentsV1SearchItemsRequest: Request to search the files and folders.
  - `page_size` integer: The number of items (files and folders combined) to return. Max value is 25. Defaults to 25 if not provided.
  - `page_token` string: The token to retrieve the next page of results. Use the value returned in the `next_page_token`` from the previous response.
  - `include_media_url` boolean: If `true`, includes a temporary media URL for each file so it can be downloaded.
  - `archived` boolean: If `true`, only archived files will be returned.
  - `search_term` string: Search term to match against file or folder names. This is case-insensitive, must be 1-130 characters, and exclude invalid characters.
  - `item_ids` string[]: List of item IDs to filter results. Only items matching any of the IDs will be returned.
  - `valid_to` S12DocumentsV1TimeInterval
    - `from` string, date-time: optional. represents the time should be after the time provided
    - `to` string, date-time: optional. represents the time should be before the time provided

## Response `200`

A successful response.

- S12DocumentsV1SearchItemsResponse
  - `folders` S12DocumentsV1Folder[]: List of folders that match the search criteria.
    - `folder_id` string: The ID of the folder
    - `name` string: The name of the folder
    - `created_at` string, date-time: The time the folder was created
    - `modified_at` string, date-time: The time the folder was last modified
    - `archived_at` string, date-time: If archived, the time the folder was archived
    - `archived` boolean: If the folder is archived or not
    - `bookmarked` boolean: If the folder is bookmarked by the requested user
    - `ancestors` S12DocumentsV1ParentFolder[]: Ordered from Highest ancestor to the current node eg. [Grandparent, Parent, Current]
      - `folder_id` string: The ID of the parent folder
      - `name` string: The name of the parent folder
    - `child_count` integer: The number of children in the folder
    - `users` S12DocumentsV1User[]: The users that own the folder
      - `user_id` string: The ID of the user
      - `email` string: The email of the user
      - `first_name` string: The first name of the user
      - `last_name` string: The last name of the user
    - `groups` S12DocumentsV1Group[]: The groups that own the folder
      - `group_id` string: The ID of the group
      - `name` string: The name of the group
  - `files` S12DocumentsV1File[]: List of files that match the search criteria.
    - `file_id` string: The ID of the file
    - `name` string: The name of the file
    - `description` string: The description of the file
    - `file_extension` string: The type extension of the file
    - `file_size` integer: The file size in bytes
    - `version_number` integer: The current version of the file
    - `download_url` string: The URL to download the file if specified in the request.
    - `labels` S12DocumentsV1Label[]: The labels associated with the file
      - `label_id` string: The ID of the label
      - `name` string: The name of the label
    - `created_at` string, date-time: The time the file was created
    - `modified_at` string, date-time: The time the file was last modified
    - `archived_at` string, date-time: If archived, the time the file was archived
    - `archived` boolean: If the file is archived or not
    - `bookmarked` boolean: If the file is bookmarked by the requested user
    - `ancestors` S12DocumentsV1ParentFolder[]: Ordered from Highest ancestor to the current node eg. [Grandparent, Parent, Current]
      - `folder_id` string: The ID of the parent folder
      - `name` string: The name of the parent folder
    - `users` S12DocumentsV1User[]: The users that own the file
      - `user_id` string: The ID of the user
      - `email` string: The email of the user
      - `first_name` string: The first name of the user
      - `last_name` string: The last name of the user
    - `groups` S12DocumentsV1Group[]: The groups that own the file
      - `group_id` string: The ID of the group
      - `name` string: The name of the group
    - `valid_from` GoogleTypeDate: * A full date, with non-zero year, month, and day values * A month and day value, with a zero year, such as an anniversary * A year on its own, with zero month and day values * A year and month value, with a zero day, such as a credit card expiration date Related types are [google.type.TimeOfDay][google.type.TimeOfDay] and `google.protobuf.Timestamp`.
      - `year` integer: Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
      - `month` integer: Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
      - `day` integer: Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.
    - `valid_to` GoogleTypeDate: * A full date, with non-zero year, month, and day values * A month and day value, with a zero year, such as an anniversary * A year on its own, with zero month and day values * A year and month value, with a zero day, such as a credit card expiration date Related types are [google.type.TimeOfDay][google.type.TimeOfDay] and `google.protobuf.Timestamp`.
      - `year` integer: Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
      - `month` integer: Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
      - `day` integer: Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.
    - `expiry_status` 'EXPIRY_STATUS_VALID' | 'EXPIRY_STATUS_EXPIRED' | 'EXPIRY_STATUS_EXPIRING_SOON': The expiry status of an object based on its validity period.
    - `sites` S12DocumentsV1Site[]: The sites the file is associated with
      - `site_id` string: The ID of the site
      - `name` string: The name of the site
  - `total` integer: Total number of files and folders that match the search criteria.
  - `next_page_token` string: The token used to retrieve the next page of results. Empty if there are no more items.

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/safetyculture/apis/safetyculture-api.md) - [All operations](https://skmtc.dev/safetyculture/apis/safetyculture-api/llms.txt) - [OpenAPI document](https://skmtc.dev/safetyculture/apis/safetyculture-api/revisions/eb6bb843bf18?raw)
