Search

The Search API lets you find files and folders in an Egnyte domain based on filenames, metadata, and text content. Search results are scoped to the authenticated user's permissions — users only see content they have access to.

The API supports two versions:

v1: Basic search using query parameters
v2: Advanced search with custom metadata filtering and similarity search using JSON request bodies

Note: All searches are performed in the context of the authenticated user. Results are automatically filtered based on the user's permissions.

Base URL

https://{domain}.egnyte.com/pubapi/v1/search
https://{domain}.egnyte.com/pubapi/v2/search

Authentication

All requests require an OAuth 2.0 Bearer token in the Authorization header:

Authorization: Bearer {access_token}

See Authentication for details on obtaining a token.

Search (v1)

Perform a basic search using query parameters. Supports filtering by filename, content, folder location, and modification dates.

Request

GET /pubapi/v1/search

Query Parameters

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	The search string. Must be 3–100 characters.
`offset`	integer	No	`0`	The 0-based index of the first result to return.
`count`	integer	No	`20`	Number of results per page. Must be 1–20.
`folder`	string	No	—	Limit results to items in this folder and its descendants. One folder per request. Must be URL-encoded once (e.g., `/Shared/Documents%202/images`).
`modified_before`	string	No	—	Limit results to items modified before this ISO-8601 timestamp (e.g., `2020-08-01T18:43:23Z`).
`modified_after`	string	No	—	Limit results to items modified after this ISO-8601 timestamp.
`uploaded_before`	string	No	—	Limit results to items uploaded before this ISO-8601 timestamp.
`uploaded_after`	string	No	—	Limit results to items uploaded after this ISO-8601 timestamp.
`type`	string	No	—	Filter by item type. One of `FILE`, `FOLDER`.
`snippet_requested`	boolean	No	`true`	Whether to include text snippets in results. Set to `false` to return empty snippets.
`sort_by`	string	No	`score`	Field to sort by. One of `score`, `last_modified`, `size`, `name`.
`sort_direction`	string	No	—	Sort direction. One of `ascending`, `descending`.
`file_query_fields`	array	No	`ALL`	Search files in specific fields. One of `ALL`, `FILENAME`, `COMMENTS`, `CONTENT`.
`folder_query_fields`	array	No	`ALL`	Search folders in specific fields. One of `ALL`, `FOLDERNAME`, `DESCRIPTION`.
`query_operator`	string	No	`ANY`	Match all words or any word. One of `ANY`, `ALL`.

Example Request

curl -i -X GET "https://{domain}.egnyte.com/pubapi/v1/search?query=localcloudpress" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

200 OK

Field	Type	Description
`count`	integer	Number of results returned in this response.
`total_count`	integer	Total number of matching results. If more than `count` results exist, returns `count + 1`.
`offset`	integer	The 0-based index of the first result in this response.
`results`	array	Array of matching files and folders.
`results[].name`	string	Name of the file or folder.
`results[].path`	string	Full path to the item in Egnyte.
`results[].type`	string	MIME type of the file (e.g., `application/msword`).
`results[].size`	integer	Size of the file in bytes.
`results[].snippet`	string	Plain text snippet containing matched content.
`results[].snippet_html`	string	HTML-formatted snippet containing matched content.
`results[].entry_id`	string	Unique GUID for this file or folder instance.
`results[].group_id`	string	Group identifier for the item.
`results[].last_modified`	string	ISO-8601 timestamp of last modification.
`results[].uploaded_by`	string	Display name of the user who uploaded the file.
`results[].uploaded_by_username`	string	Username of the user who uploaded the file.
`results[].num_versions`	integer	Number of versions available for this file.
`results[].is_folder`	boolean	`true` if the item is a folder, `false` if it's a file.

Example Response

