Prompt Templates

The Prompt Templates API lets you create, list, update, retrieve, and delete prompt templates. Prompt templates are namespace-scoped resources that can be retrieved and rendered via the Twinit MCP Server using prompts/list and prompts/get.

Note: The nsfilter query parameter is mandatory for every request. It sets the caller's namespace context (AIService sets the request context namespaces to [nsfilter]) and is automatically applied for scoping results and operations.

Using prompt templates with agents: A prompt template can be assigned to an agent by setting the agent's _promptTemplate field to the template's _userType. The template acts as the agent's instruction and is parameterized at runtime when the agent runs. See the Agents API for how to set _promptTemplate on create and update.

List Prompt Templates

Endpoint

GET /aisvc/api/v1/prompttemplates

Query parameters

Parameter	Type	Description	Required
nsfilter	String	Namespace context for the request.	Required
_offset	Integer	Number of results to skip (must be a non-negative integer).	Optional
_pageSize	Integer	Page size (must be a non-negative integer).	Optional
_name	String	Exact name match .	Optional
_userType	String	Exact userType match .	Optional
query	String	Wildcard search over name/description/template.	Optional

Response codes

Code	Description
200	Success
400	Bad Request
404	Not Found

Response example

{  "_offset": 0,  "_pageSize": 1,  "_total": 1,  "_list": [    {      "_id": "d8a53325-dbb5-4a2d-a655-ef5fa74591d3",      "_name": "Platform_Universal_Template",      "_userType": "platform_resource_universal_tmpl",      "_description": "Reusable: detect the platform service from the request, call the right read tool with the given criteria, and answer grounded + in the requested format.",      "_namespaces": ["{{namespace}}"],      "_template": "You are a platform assistant. Answer the user's request: \"{{question}}\".\n\nSTEP 1 — Use the {{resourceType}} service. Choose the specific read tool within it (e.g. getFiles, getProjects, getWorkflows, getNamedUserItems, getPermissions, getUsageMetrics) that best answers the request.\n\nSTEP 2 — Build the call from the criteria. The following is plain text describing the filters/ids/names/statuses the user wants; map it into the chosen tool's parameters. If it is empty, call the tool with no filters or sensible defaults.\nCriteria: {{criteria}}\n\nSTEP 3 — Ground the answer. Use ONLY the tool's results. Never invent ids, names, counts, statuses or fields. Cite the resource _id(s) you used and stay within the active namespace. If the tool returns nothing, say so and suggest how to refine the criteria.\n\nSTEP 4 — Format to match the request. If the user asked for JSON (or named specific fields/structure), return ONLY valid JSON in exactly that shape. Otherwise, return a concise plain-text summary of the results.",      "_arguments": [        { "_name": "question", "_description": "The user's full request in their own words.", "_required": true },        { "_name": "resourceType", "_description": "The platform service to query — pick the single best match for the user's request (the user will NOT name it). Allowed values and what each covers: IafAISvc — AI resources: agents, tools, teams, prompt templates, knowledge bases, conversations, MCP tools/filters, external MCP server configs, LLM models & providers. IafProj — projects and their models, scripts, user configs, file containers and users. IafFileSvc — files and file versions: metadata, download/preview URLs, upload metadata. IafFileContainer — file containers (folders) and the file items inside a project's containers. IafItemSvc — NamedUserItems & NamedUserCollections, related items/relationships, telemetry readings & aggregations, schema definitions. IafWorkflowSvc — workflow definitions, workflows, runs, run status, tasks, schedules and triggers. IafDataSource — data orchestrators, components, runs, run logs, run status and schedules. IafGraphicsSvc — BIM model graphics data, markups and layer lists. IafPassSvc — users, current user/principal info, workspaces, user groups, permissions, permission profiles, applications, organizations, namespaces and secrets. IafPermission — permissions across Item, File, Passport, Datasource, Graphics, ObjectModel and AI services. IafObjectModelAPISvc — Object Model API config definitions and OMAPI requests/logs. IafNotification — notification groups, senders, subscriptions, devices, templates, triggers and history. IafUsageMetrics — usage & storage metrics (counts/sizes) per namespace, application or workspace. IafScripts — scripts and script versions. IafUserConfig — user configs and versions. IafUserGroup — user groups, members and invites. IafWorkspace — workspaces, their resources, users and user groups. IafApplication — applications and their developer/owner user groups.", "_required": true },        { "_name": "criteria", "_description": "All filter criteria in plain text (ids, names, _userTypes, statuses, date ranges, etc.) to use when calling the tool. May be empty.", "_required": false }      ],      "_metadata": {        "_createdAt": 1738100000000,        "_updatedAt": 1738100000000,        "_createdById": "user-123",        "_updatedById": "user-123"      },      "_irn": "aisvc:prompttemplate:d8a53325-dbb5-4a2d-a655-ef5fa74591d3"    }  ]}

