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,
  "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",
  "type": "manager",
  "delegation_type": "router",
  "delegation_memory_strategy": "summarization",
  "is_ai_employee": false,
  "using_nemo": false,
  "deletable": true,
  "model_provider": "openai",
  "model_name": "gpt-4.1",
  "llm_api_base": "<string>",
  "output_format": "markdown",
  "output_schema": {},
  "llm_credentials_key": "<string>",
  "llm_credentials_key_type": "xpander",
  "llm_credentials": {
    "name": "<string>",
    "value": "<string>",
    "description": "<string>"
  },
  "expected_output": "",
  "agno_settings": {
    "session_storage": true,
    "agent_memories": false,
    "agentic_culture": false,
    "user_memories": false,
    "agentic_memory": false,
    "session_summaries": false,
    "num_history_runs": 3,
    "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": true,
    "tool_calls_compression": {
      "enabled": true,
      "instructions": "",
      "threshold": 3
    }
  },
  "on_prem_event_streaming": true,
  "prompts_caching_enabled": false,
  "is_generalist": false
}
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)Example: "🎧" | "🚀" | "💼"
​
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
Note: Only effective if the template was exported with with_knowledge_bases: true

​
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",
    "icon": "🎧",
    "with_knowledge_bases": false
  }' \
  https://api.xpander.ai/v1/agents/template_import/{template_id}

​
Cross-Organization Import

# Organization B importing a template from Organization A
curl -X POST -H "x-api-key: ORG_B_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Assistant (Customized)",
    "description": "Imported from marketplace template",
    "icon": "💼"
  }' \
  https://api.xpander.ai/v1/agents/template_import/template-from-org-a

​
Example Response

{
  "id": "agent-new-001",
  "name": "My Support Agent",
  "description": "Customer support agent from template",
  "icon": "🎧",
  "status": "ACTIVE",
  "origin_template": "template-123",
  "organization_id": "your-org-456",
  "deployment_type": "serverless",
  "created_at": "2025-11-06T02:47:17.244054Z",
  "instructions": {
    "role": ["Customer support specialist"],
    "goal": ["Resolve customer issues efficiently"],
    "general": "Be helpful and professional"
  },
  "model_provider": "openai",
  "model_name": "gpt-4o",
  "framework": "agno",
  "knowledge_bases": [
    {
      "id": "kb-001",
      "name": "Product Documentation",
      "description": "Product guides and FAQs"
    }
  ],
  "attached_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

​
See Also

  • [Export Agent](/API reference/v1/agents/export-agent) - Create a template from an existing agent
  • Agent Import & Export Guide - Comprehensive guide to templates
  • [Update Agent](/API reference/v1/agents/update-agent) - Customize the imported agent
  • [Deploy Agent](/API reference/v1/agents/deploy-agent) - Deploy the imported agent
  • [List Agents](/API reference/v1/agents/list-agents) - View all agents in your organization

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
​
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
​
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.

Available options:
manager,
regular,
a2a,
curl
​
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:openai
Available options:
openai,
nim,
amazon_bedrock,
huggingFace,
friendlyAI,
anthropic,
gemini,
fireworks,
google_ai_studio,
helicone,
open_router,
nebius
​
model_name
string | null
default:gpt-4.1
​
llm_api_base
string | null
​
output_format
enum<string> | null
default:markdown
Available options:
text,
markdown,
json
​
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
​
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_generalist
boolean | null
default:false