Sections API ============ .. contents:: :depth: 2 The section API supports creation, deletion, and updating of sections that can be used to categorize your content. .. _creating-sections: Creating sections ----------------- Creates a section. .. code:: POST /api/1.3/sections 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 | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | ``parent_id`` | Integer | Parent section ID - Optional | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ | ``extras`` | Object | Custom fields - Optional | +--------------------------------------+-------------------+----------------------------------------------------------------------------------------+ Page settings ************* ``page_settings`` is a set of configurations that can be enabled or disabled. =============================== ======= =================================================================================================== Name Type Description =============================== ======= =================================================================================================== ``open_in_new_tab`` Boolean Controls whether the section must be opened in a new browser tab - Optional - Defaults to ``false`` ``allow_community_posts`` Boolean Controls whether community posts can be published in a section - Optional - Defaults to ``false`` ``hide_from_entry_editor`` Boolean Controls whether the section is listed/available in entry editor - Optional - Defaults to ``false`` ``lock_posts_after_publishing`` Boolean Controls whether posts published to a specific section must be locked - Optional - Defaults to ``false`` =============================== ======= =================================================================================================== .. note:: After a section is created it will automatically be populated by posts that contain any of the configured tags for that section. Response ******** .. code:: json { "id": 100, "title": "My section", "url": "my-section", "full_url": "my-section", "status": 1, "meta_title": null, "page_settings": { "hide_from_entry_editor": false, "allow_community_posts": false, "open_in_new_tab": false }, "about_html": "", "tags": ["foo", "bar"], "url_header_image": "", "site_id": 9, "created_ts": 1507918417, "order": 3, "parent_id": 0, "type": 2, "extras": {}, "header_image_id": null } Editing sections ---------------- Edits a section. .. code:: PUT /api/1.3/sections/ Parameters ********** The same response structure used in :ref:`creating-sections` is also used here, however there are no required fields. .. note:: After a section is updated it is automatically assigned to posts that match by the new tags added and is going to be unassigned from articles by the removed tags. Response ******** The same specification from :ref:`creating-sections` section applies here. Deleting sections ----------------- Deletes a section. .. code:: DELETE /api/1.3/sections/ Parameters ********** ====================== ======= ================================= Name Type Description ====================== ======= ================================= destination_section_id Integer Destination section ID - Optional ====================== ======= ================================= .. note:: Parameters need to be sent by query string. Posts are going be moved to destination section if any. Response ******** The response payload is an empty object. .. code:: json {} List sections ------------- Fetches sections information. .. code:: GET /api/1.3/sections 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-sections` section. Get a single section -------------------- Fetch a single section by ID. .. code:: GET /api/1.3/sections/ Response ******** The same specification from :ref:`creating-sections` section applies here.