Create Prompt Templates

Endpoint

POST /aisvc/api/v1/prompttemplates

Query parameters

Parameter	Type	Description	Required
nsfilter	String	Namespace context for the call	Required

Body parameters

Request body must be a JSON array of prompt template objects.

Parameter	Type	Description	Required
_namespaces	Array of String	Must be a non-empty array. Every value must equal the nsfilter namespace (because request context is [nsfilter]).	Required
_name	String	Display name. Trimmed. Max 64 chars. Must match ^[a-zA-Z0-9_-]{1,64}$.	Required
_userType	String	Prompt identifier. Trimmed. Max 50 chars. Must match ^\\w+$ (letters/digits/underscore only).	Required
_description	String	Optional description. If provided: trimmed, max 1024 chars. Whitespace-only is treated as missing.	Optional
_template	String	Template text. Trimmed and must be non-empty. Supports placeholders like {{name}}.	Required
_arguments	Array of Object	Optional argument metadata list.	Optional

_arguments[] items:

Field	Type	Description	Required
_name	String	Required. Trimmed. Must match ^[a-zA-Z][a-zA-Z0-9_]{0,63}$.	Required
_description	String	Optional. If provided: trimmed. Whitespace-only is treated as missing.	Optional
_required	Boolean	Optional. If omitted, it is stored as null (treated as not required).	Optional

Request example (with arguments)

[  {    "_name": "Platform_Universal_Template",    "_userType": "platform_resource_universal_tmpl",    "_description": "Reusable: detect the platform service from the request, call the right read tool with the given criteria, and answer grounded + in the requested format.",    "_namespaces": ["{{namespace}}"],    "_template": "You are a platform assistant. Answer the user's request: \"{{question}}\".\n\nSTEP 1 — Use the {{resourceType}} service. Choose the specific read tool within it (e.g. getFiles, getProjects, getWorkflows, getNamedUserItems, getPermissions, getUsageMetrics) that best answers the request.\n\nSTEP 2 — Build the call from the criteria. The following is plain text describing the filters/ids/names/statuses the user wants; map it into the chosen tool's parameters. If it is empty, call the tool with no filters or sensible defaults.\nCriteria: {{criteria}}\n\nSTEP 3 — Ground the answer. Use ONLY the tool's results. Never invent ids, names, counts, statuses or fields. Cite the resource _id(s) you used and stay within the active namespace. If the tool returns nothing, say so and suggest how to refine the criteria.\n\nSTEP 4 — Format to match the request. If the user asked for JSON (or named specific fields/structure), return ONLY valid JSON in exactly that shape. Otherwise, return a concise plain-text summary of the results.",    "_arguments": [      { "_name": "question", "_description": "The user's full request in their own words.", "_required": true },      { "_name": "resourceType", "_description": "The platform service to query — pick the single best match for the user's request (the user will NOT name it). Allowed values and what each covers: IafAISvc — AI resources: agents, tools, teams, prompt templates, knowledge bases, conversations, MCP tools/filters, external MCP server configs, LLM models & providers. IafProj — projects and their models, scripts, user configs, file containers and users. IafFileSvc — files and file versions: metadata, download/preview URLs, upload metadata. IafFileContainer — file containers (folders) and the file items inside a project's containers. IafItemSvc — NamedUserItems & NamedUserCollections, related items/relationships, telemetry readings & aggregations, schema definitions. IafWorkflowSvc — workflow definitions, workflows, runs, run status, tasks, schedules and triggers. IafDataSource — data orchestrators, components, runs, run logs, run status and schedules. IafGraphicsSvc — BIM model graphics data, markups and layer lists. IafPassSvc — users, current user/principal info, workspaces, user groups, permissions, permission profiles, applications, organizations, namespaces and secrets. IafPermission — permissions across Item, File, Passport, Datasource, Graphics, ObjectModel and AI services. IafObjectModelAPISvc — Object Model API config definitions and OMAPI requests/logs. IafNotification — notification groups, senders, subscriptions, devices, templates, triggers and history. IafUsageMetrics — usage & storage metrics (counts/sizes) per namespace, application or workspace. IafScripts — scripts and script versions. IafUserConfig — user configs and versions. IafUserGroup — user groups, members and invites. IafWorkspace — workspaces, their resources, users and user groups. IafApplication — applications and their developer/owner user groups.", "_required": true },      { "_name": "criteria", "_description": "All filter criteria in plain text (ids, names, _userTypes, statuses, date ranges, etc.) to use when calling the tool. May be empty.", "_required": false }    ]  }]

