Skip to main content
POST
/
v1
/
agents
/
template_import
/
{template_id}
Import Agent
curl --request POST \
  --url https://api.xpander.ai/v1/agents/template_import/{template_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "icon": "<string>",
  "with_knowledge_bases": true
}
'
{
  "name": "<string>",
  "organization_id": "<string>",
  "webhook_url": "<string>",
  "id": "<string>",
  "unique_name": "<string>",
  "origin_template": "<string>",
  "delegation_end_strategy": "return-to-start",
  "environment_id": "<string>",
  "sub_agents_continuous_thread": true,
  "deployment_type": "serverless",
  "created_by_prompt": "<string>",
  "prompts": [],
  "is_latest": false,
  "has_pending_changes": false,
  "deep_planning": false,
  "enforce_deep_planning": false,
  "connectivity_details": {},
  "framework": "agno",
  "description": "",
  "tools": [],
  "icon": "🚀",
  "avatar": "male-avatar",
  "source_nodes": [],
  "attached_tools": [],
  "access_scope": "personal",
  "instructions": {
    "role": [],
    "goal": [],
    "general": ""
  },
  "oas": {},
  "graph": [],
  "llm_settings": [],
  "status": "ACTIVE",
  "knowledge_bases": [],
  "version": 1,
  "created_by": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "delegation_type": "router",
  "delegation_memory_strategy": "summarization",
  "is_ai_employee": false,
  "using_nemo": false,
  "deletable": true,
  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-6",
  "llm_reasoning_effort": "medium",
  "llm_api_base": "<string>",
  "output_format": "markdown",
  "voice_id": "<string>",
  "output_schema": {},
  "llm_credentials_key": "<string>",
  "llm_credentials_key_type": "xpander",
  "llm_credentials": {
    "name": "<string>",
    "value": "<string>",
    "description": "<string>"
  },
  "llm_extra_headers": {},
  "expected_output": "",
  "agno_settings": {
    "session_storage": true,
    "learning": false,
    "agent_memories": false,
    "agentic_culture": false,
    "user_memories": false,
    "agentic_memory": false,
    "session_summaries": false,
    "num_history_runs": 10,
    "max_tool_calls_from_history": 0,
    "tool_call_limit": 0,
    "coordinate_mode": true,
    "pii_detection_enabled": false,
    "pii_detection_mask": true,
    "prompt_injection_detection_enabled": false,
    "openai_moderation_enabled": false,
    "reasoning_tools_enabled": false,
    "tool_calls_compression": {
      "enabled": false,
      "instructions": "",
      "threshold": 3
    },
    "max_plan_retries": 15,
    "plan_retry_strategy": "tiered",
    "memory_strategy": "disabled"
  },
  "on_prem_event_streaming": true,
  "prompts_caching_enabled": false,
  "is_supervised": false,
  "orchestration_nodes": [],
  "notification_settings": {},
  "task_level_strategies": {
    "retry_strategy": {
      "enabled": false,
      "max_retries": 3
    },
    "iterative_strategy": {
      "enabled": false,
      "max_iterations": 3,
      "end_condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "stop_strategy": {
      "enabled": false,
      "stop_on_failure": true,
      "stop_on_condition": {
        "term": "<string>",
        "group_id": "<string>",
        "path": "<string>",
        "value": null
      }
    },
    "max_runs_per_day": 123,
    "agentic_context_enabled": false,
    "duplication_prevention": {
      "selectors": [
        "<string>"
      ],
      "enabled": false,
      "ttl_minutes": 10
    }
  },
  "use_oidc_pre_auth": false,
  "pre_auth_audiences": [],
  "use_oidc_pre_auth_token_for_llm": false,
  "oidc_pre_auth_token_llm_audience": "<string>",
  "oidc_pre_auth_token_mcp_audience": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt

Use this file to discover all available pages before exploring further.

Create a new agent instance from a template. The template can be from your organization or shared from another organization. All agent configuration, tools, sub-agents, and optionally knowledge bases will be replicated into your organization.

​
Path Parameters

​
template_id
string
required
Unique identifier of the template to import (UUID format)

​
Request Body

​
name
string
required
Display name for the new agent instance
​
description
string
Description of the agent instance (optional - can customize the template description)
​
icon
string
Emoji icon for the agent (optional - defaults to template icon)
​
with_knowledge_bases
boolean
default:true
Controls whether to import knowledge bases from the template
  • true: Imports all knowledge bases with their documents and files (if included in template)
  • false: Imports only agent configuration without knowledge bases

​
Response

Returns a complete AIAgent object:
​
id
string
Unique identifier for the created agent (UUID)
​
name
string
Display name of the agent
​
description
string
Agent description
​
icon
string
Emoji icon representing the agent
​
status
string
Current deployment status: ACTIVE or INACTIVE
​
origin_template
string
UUID of the template this agent was imported from
​
deployment_type
string
Deployment infrastructure: serverless or container
​
organization_id
string
UUID of your organization
​
instructions
object
System instructions configuration inherited from template
​
model_provider
string
AI model provider (e.g., openai)
​
model_name
string
Specific model version (e.g., gpt-4o, gpt-4.1)
​
framework
string
Agent framework used (e.g., agno)
​
knowledge_bases
array
Array of imported knowledge bases (if with_knowledge_bases: true)
​
created_at
string
ISO 8601 timestamp of when the agent was created

​
Example Requests

​
Basic Import

curl -X POST -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Support Agent",
    "description": "Customer support agent from template",
    "icon": "🎧",
    "with_knowledge_bases": true
  }' \
  https://api.xpander.ai/v1/agents/template_import/<template-id>

