REST API

REST API

The Fiber v3 control plane exposes JSON under /api/v1 for the Next.js UI and external callers. Agents do not use this API — they use the gRPC channel in Agent Protocol.

• Browser: session cookie. External callers: bearer api_token.
• Live run logs: SSE. Web terminal: WebSocket (not listed below).
• Mutating endpoints write an audit_log entry.
• Pagination: ?limit=&cursor= → { items, next_cursor }.
• Errors: { error: { code, message } }.
• Timestamps: RFC 3339 in UTC.

Paths below are relative to /api/v1.

Auth

Method	Path	Purpose
POST	/auth/login	Email + password, sets session
POST	/auth/logout	Clears session
GET	/auth/config	Whether OIDC is enabled (login page)
GET	/auth/oidc/start	Redirect to IdP
GET	/auth/oidc/callback	OIDC callback
GET	/me	Current user and role

Servers

Method	Path	Purpose
GET	/servers	List with status and last seen
POST	/servers	Create; returns enrollment token + install command
GET	/servers/:id	Detail
PATCH	/servers/:id	Rename, description, labels
DELETE	/servers/:id	Remove
POST	/servers/:id/enrollment-token	Re-issue one-time token
POST	/servers/:id/update	Offer connected agent a self-update (admin)
POST	/servers/:id/revoke	Revoke agent cert; force re-enroll
GET	/updates	Latest agent release and per-server status

Jobs

Method	Path	Purpose
GET	/jobs?server=:id	List, optional server filter
POST	/jobs	Create (version 1)
GET	/jobs/:id	Detail including current version
PATCH	/jobs/:id	Metadata/schedule/options; editing script_body creates a new version
DELETE	/jobs/:id	Delete
POST	/jobs/:id/enable	Enable scheduling
POST	/jobs/:id/disable	Disable scheduling
POST	/jobs/:id/run	Manual run now (RunNow to agent)
GET	/jobs/:id/versions	Version history
GET	/jobs/:id/versions/:n	Specific version’s script
POST	/jobs/:id/versions/:n/restore	Make an old version current (inserts a new version from it)

Runs and logs

Method	Path	Purpose
GET	/jobs/:id/runs	History (paginated)
GET	/runs/:id	Status, timing, exit code
GET	/runs/:id/logs	Full captured log for finished runs
GET	/runs/:id/logs/stream	SSE live log stream
POST	/runs/:id/cancel	Cancel (CancelRun)

Secrets, tokens, audit

Method	Path	Purpose
GET	/secrets	Names and scopes (never values)
POST	/secrets	Create; value encrypted at rest
DELETE	/secrets/:id	Delete
GET	/api-tokens	List caller’s tokens (no secrets)
POST	/api-tokens	Create; plaintext shown once
DELETE	/api-tokens/:id	Revoke
GET	/audit	Paginated, filterable

Job templates

Method	Path	Role	Notes
GET	/job-templates?category=	viewer	Built-ins sort first
GET	/job-templates/:id	viewer
POST	/job-templates	operator	Full body, or {from_job_id, name}
DELETE	/job-templates/:id	operator	403 builtin for shipped templates

Notification targets

Admin throughout (rows hold SMTP credentials and webhook URLs).

Method	Path	Notes
GET	/notification-targets	Secret config values come back as ********
POST	/notification-targets	kind: webhook, slack, or email
PATCH	/notification-targets/:id	******** keeps the stored value
POST	/notification-targets/:id/test	Real delivery; HTTP 200 either way, read delivered
DELETE	/notification-targets/:id

server_labels scopes to servers whose labels contain all given pairs; empty = whole fleet. on_statuses limits which run outcomes fire; empty = every non-success.

Connectors

Read: any authenticated role. Lifecycle: operator+. Config bytes: admin (read and write).

Method	Path	Role
GET	/connectors	viewer
GET	/connectors/:id	viewer
GET	/connectors/:id/resources	viewer
GET	/connectors/:id/operations?limit=	viewer
GET	/servers/:id/connectors	viewer
POST	/connectors/:id/actions	operator — {action, ref}: start, stop, restart, reload, enable, disable
GET	/connectors/:id/config?path=	admin
POST	/connectors/:id/config	admin — {path, content, base_checksum, dry_run}
GET	/connectors/:id/snapshots?path=&limit=	admin
POST	/connectors/:id/snapshots/:snapshotID/restore	admin

Mutating calls return {operation_id, status, message, steps}. Read status (succeeded, failed, invalid, unauthorized, unsupported, or transport offline / timeout) — a 200 with status: "invalid" means the change was refused. Transport failures: 503 agent_offline, 504 agent_timeout.

base_checksum on apply is the checksum from the read it was based on. Mismatch is invalid rather than clobbering. Pass empty to force.

Outside /api/v1

Path	Purpose
GET /healthz	Liveness + Postgres ping
GET /metrics	Prometheus (optionally bearer-gated)
GET /app/*	Proxied web UI
WS /api/servers/:id/terminal/ws	Web terminal (session cookie, admin/owner)

Full tables and request bodies: docs/api.md.