---
title: "Update a portal navigation item"
method: PUT
path: "/portal-navigation-items/{navId}"
tags: ["Portal Navigation Items"]
---

# Update a portal navigation item

`PUT /portal-navigation-items/{navId}`

## Request

- Base URL: `/management/v2/environments/DEFAULT` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/management/v2/environments/DEFAULT/portal-navigation-items/{navId}`
- Auth: one of:
  - HTTP basic
  - API key in cookie `Auth-Graviteeio-APIM`

User must have the ENVIRONMENT_DOCUMENTATION[update] permission.
ParentId is the unique identifier of the parent item.
* Optional parent ID. If provided, the item is set to that parent.
* If omitted, the item is moved to the root level.

Publication propagation applies only when the `published` value changes on a container navigation item (`FOLDER`, `API`, or `API_PRODUCT`).
When publishing a container, descendants are published only if `propagatePublishToChildren=true`.
If `propagatePublishToChildren` is omitted or false, only the selected item is published.
When unpublishing a container, descendants are always unpublished according to the business rule; `propagatePublishToChildren` is ignored and may be omitted.

## Path parameters

- `navId` string, uuid, required

## Query parameters

- `propagatePublishToChildren` boolean

## Request body

- union
  - UpdatePortalNavigationPage: Base portal navigation item for Update
    - `type` 'PAGE' | 'FOLDER' | 'LINK' | 'API' | 'API_PRODUCT', required: The type of the navigation item
    - `title` string, required: The title of the navigation item
    - `order` integer, required: The order of the navigation item, from 0 to MAX, where MAX is the maximum existing order within the target parent. If greater than MAX, the item is moved to the end of the target parent.
    - `parentId` string, uuid: The parent ID of the navigation item, if not provided item is moved to the root level
    - `published` boolean, required: Whether the navigation item is published or not
    - `visibility` 'PUBLIC' | 'PRIVATE', required: The portal visibility (used by portal navigation items)
    - `source` PortalNavigationItemSource: External source of the item content.
      - `type` string, required: Fetcher plugin id.
      - `configuration` object, required: Fetcher configuration.
      - `useAutoFetch` boolean: Whether the content is automatically re-fetched on a schedule.
      - `fetchCron` string: Cron expression driving the auto-fetch schedule. Only used when useAutoFetch is true.
      - `lastFetchedAt` string, date-time: Date of the last successful fetch.
      - `lastFetchAttemptAt` string, date-time: Date of the last fetch attempt, successful or not. This is the date the auto-fetch schedule is computed from, and it dates lastFetchError when the last attempt failed.
      - `lastFetchError` string: Error message of the last failed fetch. Absent when the last fetch succeeded.
  - UpdatePortalNavigationFolder: Base portal navigation item for Update
    - `type` 'PAGE' | 'FOLDER' | 'LINK' | 'API' | 'API_PRODUCT', required: The type of the navigation item
    - `title` string, required: The title of the navigation item
    - `order` integer, required: The order of the navigation item, from 0 to MAX, where MAX is the maximum existing order within the target parent. If greater than MAX, the item is moved to the end of the target parent.
    - `parentId` string, uuid: The parent ID of the navigation item, if not provided item is moved to the root level
    - `published` boolean, required: Whether the navigation item is published or not
    - `visibility` 'PUBLIC' | 'PRIVATE', required: The portal visibility (used by portal navigation items)
    - `source` PortalNavigationItemSource: External source of the item content.
      - `type` string, required: Fetcher plugin id.
      - `configuration` object, required: Fetcher configuration.
      - `useAutoFetch` boolean: Whether the content is automatically re-fetched on a schedule.
      - `fetchCron` string: Cron expression driving the auto-fetch schedule. Only used when useAutoFetch is true.
      - `lastFetchedAt` string, date-time: Date of the last successful fetch.
      - `lastFetchAttemptAt` string, date-time: Date of the last fetch attempt, successful or not. This is the date the auto-fetch schedule is computed from, and it dates lastFetchError when the last attempt failed.
      - `lastFetchError` string: Error message of the last failed fetch. Absent when the last fetch succeeded.
  - UpdatePortalNavigationLink: Base portal navigation item for Update
    - `type` 'PAGE' | 'FOLDER' | 'LINK' | 'API' | 'API_PRODUCT', required: The type of the navigation item
    - `title` string, required: The title of the navigation item
    - `order` integer, required: The order of the navigation item, from 0 to MAX, where MAX is the maximum existing order within the target parent. If greater than MAX, the item is moved to the end of the target parent.
    - `parentId` string, uuid: The parent ID of the navigation item, if not provided item is moved to the root level
    - `published` boolean, required: Whether the navigation item is published or not
    - `visibility` 'PUBLIC' | 'PRIVATE', required: The portal visibility (used by portal navigation items)
    - `url` string, required: The URL for the link
  - UpdatePortalNavigationApi: Base portal navigation item for Update
    - `type` 'PAGE' | 'FOLDER' | 'LINK' | 'API' | 'API_PRODUCT', required: The type of the navigation item
    - `title` string, required: The title of the navigation item
    - `order` integer, required: The order of the navigation item, from 0 to MAX, where MAX is the maximum existing order within the target parent. If greater than MAX, the item is moved to the end of the target parent.
    - `parentId` string, uuid: The parent ID of the navigation item, if not provided item is moved to the root level
    - `published` boolean, required: Whether the navigation item is published or not
    - `visibility` 'PUBLIC' | 'PRIVATE', required: The portal visibility (used by portal navigation items)
    - `apiId` string, required: The apiId for the navigationItem
    - `categoryIds` string[]: The IDs of the Portal Next categories this API navigation item is assigned to. Defaults to an empty list if not provided.
  - UpdatePortalNavigationApiProduct: Base portal navigation item for Update
    - `type` 'PAGE' | 'FOLDER' | 'LINK' | 'API' | 'API_PRODUCT', required: The type of the navigation item
    - `title` string, required: The title of the navigation item
    - `order` integer, required: The order of the navigation item, from 0 to MAX, where MAX is the maximum existing order within the target parent. If greater than MAX, the item is moved to the end of the target parent.
    - `parentId` string, uuid: The parent ID of the navigation item, if not provided item is moved to the root level
    - `published` boolean, required: Whether the navigation item is published or not
    - `visibility` 'PUBLIC' | 'PRIVATE', required: The portal visibility (used by portal navigation items)

## Response `200`

Updated portal navigation item

- union
  - PortalNavigationPage: Base portal navigation item
    - `id` string, uuid, required: The unique ID of the navigation item
    - `organizationId` string, required: The organization ID
    - `environmentId` string, required: The environment ID
    - `title` string, required: The title of the navigation item
    - `type` 'PAGE' | 'FOLDER' | 'LINK' | 'API' | 'API_PRODUCT', required: The type of the navigation item
    - `area` 'HOMEPAGE' | 'TOP_NAVBAR', required: The portal area (used by portal navigation items)
    - `parentId` string, uuid: The parent ID of the navigation item
    - `rootId` string, uuid, required: The root parent ID of the navigation item hierarchy
    - `order` integer, required: The order of the navigation item (zero-based)
    - `published` boolean, required: Whether the navigation item is published or not
    - `visibility` 'PUBLIC' | 'PRIVATE', required: The portal visibility (used by portal navigation items)
    - `portalPageContentId` string, uuid, required: The UUID of the portal page content
    - `source` PortalNavigationItemSource: External source of the item content.
      - `type` string, required: Fetcher plugin id.
      - `configuration` object, required: Fetcher configuration.
      - `useAutoFetch` boolean: Whether the content is automatically re-fetched on a schedule.
      - `fetchCron` string: Cron expression driving the auto-fetch schedule. Only used when useAutoFetch is true.
      - `lastFetchedAt` string, date-time: Date of the last successful fetch.
      - `lastFetchAttemptAt` string, date-time: Date of the last fetch attempt, successful or not. This is the date the auto-fetch schedule is computed from, and it dates lastFetchError when the last attempt failed.
      - `lastFetchError` string: Error message of the last failed fetch. Absent when the last fetch succeeded.
  - PortalNavigationFolder: Base portal navigation item
    - `id` string, uuid, required: The unique ID of the navigation item
    - `organizationId` string, required: The organization ID
    - `environmentId` string, required: The environment ID
    - `title` string, required: The title of the navigation item
    - `type` 'PAGE' | 'FOLDER' | 'LINK' | 'API' | 'API_PRODUCT', required: The type of the navigation item
    - `area` 'HOMEPAGE' | 'TOP_NAVBAR', required: The portal area (used by portal navigation items)
    - `parentId` string, uuid: The parent ID of the navigation item
    - `rootId` string, uuid, required: The root parent ID of the navigation item hierarchy
    - `order` integer, required: The order of the navigation item (zero-based)
    - `published` boolean, required: Whether the navigation item is published or not
    - `visibility` 'PUBLIC' | 'PRIVATE', required: The portal visibility (used by portal navigation items)
    - `source` PortalNavigationItemSource: External source of the item content.
      - `type` string, required: Fetcher plugin id.
      - `configuration` object, required: Fetcher configuration.
      - `useAutoFetch` boolean: Whether the content is automatically re-fetched on a schedule.
      - `fetchCron` string: Cron expression driving the auto-fetch schedule. Only used when useAutoFetch is true.
      - `lastFetchedAt` string, date-time: Date of the last successful fetch.
      - `lastFetchAttemptAt` string, date-time: Date of the last fetch attempt, successful or not. This is the date the auto-fetch schedule is computed from, and it dates lastFetchError when the last attempt failed.
      - `lastFetchError` string: Error message of the last failed fetch. Absent when the last fetch succeeded.
  - PortalNavigationLink: Base portal navigation item
    - `id` string, uuid, required: The unique ID of the navigation item
    - `organizationId` string, required: The organization ID
    - `environmentId` string, required: The environment ID
    - `title` string, required: The title of the navigation item
    - `type` 'PAGE' | 'FOLDER' | 'LINK' | 'API' | 'API_PRODUCT', required: The type of the navigation item
    - `area` 'HOMEPAGE' | 'TOP_NAVBAR', required: The portal area (used by portal navigation items)
    - `parentId` string, uuid: The parent ID of the navigation item
    - `rootId` string, uuid, required: The root parent ID of the navigation item hierarchy
    - `order` integer, required: The order of the navigation item (zero-based)
    - `published` boolean, required: Whether the navigation item is published or not
    - `visibility` 'PUBLIC' | 'PRIVATE', required: The portal visibility (used by portal navigation items)
    - `url` string, required: The URL for the link
  - PortalNavigationApi: Base portal navigation item
    - `id` string, uuid, required: The unique ID of the navigation item
    - `organizationId` string, required: The organization ID
    - `environmentId` string, required: The environment ID
    - `title` string, required: The title of the navigation item
    - `type` 'PAGE' | 'FOLDER' | 'LINK' | 'API' | 'API_PRODUCT', required: The type of the navigation item
    - `area` 'HOMEPAGE' | 'TOP_NAVBAR', required: The portal area (used by portal navigation items)
    - `parentId` string, uuid: The parent ID of the navigation item
    - `rootId` string, uuid, required: The root parent ID of the navigation item hierarchy
    - `order` integer, required: The order of the navigation item (zero-based)
    - `published` boolean, required: Whether the navigation item is published or not
    - `visibility` 'PUBLIC' | 'PRIVATE', required: The portal visibility (used by portal navigation items)
    - `apiId` string, required: ApiId referenced from the navItem
    - `categoryIds` string[]: The IDs of the Portal Next categories this API navigation item is assigned to
  - PortalNavigationApiProduct: Base portal navigation item
    - `id` string, uuid, required: The unique ID of the navigation item
    - `organizationId` string, required: The organization ID
    - `environmentId` string, required: The environment ID
    - `title` string, required: The title of the navigation item
    - `type` 'PAGE' | 'FOLDER' | 'LINK' | 'API' | 'API_PRODUCT', required: The type of the navigation item
    - `area` 'HOMEPAGE' | 'TOP_NAVBAR', required: The portal area (used by portal navigation items)
    - `parentId` string, uuid: The parent ID of the navigation item
    - `rootId` string, uuid, required: The root parent ID of the navigation item hierarchy
    - `order` integer, required: The order of the navigation item (zero-based)
    - `published` boolean, required: Whether the navigation item is published or not
    - `visibility` 'PUBLIC' | 'PRIVATE', required: The portal visibility (used by portal navigation items)
    - `apiProductId` string, uuid, required: API Product referenced by the navigation item

## Other responses

- `400`: Invalid navigation item move, parent, visibility, or malformed request
- `404`: Navigation item or target parent does not exist
- `409`: The update would violate navigation hierarchy or API Product uniqueness constraints
- `default`: Generic error response

## Changes

- **2026-08-10** `37e8cbe5f769`: 2 info
  - added the optional property `oneOf[#/components/schemas/PortalNavigationFolder]/allOf[subschema #2]/source/lastFetchAttemptAt` to the response with the `200` status
  - added the optional property `oneOf[#/components/schemas/PortalNavigationPage]/allOf[subschema #2]/source/lastFetchAttemptAt` to the response with the `200` status
- **2026-08-06** `a2bffc8c2e17`: 1 breaking
  - for the `path` request parameter `navId`, the format changed from no format to `uuid`
- **2026-08-05** `d179daa13dee`: 2 info
  - added the new optional request property `oneOf[subschema #4: UpdatePortalNavigationApi]/allOf[subschema #2]/categoryIds`
  - added the optional property `oneOf[#/components/schemas/PortalNavigationApi]/allOf[subschema #2]/categoryIds` to the response with the `200` status
- **2026-07-31** `218efa41606c`: 2 breaking, 2 info
  - added `subschema #2` to the `oneOf[subschema #1: UpdatePortalNavigationPage]/` request property `allOf` list
  - added `subschema #2` to the `oneOf[subschema #2: UpdatePortalNavigationFolder]/` request property `allOf` list
  - added the optional property `oneOf[#/components/schemas/PortalNavigationPage]/allOf[subschema #2]/source` to the response with the `200` status
  - added `subschema #2` to the `oneOf[#/components/schemas/PortalNavigationFolder]/` response property `allOf` list for the response status `200`
- …earlier changes not shown

[Operation history](https://skmtc.dev/gravitee-io/apis/gravitee-io-apim-management-api-environments/changes/portal-navigation-items/:navId/put.md)

---

[API](https://skmtc.dev/gravitee-io/apis/gravitee-io-apim-management-api-environments.md) - [All operations](https://skmtc.dev/gravitee-io/apis/gravitee-io-apim-management-api-environments/llms.txt) - [OpenAPI document](https://skmtc.dev/gravitee-io/apis/gravitee-io-apim-management-api-environments/revisions/b736a7e375df?raw)