paperclip-docs/docs/reference/api/instance-admin.md

paperclip_version

paperclip_version
v2026.720.0

Instance Admin API

A grab-bag of instance-scoped REST endpoints that don't fit neatly into the other API pages: general and experimental instance settings, on-demand database backups, the LLM reflection endpoints, environments (sandbox/runtime drivers), and execution-workspace lifecycle.

These surfaces are stable enough to call from your own tooling, but they are intentionally narrow — most operators reach them through the UI, the CLI, or via the paperclipai doctor command rather than by hand.

All routes are mounted under /api. Most require instance-admin or board authentication; per-route notes call out exceptions.

---

Instance settings

Endpoint	Purpose
GET /api/instance/settings/general	Read general instance settings (display name, defaults, etc.).
PATCH /api/instance/settings/general	Update general settings. Body is validated against patchInstanceGeneralSettingsSchema.
GET /api/instance/settings/experimental	Read the experimental-features block.
PATCH /api/instance/settings/experimental	Toggle experimental features. Body is validated against patchInstanceExperimentalSettingsSchema.
POST /api/instance/settings/experimental/issue-graph-liveness-auto-recovery/preview	Preview what the auto-recovery sweep would change without applying.
POST /api/instance/settings/experimental/issue-graph-liveness-auto-recovery/run	Run the auto-recovery sweep.

The experimental "issue-graph-liveness auto-recovery" routes are paired: preview produces a dry-run summary; run applies the same changes. Both share the issueGraphLivenessAutoRecoveryRequestSchema body shape.

The experimental-settings response and patch body include enableBuiltInAgents as a boolean. Set it to true before using the Built-in Agents API; while it is off, those routes return 404 Not Found.

---

Database backups

POST /api/instance/database-backups

Trigger a manual database backup. Returns a structured result that includes the backup directory, retention policy, and timing. Scheduled backups follow the same code path but are not exposed as a separate route.

Instance-admin only.

---

Claim first instance admin

POST /api/bootstrap/claim

On a brand-new private instance that requires login, this lets the first person to sign in promote themselves to instance_admin — no manual database seeding. The first caller to claim wins; everyone after them is locked out.

Availability. This route only exists when the instance runs with deploymentMode set to authenticated and deploymentExposure set to private. On any other configuration it returns 404 with Browser first-admin claim is not available.

Cloud-managed instances. If your instance is managed by a Paperclip control plane rather than run by you, you never meet this claim screen at all — the instance comes up ready to use. The control plane owns identity there, and the users it signs in are deliberately never given the instance_admin role, so GET /api/health skips the first-admin check entirely and always reports bootstrapStatus: "ready". Self-hosted instances are unaffected: if you run the server yourself, the claim flow behaves exactly as described here.

Authentication. The caller must be a signed-in browser session (a board actor whose session source is the browser). Other callers — agents, CLI tokens, unauthenticated requests — get 401 with Sign in from a browser session before claiming first admin.

Behaviour. If no instance_admin exists yet, the signed-in user is promoted to instance_admin. The claim is atomic — the table is locked so exactly one user can win. If the instance has already been claimed, the route returns 409 with Someone else has already claimed this instance.

The request takes no body. On success the response is:

{ "claimed": true, "userId": "<the promoted user's id>" }

---

LLM agent-configuration reflection

These endpoints exist so agents can introspect what server-side adapters and icons are available to them.

Endpoint	Purpose
GET /api/llms/agent-configuration.txt	Plain-text dump of available agent adapters and their declared shape.
GET /api/llms/agent-configuration/:adapterType.txt	Same, scoped to one adapter type.
GET /api/llms/agent-icons.txt	List of supported agent-icon names (AGENT_ICON_NAMES).

Access is limited to board callers and agents whose permissions include canCreateAgents — the routes return 403 otherwise.

---

Environments

Environments are the plugin-managed execution backends declared by environment-driver plugins (custom sandboxes, runners, etc.).

Endpoint	Purpose
GET /api/companies/:companyId/environments	List configured environments for the company.
GET /api/companies/:companyId/environments/capabilities	List the capabilities reported by available environment drivers.
POST /api/companies/:companyId/environments	Create an environment. Body validated against createEnvironmentSchema.
POST /api/companies/:companyId/environments/probe-config	Probe a candidate environment config without persisting. Body validated against probeEnvironmentConfigSchema.
GET /api/environments/:id	Read one environment.
PATCH /api/environments/:id	Update an environment. Body validated against updateEnvironmentSchema.
DELETE /api/environments/:id	Delete an environment.
POST /api/environments/:id/probe	Probe an existing environment (driver health check).
GET /api/environments/:id/leases	List active leases on the environment.
GET /api/environment-leases/:leaseId	Read a single lease.

---

Execution workspaces

Execution workspaces are the materialised working directories Paperclip creates for an issue run.

Endpoint	Purpose
GET /api/companies/:companyId/execution-workspaces	List execution workspaces for the company.
GET /api/execution-workspaces/:id	Read one workspace.
GET /api/execution-workspaces/:id/close-readiness	Whether the workspace is safe to close (no pending operations, no dirty state).
GET /api/execution-workspaces/:id/workspace-operations	List the operations recorded against the workspace.
PATCH /api/execution-workspaces/:id	Update a workspace. Body validated against updateExecutionWorkspaceSchema.
POST /api/execution-workspaces/:id/runtime-services/:action	Run a runtime-service control action against the workspace.
POST /api/execution-workspaces/:id/runtime-commands/:action	Run a runtime-command control action against the workspace. Both routes share the workspaceRuntimeControlTargetSchema body and the same handler.

---

Related

• Reference → Adapters API — adapter registry endpoints.
• Reference → Plugins API — plugin install and lifecycle.
• Reference → Deployment → Environment Variables — the env-vars these admin surfaces interact with.