rest api

Pre-Alpha. This page describes behavior that may change.

The REST API is the surface you use when you want plain HTTP and you do not want SSH or MCP in the path. It is the same web server as the Web UI and the same auth: log in with HTTP Basic, set Accept: application/json (or ?format=json), and every URL the browser uses returns structured data instead of HTML.

There is no separate "API server" with its own port, its own auth, or its own URL scheme. The web server does both. Content negotiation picks which surface you get.

Getting a JSON response

curl -k -u admin:password \
     https://localhost:8443/show/bgp/?format=json

The two ways to ask for JSON are equivalent.

Method	Effect
?format=json query parameter	Wins over the Accept header.
Accept: application/json	Used when text/html is not also present.

Default is HTML. The browser path and the API path are the same URLs through the same handlers.

Authentication

Browser sessions live in cookies. API clients use HTTP Basic. The user database is the same as the SSH server, so ze init and the user accounts you set up there work for the API too. Basic Auth requests do not create a session, which means automated scripts do not eat session slots.

URL structure

The URL pattern is verb-first and three-tier, the same scheme described in the Web UI page.

Tier	Pattern	Method	Description
View	/show/<yang-path>	GET	Read-only config tree view.
View	/monitor/<yang-path>	GET	Same as /show with auto-polling.
Config	/config/edit/<path>	GET	Editable config tree.
Config	/config/set/<path>	POST	Set a leaf value.
Config	/config/add/<path>	POST	Create a list entry.
Config	/config/delete/<path>	POST	Delete a leaf value.
Config	/config/add-form/	GET	Add new entry form (HTML).
Config	/config/changes	GET	Pending change count and commit bar state.
Config	/config/commit/	GET/POST	GET shows diff page, POST applies changes.
Config	/config/discard/	POST	Discard pending changes.
Config	/config/compare/	GET	Compare pending against committed.
Config	/config/diff	GET	Diff modal with content.
Config	/config/diff-close	GET	Closed diff modal (empty state).
Fragment	/fragment/detail	GET	Detail panel fragment.
SSE	/events	GET	SSE stream for real-time config change notifications.
Admin	/admin/<yang-path>	GET/POST	GET returns command tree (JSON), POST executes command.

The verb is in the URL. The HTTP method is the verb on that URL. POST bodies carry the value, the entry to add, or the parameters of an admin command.

A few useful one-liners

# All peers, JSON
curl -ks -u admin:pw https://localhost:8443/show/bgp/peer/?format=json

# Detail for one peer
curl -ks -u admin:pw https://localhost:8443/show/bgp/peer/upstream/?format=json

# Set a leaf value
curl -ks -u admin:pw -X POST \
     -d 'value=180' \
     'https://localhost:8443/config/set/bgp/peer/upstream/timer/hold-time'

# Commit
curl -ks -u admin:pw -X POST 'https://localhost:8443/config/commit/'

The diff before commit is GET /config/compare/. The current draft state is GET /config/changes.

Admin command tree

The /admin/ tree is available via REST with JSON content negotiation. GET with ?format=json returns the command tree structure; POST executes a command and returns the result as JSON with command, output, and error fields.

Group	Subcommands
peer	list, show, summary, capabilities, statistics, add, remove, teardown, clear-soft, flush
route	update, borr, eorr, raw
cache	list, retain, release, expire, forward
system	commit, subscribe, unsubscribe, events

# List admin command groups
curl -ks -u admin:pw 'https://localhost:8443/admin/?format=json'

# Execute a peer teardown
curl -ks -u admin:pw -X POST 'https://localhost:8443/admin/peer/192.168.1.1/teardown?format=json'

Looking Glass API

The Looking Glass exposes a separate, read-only Birdwatcher-compatible API at /api/looking-glass/. That is a different surface (different port, no auth, designed for public exposure) and it is documented on the Looking Glass page. Use the looking glass API for public route lookup and Alice-LG integration; use the web URLs above for everything authenticated.

See also

• Web UI for the same URLs in a browser.
• MCP if you want a typed-tool surface for an AI assistant rather than raw HTTP.
• CLI for the SSH-based equivalent.

Adapted from main/docs/features/api-commands.md, main/docs/features/web-interface.md, and main/docs/guide/web-interface.md.