{
  "results": [{
    "name": "LocalCloudPress.doc",
    "path": "/Shared/Documents/Sales/Proposals/LocalCloudPress.doc",
    "type": "application/msword",
    "size": 28672,
    "snippet": "Version5Version 45\nVersion 3\n\ngnyte brings its storage cloud closer to home\n\nFebruary 17, 2019\n\nhtt",
    "entry_id": "2c8e1083-47f8-4d57-94dc-fd05429b7ec3",
    "group_id": "61ed8373-6ff8-493f-8c6f-g4d8a05867243",
    "last_modified": "2020-01-14T22:19:29Z",
    "uploaded_by": "David Pfeffer",
    "uploaded_by_username": "david",
    "num_versions": 1,
    "snippet_html": "Version5Version 45\nVersion 3\n\ngnyte brings its storage cloud closer to home\n\nFebruary 17, 2019\n\nhtt",
    "is_folder": false
  }],
  "total_count": 20,
  "offset": 0,
  "count": 1
}

Search (v2)

Perform advanced searches with custom metadata filtering and similarity search. Use this endpoint to search by metadata fields, find similar documents, or combine text and metadata queries.

Request

POST /pubapi/v2/search

Request Body

Field	Type	Required	Description
`query`	string	No*	The search string. Must be 3–100 characters. *Either `query` or `custom_metadata` is required.
`offset`	integer	No	The 0-based index of the first result to return. Default: `0`.
`count`	integer	No	Number of results per page. Must be 1–20. Default: `20`.
`folder`	string	No	Limit results to items in this folder and its descendants. One folder per request. Do NOT URL-encode when using v2 (e.g., `/Shared/Documents 2/images`).
`modified_before`	integer	No	Limit results to items modified before this Unix timestamp in milliseconds.
`modified_after`	integer	No	Limit results to items modified after this Unix timestamp in milliseconds.
`uploaded_before`	integer	No	Limit results to items uploaded before this Unix timestamp in milliseconds.
`uploaded_after`	integer	No	Limit results to items uploaded after this Unix timestamp in milliseconds.
`type`	string	No	Filter by item type. One of `FILE`, `FOLDER`, `ALL`. Default: `ALL`.
`snippet_requested`	boolean	No	Whether to include text snippets in results. Default: `true`.
`sort_by`	string	No	Field to sort by. One of `score`, `last_modified`, `size`, `name`. Default: `score`.
`sort_direction`	string	No	Sort direction. One of `ascending`, `descending`.
`query_operator`	string	No	Match all words or any word. One of `ANY`, `ALL`.
`file_query_fields`	array	No	Search files in specific fields. One or more of `ALL`, `FILENAME`, `COMMENTS`, `CONTENT`.
`folder_query_fields`	array	No	Search folders in specific fields. One or more of `ALL`, `FOLDERNAME`, `DESCRIPTION`.
`custom_metadata`	array	No*	Array of metadata filter objects. *Either `query` or `custom_metadata` is required.
`namespaces`	array	No	Array of namespace names to include in results. Only namespaces with values are returned.
`mlt`	array	No	Array of document entry IDs to use as reference for similarity search.
`mltt`	array	No	Array of text strings to use as reference for similarity search.

v1 and v2 differ in two parameters. Sending the v1 form to v2, or the reverse, does not always return an error:

Parameter	v1 (`GET /pubapi/v1/search`)	v2 (`POST /pubapi/v2/search`)
Date filters (`modified_`, `uploaded_`)	ISO-8601 string, e.g. `2026-01-01T00:00:00Z`	Integer, Unix epoch milliseconds, e.g. `1767225600000`. An ISO-8601 string returns `400`.
`folder`	URL-encoded once, as a query parameter	Plain path in the JSON body. A URL-encoded path may return no results.

Timestamps in responses, such as last_modified, are ISO-8601 in both versions.

Custom Metadata Filter Object