Request example (without arguments)

[  {    "_name": "Platform_Universal_Template",    "_userType": "platform_resource_universal_tmpl",    "_namespaces": ["{{namespace}}"],    "_template": "You are a platform assistant. Detect the right platform service from the request, call the appropriate read tool, ground your answer only in the tool's results, and respond in the format the user asked for. Available services: IafAISvc, IafProj, IafFileSvc, IafItemSvc, IafWorkflowSvc, IafPassSvc, IafUsageMetrics."  }]

Response codes

Code	Description
201	Success
400	Bad Request
404	Not Found

Response example

{  "_offset": 0,  "_pageSize": 1,  "_total": 1,  "_list": [    {      "_id": "d8a53325-dbb5-4a2d-a655-ef5fa74591d3",      "_name": "Platform_Universal_Template",      "_userType": "platform_resource_universal_tmpl",      "_description": "Reusable: detect the platform service from the request, call the right read tool with the given criteria, and answer grounded + in the requested format.",      "_namespaces": ["{{namespace}}"],      "_template": "You are a platform assistant. Answer the user's request: \"{{question}}\".\n\nSTEP 1 — Use the {{resourceType}} service. Choose the specific read tool within it (e.g. getFiles, getProjects, getWorkflows, getNamedUserItems, getPermissions, getUsageMetrics) that best answers the request.\n\nSTEP 2 — Build the call from the criteria. The following is plain text describing the filters/ids/names/statuses the user wants; map it into the chosen tool's parameters. If it is empty, call the tool with no filters or sensible defaults.\nCriteria: {{criteria}}\n\nSTEP 3 — Ground the answer. Use ONLY the tool's results. Never invent ids, names, counts, statuses or fields. Cite the resource _id(s) you used and stay within the active namespace. If the tool returns nothing, say so and suggest how to refine the criteria.\n\nSTEP 4 — Format to match the request. If the user asked for JSON (or named specific fields/structure), return ONLY valid JSON in exactly that shape. Otherwise, return a concise plain-text summary of the results.",      "_arguments": [        { "_name": "question", "_description": "The user's full request in their own words.", "_required": true },        { "_name": "resourceType", "_description": "The platform service to query — pick the single best match for the user's request (the user will NOT name it). Allowed values and what each covers: IafAISvc — AI resources: agents, tools, teams, prompt templates, knowledge bases, conversations, MCP tools/filters, external MCP server configs, LLM models & providers. IafProj — projects and their models, scripts, user configs, file containers and users. IafFileSvc — files and file versions: metadata, download/preview URLs, upload metadata. IafFileContainer — file containers (folders) and the file items inside a project's containers. IafItemSvc — NamedUserItems & NamedUserCollections, related items/relationships, telemetry readings & aggregations, schema definitions. IafWorkflowSvc — workflow definitions, workflows, runs, run status, tasks, schedules and triggers. IafDataSource — data orchestrators, components, runs, run logs, run status and schedules. IafGraphicsSvc — BIM model graphics data, markups and layer lists. IafPassSvc — users, current user/principal info, workspaces, user groups, permissions, permission profiles, applications, organizations, namespaces and secrets. IafPermission — permissions across Item, File, Passport, Datasource, Graphics, ObjectModel and AI services. IafObjectModelAPISvc — Object Model API config definitions and OMAPI requests/logs. IafNotification — notification groups, senders, subscriptions, devices, templates, triggers and history. IafUsageMetrics — usage & storage metrics (counts/sizes) per namespace, application or workspace. IafScripts — scripts and script versions. IafUserConfig — user configs and versions. IafUserGroup — user groups, members and invites. IafWorkspace — workspaces, their resources, users and user groups. IafApplication — applications and their developer/owner user groups.", "_required": true },        { "_name": "criteria", "_description": "All filter criteria in plain text (ids, names, _userTypes, statuses, date ranges, etc.) to use when calling the tool. May be empty.", "_required": false }      ],      "_metadata": {        "_createdAt": 1738100000000,        "_updatedAt": 1738100000000,        "_createdById": "user-123",        "_updatedById": "user-123"      },      "_irn": "aisvc:prompttemplate:d8a53325-dbb5-4a2d-a655-ef5fa74591d3"    }  ]}

