api-compatibility.md

API compatibility

Scan history

The authenticated historical scan endpoints have two response shapes:

Endpoint	Response	Use
GET /api/v1/scans/{scanID}/summary	Scan metadata only	Scan history/detail headers and status displays. Does not read or return stored results.
GET /api/v1/scans/{scanID}	Full scan, including snapshot and changes	Existing API clients that need the complete historical result.
GET /api/v1/scans/{scanID}/hosts	Paginated effective-host summaries	Host inventory and per-address navigation.

The original full-response endpoint is retained for compatibility. New clients that only need scan metadata should use /summary, then request paginated results or host evidence separately when needed. This avoids loading large snapshots just to show scan status and timestamps.

Business units

v0.20.0 adds business units to every installation. The routes and response keys below are new or changed in that release; a single-unit installation gets them too, with its accounts in the default unit. Every route is in the route inventory, apiRoutes in internal/web/permissions.go.

Changed responses

Endpoint	Change
GET /api/v1/setup/status	platform_setup_available is true while the token from edgewatch admin platform-setup-token is unused and unexpired. Present once the first administrator exists.
GET /api/v1/auth/session	scope is platform for a platform administrator and unit otherwise; unit is the account's unit as {id, name, slug}, or null for a platform administrator; multi_unit reports whether more than one unit that is not deleted exists. role can be platform_admin.
POST /api/v1/auth/login, GET /api/v1/auth/session	totp_enrollment_required: true when an administrator or platform administrator without TOTP must enrol first; permissions then lists only account.self. The key is absent otherwise. It depends on the number of units.
GET /api/v1/status	live_updates is left out while more than one unit exists or the units cannot be counted; telemetry counts the unit's own rows, and only the default unit's status includes telemetry.database_bytes; and max_concurrent_scans, max_probe_count, and max_naabu_probe_count are the unit's own limits, which the scheduler enforces: the unit's cap where it has one and it is lower, otherwise the deployment's setting. A unit without caps reports the deployment's settings as before. The three keys are left out when the unit's capacity cannot be read.
permissions in the login, session, and status responses	Administrators also hold audit.read. A platform administrator holds units.manage, unit_accounts.manage, platform_audit.read, platform_notifications.manage, platform_status.read, and account.self.

New routes

POST /api/v1/setup/platform needs no session. It takes {token, username, password} and returns 201 with {configured, username}. It checks the browser origin (403 origin), answers a wrong, used, or expired token with the generic 400 setup_failed, and answers a client over the failure budget with 429 rate_limited and Retry-After.

GET /api/public/v1/dashboard/{slug} needs no session and returns the same projection as GET /api/public/v1/dashboard, for the unit with that slug. An unknown slug, a page that is not enabled, and a unit that is disabled or being deleted get 404 public_disabled. Each slug has its own rate limit and cache.

The audit views are read-only and return {entries, next_before}, newest first. Pass next_before as before for the next page; it is null on the last page. Both accept limit (1 to 200, default 50), action (an action prefix), since and until (RFC 3339), and actor (an account ID).

Endpoint	Permission	Use
GET /api/v1/audit	audit.read	The unit's audit, for its administrators. source_ip is left out of a platform administrator's actions.
GET /api/v1/platform/audit	platform_audit.read	The platform audit: records without a unit and every unit's account and platform records, each with its unit. unit limits it to one unit's records.

The platform console's routes serve only platform administrators; every other role gets 403. A body password is the caller's password, which the route confirms before it changes anything. An unknown or deleted unit, an account that is not the unit's, and a destination that is not the platform's get 404, except that GET /api/v1/platform/units/{id} returns a deleted unit's tombstone. DELETE /api/v1/platform/admins/{id}/activation was added after v0.20.3, when PATCH /api/v1/platform/admins/{id} began to answer a request to disable a pending platform administrator with 403 not_permitted instead of 200. POST /api/v1/platform/admins/{id}/activation and DELETE /api/v1/platform/admins/{id} were added after v0.20.5.