​
Import Without Knowledge Bases

curl -X POST -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent Framework",
    "description": "Will add custom knowledge bases later",
    "with_knowledge_bases": false
  }' \
  https://api.xpander.ai/v1/agents/template_import/<template-id>

​
Example Response

{
  "id": "<agent-id>",
  "name": "My Support Agent",
  "description": "Customer support agent from template",
  "icon": "🎧",
  "status": "ACTIVE",
  "origin_template": "<template-id>",
  "organization_id": "<org-id>",
  "deployment_type": "serverless",
  "created_at": "2026-02-07T10:30:00.000000Z",
  "instructions": {
    "role": ["Customer support specialist"],
    "goal": ["Resolve customer issues efficiently"],
    "general": "Be helpful and professional"
  },
  "model_provider": "openai",
  "model_name": "gpt-4.1",
  "framework": "agno",
  "knowledge_bases": [
    {
      "id": "<kb-id>",
      "name": "Product Documentation",
      "description": "Product guides and FAQs"
    }
  ],
  "tools": [],
  "graph": []
}

​
Import Behavior

When importing a template:
  1. New Agent Created: A completely independent agent instance is created in your organization
  2. Configuration Copied: All agent settings, instructions, and behavior are replicated
  3. Sub-Agents Recreated: Complete agent hierarchy is maintained with new instances
  4. Knowledge Bases: Documents are copied to your organization (if included and with_knowledge_bases: true)
  5. Tools & Connectors: Tool configurations are preserved - you’ll need to provide credentials
  6. Independence: Changes to the imported agent won’t affect the source agent or template

​
Notes

  • Cross-Organization Support: Templates can be imported from any organization - share the template ID
  • Customization: You can modify the agent name, description, and icon during import
  • Tool Setup: After import, configure credentials for any tools that require authentication
  • Knowledge Bases: If the template was exported without knowledge bases, with_knowledge_bases: true has no effect
  • Origin Tracking: The origin_template field tracks which template was used for import

​
Next Steps

After importing an agent:
  1. Update agent configuration using Update Agent if needed
  2. Configure tool credentials if the agent uses external tools
  3. Deploy the agent using Deploy Agent
  4. Test the agent with sample tasks

​
See Also

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
template_id
string
required

Body

application/json
​
name
string
required
​
description
string | null
​
icon
string | null
​
with_knowledge_bases
boolean | null
default:true

Response

Successful Response

​
name
string
required
​
organization_id
string
required
​
webhook_url
string
required
read-only
​
id
string | null
​
unique_name
string | null
​
origin_template
string | null
​
delegation_end_strategy
enum<string> | null
default:return-to-start

Enumeration of the agent delegation end strategies.

Attributes: ReturnToStart: when last agent is finished and about to announce "finish" it will summarize and return to the first agent. FinishWithLast: finish at the last agent.

Available options:
return-to-start,
finish-with-last
​
environment_id
string | null
​
sub_agents_continuous_thread
boolean | null
default:true
​
deployment_type
enum<string> | null
default:serverless
Available options:
serverless,
container
​
created_by_prompt
string | null
​
prompts
string[] | null
​
is_latest
boolean | null
default:false
​
has_pending_changes
boolean | null
default:false
​
deep_planning
boolean | null
default:false
​
enforce_deep_planning
boolean | null
default:false
​
connectivity_details
AIAgentConnectivityDetailsA2A · object
​
framework
string | null
default:agno
​
description
string | null
default:""
​
tools
any[] | null
​
icon
string | null
default:🚀
​
avatar
string | null
default:male-avatar
​
source_nodes
AIAgentSourceNode · object[] | null
​
attached_tools
Connector · object[] | null
​
access_scope
enum<string> | null
default:personal
Available options:
personal,
organizational
​
instructions
AIAgentInstructions · object
​
oas
Oas · object
​
graph
AIAgentGraphItem · object[] | null
​
llm_settings
AIAgentGraphItemLLMSettings · object[] | null
​
status
enum<string> | null
default:ACTIVE

