--- updatedAt: 2026-09-22T19:15:06.000Z agentTools: projectIndex: https://docs.zesty.io/llms.txt --- # Search Content Items Allows searching for contents by either ZUID, meta text values or path-related values. This accepts the follow query params: | param | description | | --------- | --------------------- | | q | [string] Can be either a text string that refers to meta text values, path-related key values, or a ZUID of type content model, user or item. | | limit | [int] The number of results to return. Allowed values are numbers between 1 to 1000. Default is 100. | | page | [int] The offset of where the result should start. Usually used in combination with the `limit` parameter. | | order | [string] What to order results by. Allowed values are created, modified and label. | | dir | [string] **Required** if order key is provided. Determines the sorting direction in either ascending or descending. Allowed values are asc and desc. Default is desc. | | start_date | [string] Aceptable date formats are `yyyy/mm/dd` `(2022/01/31)` and `mm/dd/yyyy` `(01/31/2022)`. You can also use dashes `(01-25-2022)` as a separator. More info here: https://github.com/araddon/dateparse - **Note:** _The filtering will be based on the item's updateAt value_. | | end_date | [string] Aceptable date formats are `yyyy/mm/dd` `(2022/01/31)` and `mm/dd/yyyy` `(01/31/2022)`. You can also use dashes `(01-25-2022)` as a separator. More info here: https://github.com/araddon/dateparse - **Note:** _The filtering will be based on the item's updateAt value_. | List of ZUID types that will do the search into for 'q' value: - Content Models (6-0000-0000) - Users (5-0000-0000) - Items (7-0000-0000) List of meta and path keys that will do the search into if 'q' value is not a ZUID: - URL Path Part - Full Path - Navigation Link Text - Meta Title - Meta Description - Meta Keywords # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "description": "A collection of available REST endpoints scoped to your unique instance.\n\n# ZUID\nAll named resources in this API have a unique identifier called a ZUID. For example an instance ZUID would look like `8-f48cf3a682-7fthvk`. The initial prefix, e.g. `8-`, represents the type of resource it is. Every discreet resource has it's own prefix. To find a full list of supported ZUIDs and to learn more read the spec; https://github.com/zesty-io/zuid-specification\n\n# URLs\nAs you peruse the available endpoints you will see the URLs which can be requested. The following is an explanation of the URL structure and the significance of specific portions.\n\nFor example the URL https://8-f48cf3a682-7fthvk.api.zesty.io/v1/content/models/6-556370-8sh47g/items/7-b939a4-457q19/publishings/18-660e14-jpx715 would breakdown as follows:\n\n| URL portion | description |\n| --- | --- |\n| https:// | protocol |\n| 8-f48cf3a682-7fthvk | Your instances unique identifier |\n| .api.zesty.io/ | domain for the API |\n| v1 | version of the API |\n| /content/models/6-556370-8sh47g | path to a unique content model |\n| /items/7-b939a4-457q19 | path to a unique item which belongs to the prior model |\n| /publishings/18-660e14-jpx715 | path to a unique publishings record which belongs to the prior item |\n\n# Getting an Auth Token\nThere are two types of authorization; session and access tokens. Read more about them here https://zesty.org/apis/auth-api#user-authentication", "title": "Instances API", "contact": {}, "version": "1.0" }, "paths": { "/search/items": { "get": { "security": [ { "Bearer": [] } ], "description": "Allows searching for contents by either ZUID, meta text values or path-related values. This accepts the follow query params:\n\n| param | description |\n| --------- | --------------------- |\n| q | [string] Can be either a text string that refers to meta text values, path-related key values, or a ZUID of type content model, user or item. |\n| limit | [int] The number of results to return. Allowed values are numbers between 1 to 1000. Default is 100. |\n| page | [int] The offset of where the result should start. Usually used in combination with the `limit` parameter. |\n| order | [string] What to order results by. Allowed values are created, modified and label. |\n| dir | [string] **Required** if order key is provided. Determines the sorting direction in either ascending or descending. Allowed values are asc and desc. Default is desc. |\n| start_date | [string] Aceptable date formats are `yyyy/mm/dd` `(2022/01/31)` and `mm/dd/yyyy` `(01/31/2022)`. You can also use dashes `(01-25-2022)` as a separator. More info here: https://github.com/araddon/dateparse - **Note:** _The filtering will be based on the item's updateAt value_. |\n| end_date | [string] Aceptable date formats are `yyyy/mm/dd` `(2022/01/31)` and `mm/dd/yyyy` `(01/31/2022)`. You can also use dashes `(01-25-2022)` as a separator. More info here: https://github.com/araddon/dateparse - **Note:** _The filtering will be based on the item's updateAt value_. |\n\nList of ZUID types that will do the search into for 'q' value:\n- Content Models (6-0000-0000)\n- Users (5-0000-0000)\n- Items (7-0000-0000)\n\nList of meta and path keys that will do the search into if 'q' value is not a ZUID:\n- URL Path Part\n- Full Path\n- Navigation Link Text\n- Meta Title\n- Meta Description\n- Meta Keywords", "tags": [ "/search" ], "summary": "Search Content Items", "operationId": "search-content-items", "parameters": [ { "example": 10, "description": "The number of results to return. Allowed values are numbers between 1 to 1000. Default is 100", "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "example": 1, "description": "The offset of where the result should start. Usually used in combination with the `limit` parameter.", "name": "page", "in": "query", "schema": { "type": "integer" } }, { "example": "created", "description": "What to order results by. Allowed values are created, modified and label", "name": "order", "in": "query", "schema": { "type": "string" } }, { "example": "desc", "description": "Required if order key is provided. Determines the sorting direction in either ascending or descending. Allowed values are asc and desc. Default is desc.", "name": "dir", "in": "query", "schema": { "type": "string" } }, { "example": "01/31/2022", "description": "Aceptable date formats are yyyy/mm/dd (2022/01/31) and mm/dd/yyyy (01/31/2022). You can also use dashes (01-25-2022) as a separator. More info here: https://github.com/araddon/dateparse - Note: The filtering will be based on the item's updateAt value.", "name": "start_date", "in": "query", "schema": { "type": "string" } }, { "example": "02/31/2022", "description": "Aceptable date formats are yyyy/mm/dd (2022/01/31) and mm/dd/yyyy (01/31/2022). You can also use dashes (01-25-2022) as a separator. More info here: https://github.com/araddon/dateparse - Note: The filtering will be based on the item's updateAt value.", "name": "end_date", "in": "query", "schema": { "type": "string" } }, { "example": "animals", "description": "Can be either a text string that refers to meta text values, path-related key values, or a ZUID of type content model, user or item.", "name": "q", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/body_samples.JSONResult" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/body_samples.SearchItemsResponseSuccess" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/body_samples.DataItem" }, "meta": { "$ref": "#/components/schemas/body_samples.MetaItem" }, "siblings": { "$ref": "#/components/schemas/body_samples.SiblingsItem" }, "web": { "$ref": "#/components/schemas/body_samples.WebItem" } } } ] } } } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/body_samples.JSONResultUnauthorized" } } } } }, "x-readme": { "explorer-enabled": false } } } }, "tags": [ { "description": "Endpoint to search for a set of specific entity based on the query params provided. Right now, the only searchable entity is Item.", "name": "/search" } ], "servers": [ { "url": "https://{instance_zuid}.api.zesty.io/v1", "variables": { "instance_zuid": { "default": "unknown" } } } ], "components": { "securitySchemes": { "Bearer": { "description": "Type \"Bearer\" followed by a space and JWT token.", "type": "apiKey", "name": "Authorization", "in": "header" } }, "schemas": { "body_samples.DataItem": { "type": "object", "properties": { "content": { "type": "string", "example": "