Field	Type	Required	Description
`namespace`	string	Yes	Name of the metadata namespace.
`key`	string	Yes	Metadata key to search.
`operator`	string	Yes	Search operator. One of `EQUALS`, `GREATER_THAN`, `LESS_THAN`, `BETWEEN`, `IN`, `CONTAINS`, `HAS_KEY`, `HAS_NOT_KEY`, `SUB_SET`.
`value`	string/number	No*	Value for `EQUALS`, `GREATER_THAN`, `LESS_THAN`, `CONTAINS` operators. For dates, use Unix timestamp in milliseconds.
`values`	array	No*	Array of values for `IN` or `SUB_SET` operators.
`range`	object	No*	Range object for `BETWEEN` operator. Contains `start` (inclusive) and `end` (exclusive) fields.

*One of value, values, or range is required depending on the operator.

Example Request: Basic Metadata Search

curl -i -X POST "https://{domain}.egnyte.com/pubapi/v2/search" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "offset": 0,
  "count": 20,
  "namespaces": [
    "namespace1",
    "namespace2"
  ],
  "custom_metadata": [
    {
      "namespace": "bear",
      "key": "the name",
      "operator": "EQUALS",
      "value": "hi"
    }
  ]
}'

Example Request: Advanced Operators

curl -i -X POST "https://{domain}.egnyte.com/pubapi/v2/search" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "custom_metadata": [
    {
      "namespace": "ns1",
      "key": "status",
      "operator": "EQUALS",
      "value": "active"
    },
    {
      "namespace": "ns1",
      "key": "priority",
      "operator": "GREATER_THAN",
      "value": 3
    },
    {
      "namespace": "ns1",
      "key": "effort",
      "operator": "LESS_THAN",
      "value": 40
    },
    {
      "namespace": "ns1",
      "key": "review_date",
      "operator": "BETWEEN",
      "range": {
        "start": 1704085200000,
        "end": 1735621200000
      }
    },
    {
      "namespace": "ns2",
      "key": "document_type",
      "operator": "IN",
      "values": [
        "invoice",
        "contract"
      ]
    },
    {
      "namespace": "ns2",
      "key": "metadata_map",
      "operator": "HAS_KEY"
    },
    {
      "namespace": "ns2",
      "key": "description",
      "operator": "CONTAINS",
      "value": "budget"
    },
    {
      "namespace": "egnyte document tags",
      "key": "document type",
      "operator": "SUB_SET",
      "values": [
        "Employee Handbook",
        "Balance Sheet",
        "Annual Reports"
      ]
    }
  ]
}'

Example Request: Similarity Search

curl -i -X POST "https://{domain}.egnyte.com/pubapi/v2/search" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "mlt": [
    "83d56dc9-2290-4645-b68d-98e3ec123891",
    "753e3124-ae6c-4aa6-b9a8-933c16835f9f"
  ],
  "mltt": [
    "Includes notices to bidders, substitution request forms, and various standard forms. Division 01 covers general requirements."
  ],
  "folder": "/Shared/Projects"
}'

Response

200 OK

Field	Type	Description
`count`	integer	Number of results returned in this response.
`total_count`	integer	Total number of matching results. If more than `count` results exist, returns `count + 1`.
`offset`	integer	The 0-based index of the first result in this response.
`hasMore`	boolean	`true` if there are more results available.
`results`	array	Array of matching files and folders.
`results[].name`	string	Name of the file or folder.
`results[].path`	string	Full path to the item in Egnyte.
`results[].type`	string	MIME type of the file.
`results[].size`	integer	Size of the file in bytes.
`results[].snippet`	string	Plain text snippet containing matched content.
`results[].snippet_html`	string	HTML-formatted snippet containing matched content.
`results[].entry_id`	string	Unique GUID for this file or folder instance.
`results[].group_id`	string	Group identifier for the item.
`results[].last_modified`	string	ISO-8601 timestamp of last modification.
`results[].uploaded_by`	string	Display name of the user who uploaded the file.
`results[].uploaded_by_username`	string	Username of the user who uploaded the file.
`results[].num_versions`	integer	Number of versions available for this file.
`results[].is_folder`	boolean	`true` if the item is a folder, `false` if it's a file.
`results[].custom_properties`	array	Array of custom metadata values for this item.
`results[].custom_properties[].namespace`	string	Metadata namespace.
`results[].custom_properties[].key`	string	Metadata key.
`results[].custom_properties[].value`	string	Metadata value.
`results[].custom_properties[].scope`	string	Metadata scope (e.g., `public`).
`results[].custom_properties[].valueToStampOnFile`	string	Value to display on file stamps (if applicable).
`results[].score`	number	Relevance score for this result.

