Overview

The Page Agents API is a surface-agnostic proxy to the local Gizzi brain runtime for browser and page-agent workflows. It lets you start a goal-driven run, stream runtime events over SSE, stop an active run, and save runtime configuration. In Phase 1 the runtime target defaults to http://127.0.0.1:4096 and can be overridden with the ALLTERNIT_PAGE_AGENT_URL environment variable.

Base URL

Authentication

Page-agent routes are served through the gateway, so include a valid bearer token in the Authorization header. See Authentication for details.

Endpoints

Start a run

Creates a runtime browser session for the supplied goal. The gateway forwards the request to the configured page-agent runtime and returns the runtime session ID.

Request body

Example request

Example response

Stream events

Opens a server-sent event stream that proxies events from the page-agent runtime. Each upstream event is tagged with requestedSessionId so clients can correlate frames even when the upstream runtime does not include the session ID.

Example curl

Example event

Stop a run

Aborts the runtime session. The gateway forwards the abort request to the page-agent runtime.

Example response

Check status

Probes the page-agent runtime health and returns a lightweight status object. Phase 2 will add a persistent session store with richer status.

Example response

Save configuration

Phase 1 echoes the supplied configuration back as a validation/save stub. Future phases will persist the configuration on the server.

Example request

Example response

Error codes