Blank

" }, "image": { "type": "string", "example": "https://be93523bd41e2e475e74-e4edef19ad51123442eaceed55c78461.ssl.cf2.rackcdn.com/or-homepage1.png" }, "title": { "type": "string", "example": "My Homepage" } } }, "body_samples.EmptyData": { "type": "object" }, "body_samples.JSONResult": { "type": "object", "properties": { "_meta": { "$ref": "#/components/schemas/body_samples.Meta" }, "data": {} } }, "body_samples.JSONResultUnauthorized": { "type": "object", "properties": { "_meta": { "$ref": "#/components/schemas/body_samples.Meta" }, "data": { "$ref": "#/components/schemas/body_samples.EmptyData" }, "error": { "type": "string", "example": "invalid session" } } }, "body_samples.Meta": { "type": "object", "properties": { "limit": { "type": "integer", "example": 1 }, "offset": { "type": "integer", "example": 0 }, "start": { "type": "integer", "example": 0 }, "timestamp": { "type": "string", "example": "2024-04-11T14:49:51.039478001Z" }, "totalResults": { "type": "integer", "example": 1 } } }, "body_samples.MetaItem": { "type": "object", "properties": { "ZUID": { "type": "string", "example": "7-abcd-1234" }, "contentModelName": { "type": "string", "example": "Test Content Model" }, "contentModelZUID": { "type": "string", "example": "6-abcd-1234" }, "createdAt": { "type": "string", "format": "date-time", "example": "2021-06-29T20:00:00Z" }, "langID": { "type": "integer", "example": 1 }, "listed": { "type": "boolean", "example": true }, "masterZUID": { "type": "string", "example": "7-abcd-1234" }, "sort": { "type": "integer", "example": 0 }, "updatedAt": { "type": "string", "format": "date-time", "example": "2021-06-29T20:00:00Z" }, "version": { "type": "integer", "example": 1 } } }, "body_samples.SearchItemsResponseSuccess": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/body_samples.DataItem" }, "meta": { "$ref": "#/components/schemas/body_samples.MetaItem" }, "siblings": { "$ref": "#/components/schemas/body_samples.SiblingsItem" }, "web": { "$ref": "#/components/schemas/body_samples.WebItem" } } }, "body_samples.SiblingsItem": { "type": "object", "properties": { "cs": { "type": "string", "example": "7-324534-34fdwf" }, "en-us": { "type": "string", "example": "7-3245ew-5dwfsr" } } }, "body_samples.WebItem": { "type": "object", "properties": { "canonicalQueryParamWhitelist": { "type": "string", "example": "null", "nullable": true }, "canonicalTagCustomValue": { "type": "string", "example": "null", "nullable": true }, "canonicalTagMode": { "type": "integer", "example": 1 }, "createdAt": { "type": "string", "format": "date-time", "example": "2021-06-29T20:00:00Z" }, "createdByUserZUID": { "type": "string", "example": "5-abcd-1234" }, "metaDescription": { "type": "string", "example": "" }, "metaKeywords": { "type": "string", "example": "null", "nullable": true }, "metaLinkText": { "type": "string", "example": "Homepage" }, "metaTitle": { "type": "string", "example": "Homepage" }, "parentZUID": { "type": "string", "example": "0" }, "path": { "type": "string", "example": "/" }, "pathPart": { "type": "string", "example": "zesty_home" }, "sitemapPriority": { "type": "integer", "example": -1 }, "updatedAt": { "type": "string", "format": "date-time", "example": "2021-06-29T20:00:00Z" }, "version": { "type": "integer", "example": 1 }, "versionZUID": { "type": "string", "example": "9-abcd-1234" } } } } } } ```