API reference
Portrait is API-first. The web UI is a client of the same public REST API, with no privileged back door. Anything the UI does, your own scripts and coding agents can do too.
This page is a placeholder. The API is still changing shape ahead of the public beta. A generated reference and a machine-readable schema will replace this page once the surface is stable. What follows is the design intent, written to be usable by both people and the agents that will build against it.
Shape
- One versioned REST API, rooted at
/api/v1/. No legacy API and no private side-channel alongside it. - JSON request and response bodies. Resource-oriented paths, standard HTTP verbs and status codes.
- An OpenAPI 3.1 document at
/api/v1/openapi.json. TheportraitctlCLI ships a client generated from it. - Cursor-paginated list endpoints. Filtering uses the same query language the web UI
and profiles use (
hostname:web-*,status:active,tag:workstation, and so on).
Authentication
- Bearer token in the
Authorizationheader. Tokens are issued to a user or to a service identity. - Every call is authorised against the caller's roles and access groups, scoped exactly as it is in the UI. A token can never exceed the permissions of the identity behind it.
Mutations return activities
Anything that changes fleet state - an install, a script run, a reboot, a profile edit that triggers work - returns an activity (or an activity group, for fan-out across many hosts). Poll the activity for status, output and completion; nothing is fire-and-forget. See Everything is an activity.
Until this is published
How Portrait works describes the request flow end to end, including a worked example of an admin running a script through the API and the agent picking it up on its next exchange.