Tags API ======== .. contents:: :depth: 2 .. important:: This API is available only for sites that have this feature enabled. Please contact your Account Manager to enable it for your site. The tags API supports creation, deletion, and updating of tags that can be used to categorize your content. .. _creating-tags: Creating tags ------------- Creates a tag. .. code:: POST /api/1.3/tags Parameters ********** +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | Name | Type | Description | +======================================+===================+========================================================================================+ | ``title`` | String | Title - Required | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | ``url`` | String | Slug - Required | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | ``tags`` | Array of strings | Tags - Optional | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | ``status`` | Integer || Status - Optional | | | || Choices: | | | | | | | || - ``1``: Private (Default) | | | || - ``2``: Public | | | || - ``3``: Unlisted | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | ``about_html`` | String | About - Optional | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | ``meta_title`` | String | Meta title - Optional | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | ``page_settings`` | Object | Page settings - Optional | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | ``url_header_image`` | String | URL header image - Optional | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | ``header_image_id`` | Integer | ID of the uploaded header image (it takes precedence over url_header_image) - Optional | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | ``extras`` | Object | Custom fields - Optional | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ Response ******** .. code:: json { "id": 100, "title": "My tag", "url": "my-tag", "full_url": "my-tag", "status": 1, "meta_title": null, "page_settings": { "hide_from_entry_editor": false, "allow_community_posts": false, "open_in_new_tab": false }, "about_html": "", "tags": [], "url_header_image": "", "site_id": 9, "created_ts": 1507918417, "order": 3, "parent_id": 0, "type": 2, "extras": {}, "header_image_id": null } Editing tags ------------ Edits a tag. .. code:: PUT /api/1.3/tags/ Parameters ********** The same parameters from :ref:`creating-tags` apply here; however, ``title`` and ``url`` are not required. Response ******** The same specification from :ref:`creating-tags` section applies here. Deleting tags ------------- Deletes a tag. .. code:: DELETE /api/1.3/tags/ Parameters ********** No parameters are required. Response ******** The response payload is an empty object. .. code:: json {} List tags --------- Fetches tags information. .. code:: GET /api/1.3/tags Parameters ********** Applying the following parameters will filter the response. +--------------------+----------+-------------------------------------------+ | Name | Type | Description | +====================+==========+===========================================+ | ``include_fields`` | Array of | Fields to include in response – Optional | | | strings | | +--------------------+----------+-------------------------------------------+ | ``exclude_fields`` | Array of | Fields to exclude in response – Optional | | | strings | | +--------------------+----------+-------------------------------------------+ Response ******** It returns a list of objects described at :ref:`creating-tags` section. Get a single tag ---------------- Fetch a single tag by ID. .. code:: GET /api/1.3/tags/ Response ******** The same specification from :ref:`creating-tags` section applies here.