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.
/v1/agent-templates/{role}/instantiateRequires 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 Engine-issued API key or tenant-signed JWT.
In: header
Path Parameters
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}Read an agent template edition
Requires an authenticated user JWT. Generated from the production route registered in `internal/features/agents/inbound/roles.go`. Reads an immutable Engine-owned edition with presentation. External editions include identity, presentation and a setup_required boolean derived from the declared tools. Internal workflow steps and setup questions are empty. Edition is a separate sequential number, not necessarily the Blinq version. Retained editions stay readable after a release change. Use the instantiated agent's template read for its saved edition. Applications cannot publish or replace template content.
List agents
Requires an authenticated tenant principal. Generated from the production route registered in `internal/features/agents/inbound/http.go`.