Enumeration of possible agent statuses.

Attributes: DRAFT: Agent is in a draft state. ACTIVE: Agent is active and operational. INACTIVE: Agent is inactive and not operational.

Available options:
DRAFT,
ACTIVE,
INACTIVE
​
knowledge_bases
AgentKnowledgeBase · object[] | null
​
version
integer | null
default:1
​
created_by
string | null
​
created_at
string<date-time> | null
​
type
enum<string> | null

Enumeration of the agent types.

Attributes: Manager: marks the agent as a Managing agent. Regular: marks the agent as a regular agent. A2A: marks the agent as an external agent used via A2A protocol. Curl: marks the agent as an external agent used via a CURL. Orchestration: marks the agent as an Orchestration object.

Available options:
manager,
regular,
a2a,
curl,
orchestration
​
delegation_type
enum<string> | null
default:router

Enumeration of the agent delegation types.

Attributes: Router: Marks the agent as a router agent - xpanderAI's LLM will decide which sub-agent to trigger. Sequence: Marks the agent as a sequence agent - sub-agents will delegate to other sub-agents.

Available options:
router,
sequence
​
delegation_memory_strategy
enum<string> | null
default:summarization

Enumeration of the agent delegation memory strategies.

Attributes: Full: The memory object will be passed completely between agents. Summarization: Between each sub-agent delegation, a summarization will occur, and a new thread will be created for each agent. OriginalInput: the sub agent will get the initial task with a fresh memory thread

Available options:
full,
summarization,
original-input
​
is_ai_employee
boolean | null
default:false
​
using_nemo
boolean | null
default:false
​
deletable
boolean | null
default:true
​
model_provider
enum<string> | null
default:anthropic
Available options:
openai,
nim,
amazon_bedrock,
azure_ai_foundary,
huggingFace,
friendlyAI,
anthropic,
gemini,
fireworks,
google_ai_studio,
helicone,
bytedance,
tzafon_lightcone,
open_router,
nebius,
cloudflare_ai_gw
​
model_name
string | null
default:claude-sonnet-4-6
​
llm_reasoning_effort
enum<string> | null
default:medium
Available options:
low,
medium,
high,
xhigh
​
llm_api_base
string | null
​
output_format
enum<string> | null
default:markdown
Available options:
text,
markdown,
json,
voice
​
voice_id
string | null
​
output_schema
Output Schema · object
​
llm_credentials_key
string | null
​
llm_credentials_key_type
enum<string> | null
default:xpander
Available options:
xpander,
custom
​
llm_credentials
LLMCredentials · object
​
llm_extra_headers
Llm Extra Headers · object
​
expected_output
string | null
default:""
​
agno_settings
AgnoSettings · object
​
on_prem_event_streaming
boolean | null
default:true
​
prompts_caching_enabled
boolean | null
default:false
​
is_supervised
boolean | null
default:false
​
orchestration_nodes
OrchestrationNode · object[] | null
​
notification_settings
NotificationSettings · object

Configuration for event-based notifications.

Attributes: on_success: Notifications to send when an operation succeeds. Maps notification types to a list of notification configurations. on_error: Notifications to send when an operation fails. Maps notification types to a list of notification configurations.

​
task_level_strategies
TaskLevelStrategies · object

Configuration object for task-level execution strategies.

This model groups optional strategy configurations that control how a task is executed and managed over time, including retries, iterative execution, stopping conditions, and daily run limits.

Attributes: retry_strategy: Optional retry policy configuration that defines how the task should behave when execution fails (e.g., max attempts, backoff rules).

iterative_strategy:
    Optional iterative execution configuration for tasks that may run in
    repeated cycles/steps until completion or a stop condition is met.

stop_strategy:
    Optional stopping policy configuration that defines when the task
    should stop running (e.g., timeout, max iterations, success criteria).

max_runs_per_day:
    Optional limit on how many times the task is allowed to run within a
    24-hour period. If not set, no explicit daily limit is enforced.

agentic_context_enabled:
    if agentic memory is enabled and accesible to the executor.
​
use_oidc_pre_auth
boolean | null
default:false
​
pre_auth_audiences
string[] | null
​
use_oidc_pre_auth_token_for_llm
boolean | null
default:false
​
oidc_pre_auth_token_llm_audience
string | null
​
oidc_pre_auth_token_mcp_audience
string | null