Endpoint	Permission	Request and response
GET /api/v1/platform/units	units.manage	Units that are not deleted, with their counts (accounts, administrators, jobs, and stored_scans) and slot use, and the deployment's limits. stored_scans counts every scan the unit's history holds, those of archived jobs included.
POST /api/v1/platform/units	units.manage	{name, slug}; the slug is derived from the name when empty. 201 with the unit.
GET /api/v1/platform/units/{id}	units.manage	One unit with the same counts, including a deleted unit's tombstone and a deleting unit's purge progress; a deleting unit's stored_scans counts the scans that are left to erase.
PATCH /api/v1/platform/units/{id}	units.manage	{revision, name, slug}, name and slug optional. A stale revision gets 409 with details.current.
DELETE /api/v1/platform/units/{id}	units.manage	{confirm_name, password} for a disabled unit that is not the default. The unit in the deleting state.
POST /api/v1/platform/units/{id}/disable	units.manage	{password, revision}, revision optional.
POST /api/v1/platform/units/{id}/enable	units.manage	{password, revision}, revision optional.
GET /api/v1/platform/units/{id}/capacity	units.manage	The unit's capacity, the deployment's limits, its slots, and the unit's revision when the capacity was read. The capacity.high_cost_ceiling is null when the unit inherits the deployment's (limits.max_probe_count_limit), 0 when no ceiling is granted, so a job approved for high-cost work keeps the unit's budgets, and otherwise the granted ceiling. A new unit starts at 0; up to v0.20.7 it started at the lower of the deployment's two probe budgets.
PATCH /api/v1/platform/units/{id}/capacity	units.manage	max_concurrent_scans, max_probe_count, max_naabu_probe_count, and high_cost_ceiling: an absent key keeps the setting, null inherits the deployment's, and a number sets it. A high_cost_ceiling of 0 takes the grant away; releases up to v0.20.7 refused it. revision, optional, is the one from the capacity the change is based on; once another change moved the unit on, the change gets 409 conflict and nothing is saved. Without it, the change applies to the settings current at the request.
GET /api/v1/platform/units/{id}/accounts	unit_accounts.manage	The unit's accounts as summaries without credentials.
POST /api/v1/platform/units/{id}/accounts	unit_accounts.manage	{username, display_name, role, password}; role may only be administrator. 201 with the one-time activation_token and activation_path.
POST /api/v1/platform/units/{id}/accounts/{uid}/password-reset	unit_accounts.manage	{password}, for an administrator of the unit. The one-time link, expires_at, and totp_enrolled.
DELETE /api/v1/platform/units/{id}/accounts/{uid}/sessions	unit_accounts.manage	{password}, for any account of the unit. 204.
GET /api/v1/platform/admins	unit_accounts.manage	The platform administrators.
POST /api/v1/platform/admins	unit_accounts.manage	{username, display_name, password}. 201 with the one-time link.
PATCH /api/v1/platform/admins/{id}	unit_accounts.manage	{enabled, revision, password}; never the caller's own account or the last enabled platform administrator. A pending platform administrator, which has not redeemed its invitation, is neither enabled nor disabled: both get 403 not_permitted.
DELETE /api/v1/platform/admins/{id}	unit_accounts.manage	{password}, for a pending platform administrator: the account and its activation links are removed, so its username can be invited again. 204. Any other platform administrator, enabled or disabled, the caller's own account included, gets 403 not_permitted.
POST /api/v1/platform/admins/{id}/activation	unit_accounts.manage	{password}, for a pending platform administrator, including one whose link expired or was revoked: a new one-time link, and every older link stops working. 200 with user, activation_token, activation_path, and expires_at. Any other platform administrator, the caller's own account included, gets 403 not_permitted.
DELETE /api/v1/platform/admins/{id}/activation	unit_accounts.manage	{password}, for a pending platform administrator: its unused activation link stops working, and the account stays pending. 204, or 404 no_active_activation when no usable link is left. Any other platform administrator, the caller's own account included, gets 403 not_permitted.
GET /api/v1/platform/notifications	platform_notifications.manage	The platform's destinations without URLs, each with its delivery health as a unit's destinations have it; their status, with the delivery_* totals of the platform's destinations only; and the platform's update_routing.
POST /api/v1/platform/notifications	platform_notifications.manage	{name, url, enabled, password}. 201 with the destination.
PATCH /api/v1/platform/notifications/{id}	platform_notifications.manage	{revision, name, url, enabled, password}; an absent url or enabled, or an empty name, keeps its value.
DELETE /api/v1/platform/notifications/{id}	platform_notifications.manage	{revision, password}. 204.
PUT /api/v1/platform/notifications/update-routing	platform_notifications.manage	{destinations, password}; platform destination IDs only, and an empty array selects none.
GET /api/v1/platform/status	platform_status.read	Units by state, account, job, and stored scan totals (accounts, jobs, stored_scans), platform administrator counts, the deployment's scan limits and slot use, and the version and update status.