Example Response

{
  "count": 1,
  "total_count": 1,
  "hasMore": false,
  "results": [{
    "num_versions": 0,
    "name": "temp_image.jpg",
    "custom_properties": [
      {
        "scope": "public",
        "namespace": "bear",
        "value": "hi",
        "key": "the name"
      },
      {
        "scope": "public",
        "namespace": "bear",
        "value": "another value",
        "key": "a key not searched for"
      },
      {
        "scope": "public",
        "namespace": "namespace1",
        "value": "value1",
        "key": "key1"
      },
      {
        "scope": "public",
        "namespace": "namespace1",
        "value": "",
        "key": "key2"
      }
    ],
    "uploaded_by_username": "gyang",
    "snippet": "",
    "last_modified": "2020-08-27T01:31:00Z",
    "entry_id": "1603e372-75f2-4b9f-af74-080dec5e4aef",
    "is_folder": false,
    "uploaded_by": "Grant Yanng",
    "path": "/Shared/images/temp_image.jpg",
    "group_id": "1234567c-ac62-222f-a5d5-e84aaa4050f0",
    "type": "image/jpeg",
    "snippet_html": "",
    "size": 80972
  }],
  "offset": 0
}

Error Codes

Status	Error	Description	Resolution
400	Bad Request	Invalid query parameter or malformed JSON body	Verify query length (3–100 characters), check JSON syntax, and ensure operator matches value type
401	Unauthorized	Invalid or expired OAuth token	Refresh your OAuth token
403	Forbidden	User lacks permission to access search results	Ensure the user has read access to the folders being searched
404	Not Found	Requested resource does not exist	Verify the request path
429	Rate Limited	Too many requests	Implement exponential backoff; check `Retry-After` header

Note: If a folder-scoped search returns no results, check that the folder path exists and is encoded the right way for the API version (encoded once in v1, plain in v2).

Code Examples

GET /pubapi/v1/search?query=financial%20report&count=10&sort_by=last_mo...

curl -i -X GET "https://{domain}.egnyte.com/pubapi/v1/search?query=financial%20report&count=10&sort_by=last_modified&sort_direction=descending" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

POST /pubapi/v2/search

curl -i -X POST "https://{domain}.egnyte.com/pubapi/v2/search" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "query": "contract",
  "custom_metadata": [
    {
      "namespace": "legal",
      "key": "status",
      "operator": "EQUALS",
      "value": "approved"
    }
  ],
  "namespaces": [
    "legal",
    "finance"
  ]
}'

POST /pubapi/v2/search

curl -i -X POST "https://{domain}.egnyte.com/pubapi/v2/search" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -d '{
  "mlt": [
    "83d56dc9-2290-4645-b68d-98e3ec123891"
  ],
  "mltt": [
    "Project specifications and requirements document"
  ],
  "folder": "/Shared/Projects",
  "count": 5
}'

Authentication — How to obtain and refresh OAuth tokens
File System API — Create, read, update, and delete files and folders
Metadata API — Manage custom metadata namespaces and values
Best Practices — Rate limiting, pagination, and error handling

Reference →Browse all endpoints

Search

Base URL

Authentication

Search (v1)

Request

Query Parameters

Response

Search (v2)

Request

Request Body

Custom Metadata Filter Object

Response

Error Codes

Code Examples

Related Resources