API referenceEndpoints

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.

POST/v1/agent-templates/{role}/instantiate

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.

Authorization

bearerAuth
AuthorizationBearer <token>

Engine-issued API key or tenant-signed JWT.

In: header

Path Parameters

role*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/agent-templates/string/instantiate" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "executor_mode": "internal",  "status": "active",  "role_id": "string",  "role_edition": 0}