Get Prompt Template by ID

Endpoint

GET /aisvc/api/v1/prompttemplates/{id}

Path parameters

Parameter	Type	Description	Required
id	UUID	Prompt template identifier.	Required

Query parameters

Parameter	Type	Description	Required
nsfilter	String	Namespace context for the call	Required

Response codes

Code	Description
200	Success
400	Bad Request
404	Not Found

Update Prompt Template

Endpoint

PUT /aisvc/api/v1/prompttemplates/{id}

Path parameters

Parameter	Type	Description	Required
id	UUID	Prompt template identifier.	Required

Query parameters

Parameter	Type	Description	Required
nsfilter	String	Namespace context for the call	Required

Body parameters

Parameter	Type	Description	Required
_namespaces	Array of String	Required by validation. Must be within nsfilter context (so effectively ["<nsfilter>"]).	Required
_name	String	Trimmed. Max 64 chars. Must match ^[a-zA-Z0-9_-]{1,64}$.	Required
_userType	String	Trimmed. Max 50 chars. Must match ^\\w+$.	Required
_description	String	Optional. Trimmed. Max 1024 chars. Whitespace-only treated as missing.	Optional
_template	String	Trimmed and non-empty.	Required
_arguments	Array of Object	Optional. See _arguments format above.	Optional

Request example

{  "_name": "Platform_Universal_Template_Updated",  "_userType": "platform_resource_universal_tmpl_updated",  "_description": "Updated: detect the platform service from the request, call the right read tool with the given criteria, and answer grounded + in the requested format.",  "_namespaces": ["{{namespace}}"],  "_template": "You are a platform assistant. Answer the user's request: \"{{question}}\".\n\nSTEP 1 — Use the {{resourceType}} service. Choose the specific read tool within it (e.g. getFiles, getProjects, getWorkflows, getNamedUserItems, getPermissions, getUsageMetrics) that best answers the request.\n\nSTEP 2 — Build the call from the criteria. The following is plain text describing the filters/ids/names/statuses the user wants; map it into the chosen tool's parameters. If it is empty, call the tool with no filters or sensible defaults.\nCriteria: {{criteria}}\n\nSTEP 3 — Ground the answer. Use ONLY the tool's results. Never invent ids, names, counts, statuses or fields. Cite the resource _id(s) you used and stay within the active namespace. If the tool returns nothing, say so and suggest how to refine the criteria.\n\nSTEP 4 — Format to match the request. If the user asked for JSON (or named specific fields/structure), return ONLY valid JSON in exactly that shape. Otherwise, return a concise plain-text summary of the results.",  "_arguments": [    { "_name": "question", "_description": "The user's full request in their own words.", "_required": true },    { "_name": "resourceType", "_description": "The platform service to query — pick the single best match for the user's request (the user will NOT name it). Allowed values and what each covers: IafAISvc — AI resources: agents, tools, teams, prompt templates, knowledge bases, conversations, MCP tools/filters, external MCP server configs, LLM models & providers. IafProj — projects and their models, scripts, user configs, file containers and users. IafFileSvc — files and file versions: metadata, download/preview URLs, upload metadata. IafFileContainer — file containers (folders) and the file items inside a project's containers. IafItemSvc — NamedUserItems & NamedUserCollections, related items/relationships, telemetry readings & aggregations, schema definitions. IafWorkflowSvc — workflow definitions, workflows, runs, run status, tasks, schedules and triggers. IafDataSource — data orchestrators, components, runs, run logs, run status and schedules. IafGraphicsSvc — BIM model graphics data, markups and layer lists. IafPassSvc — users, current user/principal info, workspaces, user groups, permissions, permission profiles, applications, organizations, namespaces and secrets. IafPermission — permissions across Item, File, Passport, Datasource, Graphics, ObjectModel and AI services. IafObjectModelAPISvc — Object Model API config definitions and OMAPI requests/logs. IafNotification — notification groups, senders, subscriptions, devices, templates, triggers and history. IafUsageMetrics — usage & storage metrics (counts/sizes) per namespace, application or workspace. IafScripts — scripts and script versions. IafUserConfig — user configs and versions. IafUserGroup — user groups, members and invites. IafWorkspace — workspaces, their resources, users and user groups. IafApplication — applications and their developer/owner user groups.", "_required": true },    { "_name": "criteria", "_description": "All filter criteria in plain text (ids, names, _userTypes, statuses, date ranges, etc.) to use when calling the tool. May be empty.", "_required": false }  ]}

