# GatherContent API Documentation > Documentation for GatherContent API ## Guides - [Webhook Payloads](https://docs.gathercontent.com/docs/webhooks.md) ## API Reference - [Components](https://docs.gathercontent.com/reference/components.md) - [List components](https://docs.gathercontent.com/reference/listcomponents.md): List components for a given project - [Create a component](https://docs.gathercontent.com/reference/createcomponent.md): Create a component within a given project - [Get a component](https://docs.gathercontent.com/reference/getcomponent.md): Get a components by id - [Delete a component](https://docs.gathercontent.com/reference/deletecomponent.md): Delete a components by id - [Update a components fields](https://docs.gathercontent.com/reference/updatecomponentfields.md) - [Rename a component](https://docs.gathercontent.com/reference/renamecomponent.md) - [Items](https://docs.gathercontent.com/reference/items.md) - [List items](https://docs.gathercontent.com/reference/listitems.md): ### 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. - [Create item](https://docs.gathercontent.com/reference/createitem.md): In it's simplest form, creating an item just requires the `project_id` in the path parameters. You will usually want to set at least a `name`, and one of `template_id` **OR** `structure` (but not both). You can also set a workflow `status_id`, a `folder_uuid` and `position` to set where in the hierarchy of existing items the new item should be placed (the default is appended to the existing items in the project root folder). You can optionally set the `content` for the item too, which is an array of objects for every field you want to set the content for. Each object must contain a `uuid` (which matches a field uuid from the items template or custom structure) and `content`, which is where the raw HTML, text or other content should go. - [Get item](https://docs.gathercontent.com/reference/getitem.md): Fetches the item with content for the given item id path parameter. - [Update item structure](https://docs.gathercontent.com/reference/updateitemstructure.md): Update the structure of an item. - [Update item content](https://docs.gathercontent.com/reference/updateitemcontent.md): Update the content of an existing item. The existing item will have a structure which will contain fields. You can update any number of the items fields by sending an array of content values in the request body, keyed by the field `uuid`. For example, if you only want to update a single field you would only send a single field in the request body. The content value could take one of a few formats, depending on the field type. For example: - **Text Field (HTML or plain text)** - this should just be the value, e.g. "<h1>hello</h1><p>world</p>" or "hello world" - **Repeatable Text Fields** - This should be an ordered array of content values. All repeatable text fields that you wish to keep should be included in the array, otherwise they will be deleted. Any fields you wish to add simply include them in the array, at the order you wish for the content to appear. E.g. If existing repeatable fields has content ['hello', 'world', 'test'] then submitted content array of ['hello', 'world'] would delete 'test' field. Alternatively, submitting a content array of ['hello', 'world', 'test', 'another'] would create a new field with the text 'another'. Submitting a content array of ['world', 'hello', 'test'] would simply swap the first two fields content. - **Option Field** - this should be an array of objects which each containing the selected option id as an id property, e.g. [{"id": "864cc5f7-e93b-4077-8b88-e4448a26c892"}]. If the option field has "other option" enabled, you can select that by id _and_ set a value for the other option e.g. [{"id": "d6e91c1e-7765-454e-90fe-0ef272768a8e", "value": "Other option value"}] - **Attachment Field** - To leave this field unchanged, omit the field id from the content object in the request. To _remove_ all existing attachments for the field, send an empty array `[]`. To keep one or more existing attachments, or rearrange the order of attachments, send an array of the `fileIds` in the new order, omitting any files that you want to remove, e.g. ["MjU5MzE/elo0LlJffypudKIs", "MjU5MzE/26KVIGh2CCyLjTq8"]. **Deprecated - Uploading files directly to items is soon to be deprecated, please see the [Upload files endpoint](https://docs.gathercontent.com/reference/upload-filed)** to upload the files to the project, and then include them in the content as described above. To upload one or more new files to an attachment field, send a `multipart/form-data` request, with each file keyed by `assets[field id][optional index if more than one file]`, e.g. `assets[46529874-0e0d-43fe-8c90-e65d4765573b]` or `assets[46529874-0e0d-43fe-8c90-e65d4765573b][0]`. It is possible to upload new `assets` and update the `content` of other fields in the same `multipart/form-data` request. - **Component Field** - A component field can be repeatable, and will contain a collection of fields. Fields omitted from the request wont be updated. - [Rename item](https://docs.gathercontent.com/reference/renameitem.md): Rename an existing item - [Move item](https://docs.gathercontent.com/reference/moveitem.md): Move an existing item - reposition within the current folder, or move to a different folder. - [Apply template to an item](https://docs.gathercontent.com/reference/applytemplate.md): Apply an existing template to an item. **Caution** - the fields from the new template _will replace the fields_ in the current item, _without copying_ the content. (The previous content will only exist and be accessible in the items revision history) - [Disconnect template from item](https://docs.gathercontent.com/reference/disconnecttemplate.md): Disconnect item from current template. This will create a new "custom structure" for the item, and any existing content will be copied across. If the item is not connected to a template, no change will occur. - [Save custom structure as template](https://docs.gathercontent.com/reference/savecustomstructureastemplate.md): Save an items custom structure as a re-usable template - [Duplicate an item](https://docs.gathercontent.com/reference/duplicateitem.md): Duplicates an item, including its current status, template, content and files. Comments and conversations, assignees and due dates won't be included. - [Templates](https://docs.gathercontent.com/reference/templates.md) - [List templates](https://docs.gathercontent.com/reference/listtemplates.md): List templates for a project - [Create template](https://docs.gathercontent.com/reference/createtemplate.md) - [Get template](https://docs.gathercontent.com/reference/gettemplate.md): Get template by template ID - [Delete template](https://docs.gathercontent.com/reference/deletetemplate.md): Deletes template by ID. Note, you cannot delete a template if it's being used by one or more items. - [Update a templates structure](https://docs.gathercontent.com/reference/updatetemplatestructure.md): Update the structure of a template. - [Rename template](https://docs.gathercontent.com/reference/renametemplate.md): Rename an existing template - [Duplicate template](https://docs.gathercontent.com/reference/duplicatetemplate.md): Duplicate template - [Structures](https://docs.gathercontent.com/reference/structures.md) - [Get structure [Deprecated]](https://docs.gathercontent.com/reference/getstructure.md): Get structure by structure uuid - [Alter structure [Deprecated]](https://docs.gathercontent.com/reference/alterstructure.md): ### Alters structure for given structure uuid. This will asynchronously apply the structure changes to any items that are using this structure. You may optionally supply a `priority_item_id` which will attempt to make the changes to the item synchronously with the alterations to the structure. - [Save structure as template [Deprecated]](https://docs.gathercontent.com/reference/savestructureastemplate.md): Save the given structure as a re-usable template - [Folders](https://docs.gathercontent.com/reference/folders.md) - [List folders](https://docs.gathercontent.com/reference/listfolders.md): ### Returns a list of all folders belonging to a project. You may optionally include trashed folders by setting `include_trashed` to `true`. - [List folders as tree structure](https://docs.gathercontent.com/reference/listfoldersastree.md): ### Returns a list of all folders belonging to a project in their tree hierarchy. - [Create folder](https://docs.gathercontent.com/reference/createfolder.md): All folders (except the `project-root` and `project-archived` folders) have a `parent_uuid`. When you create a new folder you must POST to the parent folder that you want the new folder to belong to. You may optionally set a `name`, `uuid` and `position`, otherwise these will be generated for you. - [Rename folder](https://docs.gathercontent.com/reference/renamefolder.md): Folder name cannot be empty - [Move folder](https://docs.gathercontent.com/reference/movefolder.md): Move a folder within the existing folder hierarchy. If you only supply a `parent_uuid`, (i.e. omit the position) the folder will be moved to the bottom of the parent folder. To reposition a folder, simply send the same `parent_uuid` in the request, with the new `position` (folder positions are start at 0). You cannot move a folder into an archived folder, and you cannot move an archived folder - you must restore the folders first. - [Trash or Delete folder](https://docs.gathercontent.com/reference/trashordeletefolder.md): Move folder, and all descendant folders and items to trash. Once folder is in trash, calling delete again will permanently delete the folder, descendant folders and items. When a folder is trashed we will return the now trashed folder in the response, else a permanent delete will return 204 No-Content response. - [Restore folder](https://docs.gathercontent.com/reference/restorefolder.md): Restores a trashed folder, and all it's descendant folders and items, to the project. The folder is appended to the project root folder - once restored it can be moved to a desired location (we cannot restore it automatically to it's original parent because the parent may not exist anymore or may have been moved). Any sub- folders or items will keep their position in the hierarchy. - [List files](https://docs.gathercontent.com/reference/listfiles.md): List files for a given project #### Optional includes: - item_instances: Will include a `item_instances` field that contains an array of item id's that the file is attached via an attachment field. - metadata: Will include a `metadata` field that contains an array of any metadata that the file contains. - uploader: Will include `avatar`,`name` & `initials` fields of the user who uploaded the file. - [Upload files](https://docs.gathercontent.com/reference/upload-filed.md): Upload a file to a project - [Delete files](https://docs.gathercontent.com/reference/deletefile.md): Delete files from a project and remove them from any items they are associated to. - [Get file](https://docs.gathercontent.com/reference/getfile.md): Get a file. #### Optional includes: - item_instances: Will include a `item_instances` field that contains an array of item id's that the file is attached via an attachment field. - metadata: Will include a `metadata` field that contains an array of any metadata that the file contains. - uploader: Will include `avatar`,`name` & `initials` fields of the user who uploaded the file. - [List webhooks](https://docs.gathercontent.com/reference/listwebhooks-1.md): List subscribed webhooks for a given project - [Subscribe to event](https://docs.gathercontent.com/reference/subscribetowebhook-1.md): Create a webhook that subscribes to a system event. For more information, including a list of event names see: https://docs.gathercontent.com/docs/webhooks - [Unsubscribe from an event](https://docs.gathercontent.com/reference/deletewebhook-1.md): Deletes a webhook that was previously subscribed to an event ## Recipes - [Course Content: Adding content to an item](https://docs.gathercontent.com/recipes/course-content-adding-content-to-an-item-1.md) - [Course Content: Creating the item and it's structure](https://docs.gathercontent.com/recipes/course-content-creating-the-item-and-its-structure.md) - [Structure Definition](https://docs.gathercontent.com/recipes/structure-definition.md) - [Updating attachment fields](https://docs.gathercontent.com/recipes/updating-attachment-fields.md)