UI API — Nav

apiClient.ui.nav manages navigation structures — tree-shaped menus that drive sidebar and top-level navigation in the platform.

Nav Node Destinations

Nav nodes use a destination enum to control where they navigate. Available values (from UI.CRUD.Destination):

Methods

create

Create a new navigation structure.

import { UI } from '@skedulo/protobuf-web'

const nav = await apiClient.ui.nav.create({
  nav: {
    name: 'Main Nav',
    nodes: [
      {
        label: 'Jobs',
        destination: UI.CRUD.Destination.PLATFORM,
        ref: 'jobs',
      },
      {
        label: 'Resources',
        destination: UI.CRUD.Destination.PLATFORM,
        ref: 'resources',
      },
    ],
  },
})
console.log(nav.uid)

get

Fetch a single nav by UID. Nodes are role-restricted based on the current user.

const nav = await apiClient.ui.nav.get({ uid: 'abc123' })

getUnrestricted

Fetch a nav by UID without role restrictions — returns all nodes regardless of permissions.

const nav = await apiClient.ui.nav.getUnrestricted({ uid: 'abc123' })

getMany

Fetch multiple navs, with optional filters.

const navs = await apiClient.ui.nav.getMany({ name: 'Main Nav', limit: 100 })

// Paginated
const page = await apiClient.ui.nav.getMany({ limit: 10, page: 1 })

put

Update an existing nav. Uses merge-and-put — only include the fields you want to change.

await apiClient.ui.nav.put({
  nav: {
    uid: 'abc123',
    nodes: [
      {
        label: 'Dashboard',
        destination: UI.CRUD.Destination.PLATFORM,
        ref: 'dashboard',
      },
    ],
  },
})

del

Delete a nav by UID.

await apiClient.ui.nav.del({ uid: 'abc123' })

getBestNav

Find the best-matching nav by name (sorted by relevance). Returns null if none found.

const nav = await apiClient.ui.nav.getBestNav('Main Nav')

getBestNavUnrestricted

Same as getBestNav but without role restrictions.

const nav = await apiClient.ui.nav.getBestNavUnrestricted('Main Nav')

getDestinations

List all available navigation destinations, optionally filtered by destination type.

import { UI } from '@skedulo/protobuf-web'

// All destinations
const { nodes } = await apiClient.ui.nav.getDestinations()

// Only PLATFORM destinations
const { nodes } = await apiClient.ui.nav.getDestinations({
  destination: UI.CRUD.Destination.PLATFORM,
})

React Example

import { useApiClient } from '@skedulo/horizon-core'
import { useEffect, useState } from 'react'
import { UI } from '@skedulo/protobuf-web'

const NavRenderer = () => {
  const apiClient = useApiClient()
  const [nav, setNav] = useState(null)

  useEffect(() => {
    apiClient?.ui.nav.getBestNav('Main Nav').then(setNav)
  }, [apiClient])

  if (!nav) return null

  return (
    <nav>
      {nav.nodes.map((node) => {
        if (node.destination === UI.CRUD.Destination.NOOP) {
          return <span key={node.ref}>{node.label}</span>
        }
        const href =
          node.destination === UI.CRUD.Destination.PLATFORM
            ? `/platform/${node.ref}`
            : node.ref
        return (
          <a key={node.ref} href={href}>
            {node.label}
          </a>
        )
      })}
    </nav>
  )
}