Response codes

Code	Description
200	Success
400	Bad Request
404	Not Found

Response example

{  "_id": "d8a53325-dbb5-4a2d-a655-ef5fa74591d3",  "_name": "Platform_Universal_Template_Updated",  "_userType": "platform_resource_universal_tmpl_updated",  "_description": "Updated: detect the platform service from the request, call the right read tool with the given criteria, and answer grounded + in the requested format.",  "_namespaces": ["{{namespace}}"],  "_template": "You are a platform assistant. Answer the user's request: \"{{question}}\".\n\nSTEP 1 — Use the {{resourceType}} service. Choose the specific read tool within it (e.g. getFiles, getProjects, getWorkflows, getNamedUserItems, getPermissions, getUsageMetrics) that best answers the request.\n\nSTEP 2 — Build the call from the criteria. The following is plain text describing the filters/ids/names/statuses the user wants; map it into the chosen tool's parameters. If it is empty, call the tool with no filters or sensible defaults.\nCriteria: {{criteria}}\n\nSTEP 3 — Ground the answer. Use ONLY the tool's results. Never invent ids, names, counts, statuses or fields. Cite the resource _id(s) you used and stay within the active namespace. If the tool returns nothing, say so and suggest how to refine the criteria.\n\nSTEP 4 — Format to match the request. If the user asked for JSON (or named specific fields/structure), return ONLY valid JSON in exactly that shape. Otherwise, return a concise plain-text summary of the results.",  "_arguments": [    { "_name": "question", "_description": "The user's full request in their own words.", "_required": true },    { "_name": "resourceType", "_description": "The platform service to query — pick the single best match for the user's request (the user will NOT name it). Allowed values and what each covers: IafAISvc — AI resources: agents, tools, teams, prompt templates, knowledge bases, conversations, MCP tools/filters, external MCP server configs, LLM models & providers. IafProj — projects and their models, scripts, user configs, file containers and users. IafFileSvc — files and file versions: metadata, download/preview URLs, upload metadata. IafFileContainer — file containers (folders) and the file items inside a project's containers. IafItemSvc — NamedUserItems & NamedUserCollections, related items/relationships, telemetry readings & aggregations, schema definitions. IafWorkflowSvc — workflow definitions, workflows, runs, run status, tasks, schedules and triggers. IafDataSource — data orchestrators, components, runs, run logs, run status and schedules. IafGraphicsSvc — BIM model graphics data, markups and layer lists. IafPassSvc — users, current user/principal info, workspaces, user groups, permissions, permission profiles, applications, organizations, namespaces and secrets. IafPermission — permissions across Item, File, Passport, Datasource, Graphics, ObjectModel and AI services. IafObjectModelAPISvc — Object Model API config definitions and OMAPI requests/logs. IafNotification — notification groups, senders, subscriptions, devices, templates, triggers and history. IafUsageMetrics — usage & storage metrics (counts/sizes) per namespace, application or workspace. IafScripts — scripts and script versions. IafUserConfig — user configs and versions. IafUserGroup — user groups, members and invites. IafWorkspace — workspaces, their resources, users and user groups. IafApplication — applications and their developer/owner user groups.", "_required": true },    { "_name": "criteria", "_description": "All filter criteria in plain text (ids, names, _userTypes, statuses, date ranges, etc.) to use when calling the tool. May be empty.", "_required": false }  ],  "_metadata": {    "_createdAt": 1738100000000,    "_updatedAt": 1738200000000,    "_createdById": "user-123",    "_updatedById": "user-456"  },  "_irn": "aisvc:prompttemplate:d8a53325-dbb5-4a2d-a655-ef5fa74591d3"}

Delete Prompt Template

Endpoint

DELETE /aisvc/api/v1/prompttemplates/{id}

Path parameters

Parameter	Type	Description	Required
id	UUID	Prompt template identifier.	Required

Query parameters

Parameter	Type	Description	Required
nsfilter	String	Namespace context for the call	Required

Response codes

Code	Description
204	No Content
400	Bad Request
404	Not Found

Response body

// empty response body