--- updatedAt: 2025-09-11T20:21:33.000Z agentTools: projectIndex: https://docs.gathercontent.com/llms.txt --- # List items ### List items for a given project You can apply multiple filters to narrow your search results, apply sorting and page through the results if there are large numbers of items that match your request. Many of the parameters take one or more comma separated arguments, allowing you to filter by multiple templates/assignees/statuses at once. e.g. ``` projects/{project_id}/items?template_id=1,3&status_id=4,5 ``` Some of the filters include optional includes, such as `with_conversation_count`. For performance reasons these are not included in the default response. These values should be either `0` for `false`, `1` for true, or omitted altogether. > 👍 Getting content for items > > Items retrieved via this endpoint will not include any content. In order to retrieve content you must [retrieve an item individually](https://docs.gathercontent.com/reference/getitem). # OpenAPI definition ````json { "openapi": "3.0.2", "info": { "title": "GatherContent API", "description": "This is the documentation for the latest stable version of the GatherContent API Find out more about GatherContent at [https://gathercontent.com](https://gathercontent.com) or get help at [https://help.gathercontent.com](https://help.gathercontent.com)", "version": "2.0.0", "termsOfService": "https://gathercontent.com/legal/terms-of-service", "contact": { "email": "development@gathercontent.com" } }, "x-samples-languages": [ "curl", "node", "ruby", "javascript", "python" ], "servers": [ { "url": "https://api.gathercontent.com" }, { "url": "https://api.gatherpreview.com" }, { "url": "http://api.gathercontent.test" } ], "externalDocs": { "description": "GatherContent help docs", "url": "https://help.gathercontent.com" }, "paths": { "/projects/{project_id}/items": { "parameters": [ { "$ref": "#/components/parameters/projectId" } ], "get": { "summary": "List items", "description": "### List items for a given project\nYou can apply multiple filters to narrow your search results, apply sorting and page through the results if there are large numbers of items that match your request.\nMany of the parameters take one or more comma separated arguments, allowing you to filter by multiple templates/assignees/statuses at once. e.g.\n``` projects/{project_id}/items?template_id=1,3&status_id=4,5 ```\nSome of the filters include optional includes, such as `with_conversation_count`. For performance reasons these are not included in the default response. These values should be either `0` for `false`, `1` for true, or omitted altogether.\n", "operationId": "listItems", "tags": [ "Items" ], "parameters": [ { "in": "query", "name": "include", "description": "A comma separated list of extra includes", "explode": false, "schema": { "type": "array", "items": { "enum": [ "template_name", "assignee_full_names", "folder_name", "status_name", "item_url", "structure" ] } } }, { "in": "query", "name": "with_conversation_count", "description": "Return the number of conversations on each item in the response object", "schema": { "type": "boolean" } }, { "in": "query", "name": "is_overdue", "description": "Return only overdue items", "schema": { "type": "boolean" } }, { "in": "query", "name": "is_archived", "description": "Return only archived items", "schema": { "type": "boolean" } }, { "in": "query", "name": "template_id", "description": "Filter by one or more template id(s). To filter items not using a template, use `0`.", "explode": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "in": "query", "name": "assigned_to", "description": "Filter by one or more assigned user id(s)", "explode": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "in": "query", "name": "folder_uuid", "description": "Filter by one or more folder uuid(s)", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/uuid" } } }, { "in": "query", "name": "status_id", "description": "Filter by one or more status id(s)", "explode": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "in": "query", "name": "item_id", "description": "Filter by one or more item id(s)", "explode": false, "schema": { "type": "array", "items": { "type": "integer" } } }, { "in": "query", "name": "name_contains", "description": "Filter items matching item name", "schema": { "type": "string" } }, { "in": "query", "name": "sort_by", "description": "Sort results by a given field", "schema": { "enum": [ "name", "template", "updated_at", "assignees", "next_due_at", "conversations", "position", "archived_by", "archived_at", "folder" ] } }, { "in": "query", "name": "sort_dir", "description": "Sort results ascending or descending", "schema": { "enum": [ "asc", "desc" ] } }, { "$ref": "#/components/parameters/perPage" }, { "$ref": "#/components/parameters/page" } ], "responses": { "200": { "description": "Success - OK", "content": { "application/vnd.gathercontent.v2+json": { "schema": { "$ref": "#/components/schemas/itemCollection" } } } }, "404": { "$ref": "#/components/responses/projectNotFoundError" }, "422": { "$ref": "#/components/responses/validationError" }, "429": { "$ref": "#/components/responses/tooManyRequests" } } } } }, "tags": [ { "name": "Items", "description": "Items are the where your content is held. An item may represent a webpage, article or component. It has a structure (which can either be linked to a reusable template - shared across multiple items, or it can have it's own \"custom\" structure - where the fields are unique to a particular item)." } ], "components": { "parameters": { "projectId": { "name": "project_id", "description": "Project id", "in": "path", "required": true, "schema": { "type": "integer" } }, "perPage": { "in": "query", "name": "per_page", "description": "How many results do you want to return (1-500, default 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, "page": { "in": "query", "name": "page", "description": "Which page of results do you want to return (default page 1)", "schema": { "type": "integer", "minimum": 1 } } }, "schemas": { "uuid": { "type": "string", "pattern": "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", "example": "aa23428b-9b43-4d7f-8c5c-0fb5fc3a944e" }, "uuidNullable": { "type": "string", "pattern": "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}", "example": "aa23428b-9b43-4d7f-8c5c-0fb5fc3a944e", "nullable": true }, "datetime": { "type": "string", "description": "DateTimes are all in UTC - it's up to the client to convert them to an appropriate time zone", "pattern": "\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}", "example": "2019-04-20T04:20:00.000Z" }, "datetimeNullable": { "type": "string", "description": "DateTimes are all in UTC - it's up to the client to convert them to an appropriate time zone", "pattern": "\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}", "example": "2019-04-20T04:20:00.000Z", "nullable": true }, "optionDefinition": { "type": "object", "required": [ "label" ], "properties": { "optionId": { "$ref": "#/components/schemas/uuid" }, "label": { "type": "string" } } }, "structureFieldType": { "type": "string", "enum": [ "text", "attachment", "guidelines", "choice_radio", "choice_checkbox", "component" ] }, "structureMeta": { "anyOf": [ { "type": "object", "description": "is_plain will only be applied to `text` fields", "required": [ "is_plain" ], "properties": { "is_plain": { "type": "boolean" } } }, { "type": "object", "description": "validation will only be applied to `text` fields", "required": [ "validation" ], "properties": { "validation": { "required": [ "rule", "limit" ], "properties": { "rule": { "type": "string", "enum": [ "chars", "words" ] }, "limit": { "type": "integer" } } } } }, { "type": "object", "description": "choice_fields will only be applied to `choice_radio` and `choice_checkbox` fields", "required": [ "choice_fields" ], "properties": { "choice_fields": { "type": "object", "required": [ "options" ], "properties": { "options": { "type": "array", "items": { "$ref": "#/components/schemas/optionDefinition" } }, "otherOption": { "$ref": "#/components/schemas/optionDefinition" } } } } }, { "type": "object", "description": "repeatable will only be applied to fields marked as repeatable", "required": [ "repeatable" ], "properties": { "repeatable": { "type": "object", "required": [ "isRepeatable", "limitEnabled", "limit" ], "properties": { "isRepeatable": { "type": "boolean" }, "limitEnabled": { "type": "boolean" }, "limit": { "type": "integer" } } } } } ] }, "structureFieldResponseDefinition": { "type": "object", "required": [ "field_type", "label" ], "properties": { "uuid": { "$ref": "#/components/schemas/uuid" }, "field_type": { "$ref": "#/components/schemas/structureFieldType" }, "label": { "type": "string" }, "instructions": { "type": "string" }, "component": { "$ref": "#/components/schemas/component" }, "metadata": { "$ref": "#/components/schemas/structureMeta" } } }, "componentStructureFieldDefinition": { "type": "object", "required": [ "field_type", "label" ], "properties": { "uuid": { "$ref": "#/components/schemas/uuid" }, "field_type": { "$ref": "#/components/schemas/structureFieldType" }, "label": { "type": "string" }, "instructions": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/structureMeta" } } }, "fieldGroupDefinition": { "type": "object", "required": [ "name" ], "properties": { "uuid": { "$ref": "#/components/schemas/uuid" }, "name": { "type": "string", "example": "Group name" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/structureFieldResponseDefinition" } } } }, "itemStructureDefinition": { "type": "object", "properties": { "uuid": { "$ref": "#/components/schemas/uuid" }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/fieldGroupDefinition" } } } }, "component": { "type": "object", "description": "A component object", "properties": { "uuid": { "$ref": "#/components/schemas/uuid" }, "name": { "type": "string", "example": "My component" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/componentStructureFieldDefinition" } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "count": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "total_pages": { "type": "integer" }, "links": { "type": "object" } } }, "itemDefinition": { "type": "object", "properties": { "id": { "type": "integer" }, "project_id": { "type": "integer" }, "status_id": { "type": "integer" }, "folder_uuid": { "$ref": "#/components/schemas/uuidNullable" }, "template_id": { "type": "integer", "nullable": true }, "structure_uuid": { "$ref": "#/components/schemas/uuid" }, "position": { "type": "integer", "minimum": 0 }, "name": { "type": "string" }, "archived_by": { "type": "integer", "nullable": true }, "archived_at": { "$ref": "#/components/schemas/datetimeNullable" }, "created_at": { "$ref": "#/components/schemas/datetime" }, "updated_at": { "$ref": "#/components/schemas/datetimeNullable" }, "next_due_at": { "$ref": "#/components/schemas/datetimeNullable" }, "completed_at": { "$ref": "#/components/schemas/datetimeNullable" }, "assigned_user_ids": { "type": "array", "items": { "type": "integer" } }, "assinee_count": { "type": "integer" }, "structure": { "$ref": "#/components/schemas/itemStructureDefinition" } } }, "itemCollection": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/itemDefinition" } }, "pagination": { "$ref": "#/components/schemas/pagination" } } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } }, "responses": { "validationError": { "description": "Validation error", "content": { "application/vnd.gathercontent.v2+json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "The given data was invalid" }, "code": { "type": "integer", "example": 422 }, "messages": { "type": "object", "description": "Key/value mapping of invalid field => failure reason. This changes depending on which data is invalid." } } } } } }, "tooManyRequests": { "description": "Too many request", "content": { "application/vnd.gathercontent.v2+json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Too Many Attempts." }, "code": { "type": "integer", "example": 429 } } } } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Request limit." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "The number of requests left for the time window." }, "X-RateLimit-Reset": { "schema": { "type": "string" }, "description": "The Unix timestamp at which the current rate limit window resets." }, "Retry-After": { "schema": { "type": "integer" }, "description": "The number of seconds before the current rate limit window resets." } } }, "projectNotFoundError": { "description": "Project not found", "content": { "application/vnd.gathercontent.v2+json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Project not found" }, "code": { "type": "integer", "example": 404 } } } } } } } }, "security": [ { "basicAuth": [] } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ````