Service Structure
By default tags are sorted by name and the endpoints inside a tag follow the specification. Administrators and editors can arrange a service by hand into folders, tags, endpoints and text pages. This page explains the Service structure editor.
Roles: Editing the structure is for
adminandeditor. Everyone who can see the service sees the arrangement in the left menu. Marking endpoints for MCP is foradminonly.
Opening the editor#
Hover over a service in the left menu and click Service structure at the right edge of the row, or open /docs/<service>/structure.
The tree#
The page shows the service as a tree. One level holds folders, tags and endpoints without a tag in a single mixed list. A folder can hold any of them again, up to max_tree_depth levels (8 by default).
A tag is a folder made from a tag of the specification. It has its own icon, holds any nodes, keeps its link to the tag name so that new versions keep filling it, and cannot be renamed or deleted.
Create things with the toolbar:
- New folder and New page open a dialog with a name and an optional parent (an autocomplete over the folders and tags). Without a parent the item goes to the first level.
- Every folder and tag row has buttons to create a folder or a page inside it.
Moving things#
- Drag a row by its handle. Drop on the top or bottom edge of a row to place the item before or after it, or on the middle of a folder or tag to move it inside.
- Use the buttons: up, down, Move up one level and Move. Move shows the item's path as breadcrumbs and an autocomplete of the folders and tags it may go to. It works with a keyboard and touch, and moves are announced to screen readers.
- Tick the checkboxes to move several items at once. Ticking a folder or tag covers everything inside it. The dialog lists the selection and offers only the targets the whole set can go into. The toggle Create a new folder creates a folder, with its own optional parent, and moves the selection into it.
- Rename or delete a folder from its row. What was inside it moves to the folder's place.
Save and Cancel are at the top. Cancel and leaving the page ask first when there are unsaved changes. Reset structure deletes the saved structure, folders included. If someone else saved in between, your save is refused.
The structure belongs to the service#
The arrangement applies to every version of the service and never gets in the way of publishing. Nodes are bound to names used by the specification (a tag name, an endpoint id):
- An endpoint you moved by hand stays where you put it, even if the specification gives it another tag later. An endpoint you did not move is only kept in a tag while the version still gives it that tag.
- New items in a version go to their natural place after your arranged items: a new endpoint into its tag, a new tag or an untagged endpoint to the end of the first level.
- Tags and endpoints a version lacks are kept in the structure, so older versions that still have them show them in the same place.
The structure is applied to the left menu, the tag and service pages, the Export Wizard tree and every export format.
Marking endpoints for MCP (administrators)#
Administrators see an extra group of buttons labelled MCP Try-It that controls which endpoints AI clients may call. See Try-It Through MCP.