API referenceEndpoints

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.

GET/v1/agent-templates/{role}/editions/{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.

Authorization

bearerAuth
AuthorizationBearer <token>

Engine-issued API key or tenant-signed JWT.

In: header

Path Parameters

role*string
edition*integer
Range1 <= value

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/agent-templates/string/editions/1"
{  "role_id": "string",  "edition": 1,  "name": "string",  "description": "string",  "expertise": "string",  "setup_instructions": "string",  "requirements": [    {      "key": "string",      "kind": "answer",      "label": "string",      "prompt": "string",      "shared": true,      "tool": "string"    }  ],  "preferences": [    {      "key": "string",      "label": "string",      "kind": "text",      "options": [        "string"      ],      "max_length": 1    }  ],  "setup_required": true,  "blinq_id": "163ce100-8211-4522-93e1-e382b5984dbb",  "blinq_version": 1,  "presentation": {    "color": "string",    "avatar": "string",    "availability": "available"  },  "color": "string",  "avatar": "string",  "availability": "available",  "details": "string",  "capabilities": {    "accepts_messages": true,    "models": [      "string"    ],    "starts_on_hire": true,    "schedule_cron": "string",    "inbox_actions": [      "string"    ],    "reads_context": true,    "tools": [      "string"    ],    "limits": {      "max_model_calls": 0,      "max_input_tokens": 0,      "max_output_tokens": 0,      "max_cost_micros": 0    }  },  "executor_mode": "internal",  "core_workflow": [],  "jobs": []}

List agent templates

Requires an authenticated user JWT. Generated from the production route registered in `internal/features/agents/inbound/roles.go`. Returns shared Engine-owned template summaries across Engine applications under the existing tenant model. Built-in listings/presentation stay unchanged. An external Blinq appears only with an accepted current version and availability=available, carrying executor_mode=external and a setup_required boolean indicating whether the release needs a connected account. Hidden and pending-only Blinqs are absent. A promotion appends one immutable edition; rollback selects its existing edition. Shared content and appearance never expose private setup or work. No SaaS publication is needed.

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.