API referenceEndpoints

List agents

Requires an authenticated tenant principal. Generated from the production route registered in `internal/features/agents/inbound/http.go`.

GET/v1/agents

Requires an authenticated tenant principal. Generated from the production route registered in internal/features/agents/inbound/http.go.

Authorization

bearerAuth
AuthorizationBearer <token>

Engine-issued API key or tenant-signed JWT.

In: header

Query Parameters

include_hidden?boolean

Also list the agents the engine made for scheduled tasks (hidden: true). Off by default. Grants no visibility the caller does not already have; GET /v1/agents/{id} never needs it.

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/agents"
{  "items": [    {      "executor_mode": "internal",      "status": "active"    }  ]}

Instantiate or reopen a personal agent

Requires an authenticated user JWT. Generated from the production route registered in `internal/features/agents/inbound/roles.go`. Installs or reopens the same personal agent, even across concurrent retries and newer editions. An external install requires a valid device time_zone. For a connected-tool release, omit name and tool_connections to save the pinned install with status=setup_required and no schedule or activation run. Finish with PATCH /v1/agents/{id} or uninstall with DELETE /v1/agents/{id}. Clients can also provide a valid name and tool_connections at install time to start immediately. Releases that need no setup start immediately. First activation commits the active status, private schedule, pinned first run/task and audit records together. Failure rolls back that activation. The activation trigger is the hire UUID. Reopening retains the saved timezone, edition, model and status, and does not create a second first run. An active hire missing a schedule or activation can be repaired from its original metadata under current owner and hosting checks. A disabled incomplete hire or unavailable original metadata prevents repair. A busy hire returns a retryable conflict. Built-in templates retain their existing personal blueprint adoption and readiness rules. Installation and activation make no model call.

Create agent

Requires an authenticated tenant principal. Generated from the production route registered in `internal/features/agents/inbound/http.go`.