Get Agent

curl --request GET \
  --url https://api.xpander.ai/v1/agents/{agent_id} \
  --header 'x-api-key: <api-key>'

{
  "name": "<string>",
  "organization_id": "<string>",
  "webhook_url": "<string>",
  "created_by_details": {
    "id": "<string>",
    "name": "<string>",
    "email": "<string>"
  },
  "id": "<string>",
  "unique_name": "<string>",
  "origin_template": "<string>",
  "environment_id": "<string>",
  "deployment_type": "serverless",
  "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": [],
  "status": "ACTIVE",
  "knowledge_bases": [],
  "version": 1,
  "created_by": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "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"
  },
  "on_prem_event_streaming": true,
  "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>"
}

GET

agents

{agent_id}

Get Agent

curl --request GET \
  --url https://api.xpander.ai/v1/agents/{agent_id} \
  --header 'x-api-key: <api-key>'

{
  "name": "<string>",
  "organization_id": "<string>",
  "webhook_url": "<string>",
  "created_by_details": {
    "id": "<string>",
    "name": "<string>",
    "email": "<string>"
  },
  "id": "<string>",
  "unique_name": "<string>",
  "origin_template": "<string>",
  "environment_id": "<string>",
  "deployment_type": "serverless",
  "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": [],
  "status": "ACTIVE",
  "knowledge_bases": [],
  "version": 1,
  "created_by": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "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"
  },
  "on_prem_event_streaming": true,
  "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>"
}

Returns the complete agent object including its tools with full schemas, the tool graph with customized input/output schemas, structured output schema, webhook URL, LLM settings, and all configuration details. This is the single source of truth for an agent’s current state.

Path Parameters

agent_id

string

required

Unique identifier of the agent (UUID format)

Response

Identity & Status

string

Agent UUID

unique_name

string

Auto-generated URL-safe slug (e.g., emerald-emu). Assigned on creation.

name

string

Display name

description

string

Auto-generated on deploy from instructions. Describes what the agent does.

icon

string

Emoji icon (e.g., 🚀)

avatar

string

Avatar identifier (e.g., male-avatar)

status

string

ACTIVE (deployed) or INACTIVE (not yet deployed)

version

integer

Increments on each deploy

deletable

boolean

Whether the agent can be deleted via the API

organization_id

string

Owning organization UUID

created_by

string | null

UUID of the user who created the agent

created_by_details

object | null

Resolved creator details. null when created_by is empty or the user cannot be resolved — null-check before reading sub-fields.

Show Created By Details

string

User UUID

name

string

Display name — first + last name. Falls back to email, then id, when the name is missing. Not guaranteed to be a real first/last name.

string

User email

created_at

string

ISO 8601 timestamp

Instructions

instructions

object

System instructions that define the agent’s behavior. Divided into three sections.

Show Instructions Object

role

string[]

Array of role statements. The agent’s identity, rules, and domain knowledge.

goal

string[]

Array of goal statements. What the agent should accomplish.

general

string

Free-form general system prompt.

expected_output

string

Describes the desired output format in natural language (e.g., "Short answer, formatted in rich markdown text.").

Model Configuration

model_provider

string

LLM provider: openai, anthropic, bedrock, gemini, etc.

model_name

string

Model identifier (e.g., gpt-5.2, claude-sonnet-4-5-20250929)

llm_reasoning_effort

string

Reasoning effort level: low, medium, or high

llm_api_base

string | null

Custom LLM API base URL. null for default provider endpoints.

Structured Output

output_format

string

Response format: text, json, or markdown

output_schema

object | null

When output_format is json, this is a full JSON Schema that the agent’s output must conform to. Includes $schema, type, required, properties with types, descriptions, validations, and nested objects/arrays.

Show Example: Company Details Schema

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Registered or trading name of the company."
    },
    "industry": {
      "type": "string",
      "description": "Industry classification or sector."
    },
    "website": {
      "type": "string",
      "format": "uri",
      "description": "Company website URL."
    },
    "contact": {
      "type": "object",
      "properties": {
        "email": { "type": "string", "format": "email" },
        "phone": { "type": "string" }
      }
    },
    "status": {
      "enum": ["active", "inactive", "suspended", "closed"],
      "type": "string"
    }
  },
  "additionalProperties": false
}

Tools

tools

array

The fully-resolved tool definitions available to this agent. Each tool includes its operation ID, HTTP method, path, and complete request schemas (body_schema and parameters). These are the actual tool-calling interfaces the LLM sees at runtime.

Show Tool Object

string

Operation ID (e.g., TavilySearchServiceExecuteQueryAndReturnResults). This matches item_id in the graph.

name

string

Extended description of the tool’s purpose and workflow context.

raw_description

string

Original tool description from the toolkit source.

function_description

string

Description passed to the LLM as the function docstring.

method

string

HTTP method: get, post, put, delete, patch

path

string

Endpoint path (e.g., /operation/TavilySearchServiceExecuteQueryAndReturnResults/search)

body_schema

object

Flat map of body parameter definitions. Each key is a parameter name, value is its JSON Schema with type, description, default, enum, minimum, maximum, etc.

path_params

object

Path parameter definitions (often empty {})

query_params

object

Query parameter definitions (often empty {})

parameters

object

The structured function-calling schema sent to the LLM. Contains query_params, path_params, body_params, and headers objects.

Show Parameters Structure

body_params

object

properties map with each parameter’s type and description. required array lists mandatory fields.

headers

object

Includes toolcallreasoningtitle and toolcallreasoningdescription — metadata the LLM provides when calling the tool to explain its reasoning.

Tool Graph

graph

array

The agent’s tool graph — defines how tools are wired together, with optional custom schemas, descriptions, and routing targets. Graph items can override the default tool schemas to lock parameters, customize descriptions, or define expected output formats.

Show Graph Item

string

Graph node UUID

item_id

string

References the tool’s id in the tools array (operation ID)

name

string

Display name for this graph node (e.g., "Search Mintlify Documentation")

type

string

Node type: tool, mcp, or agent

sub_type

string | null

Sub-classification (if applicable)

targets

string[]

Array of graph node ids this tool can call next. Self-references allow looping. Empty array [] means terminal node.

is_first

boolean

Whether this is the entry-point tool in the graph

settings

object | null

Customization layer for this graph node. null if using defaults.

Show Graph Node Settings

description

string | null

Custom description override for this tool in this graph context

instructions

string | null

Additional instructions for the LLM when using this tool

use_cache

boolean

Whether to cache tool results for repeated calls

schemas

object | null

Custom input/output schema overrides

Show Schema Overrides

input

object

Custom JSON Schema for the tool input. Can include permanentValue on fields to lock a parameter to a fixed value (e.g., always search a specific subdomain).

output

object

Custom JSON Schema describing the expected output format from this tool.

hitl_options

object | null

Human-in-the-loop configuration (approval requirements)

a2a_options

object | null

Agent-to-agent delegation options

mcp_settings

object | null

MCP-specific settings when type is mcp

Attached Tools (Toolkit References)

attached_tools

array

References to which toolkits and specific operations are attached to this agent. This maps toolkit UUIDs to the operation IDs selected from each toolkit.

Show Attached Tool Entry

string

Toolkit UUID

operation_ids

string[]

Array of operation IDs from that toolkit that are enabled for this agent

Webhook & Entry Points

webhook_url

string

Auto-generated webhook endpoint for this agent. Accepts POST requests to trigger agent tasks. Includes agent_id and asynchronous query parameters.

See the Webhook documentation for payload format, authentication, and async/sync modes.

source_nodes

array

Entry points through which this agent can be invoked.

Show Source Node

string

Node UUID

type

string

Entry point type: assistant (chat widget), sdk (Python/JS SDK), or webhook

targets

array | null

Downstream graph targets (usually null)

metadata

object

Additional metadata for this entry point

Agent Framework Settings

framework

string

Agent framework (e.g., agno)

type

string

Agent type: manager, regular, a2a, curl, or orchestration. Agents with type orchestration are Workflows — visual multi-step pipelines.

deployment_type

string

Infrastructure: serverless or container

agno_settings

object

Framework-level configuration for the Agno runtime.

Show Agno Settings

session_storage

boolean

Enable session persistence across turns

agent_memories

boolean

Allow agent to store long-term memories

user_memories

boolean

Allow per-user memory storage

session_summaries

boolean

Auto-summarize sessions

num_history_runs

integer

Number of previous runs to include in context

tool_call_limit

integer

Max tool calls per run (0 = unlimited)

coordinate_mode

boolean

Enable multi-agent coordination

pii_detection_enabled

boolean

PII detection on inputs

pii_detection_mask

boolean

Mask detected PII

prompt_injection_detection_enabled

boolean

Detect prompt injection attacks

openai_moderation_enabled

boolean

OpenAI content moderation

openai_moderation_categories

string[] | null

Moderation categories to check (e.g., ["hate", "harassment", "sexual", "violence"])

reasoning_tools_enabled

boolean

Enable chain-of-thought reasoning tools

tool_calls_compression

object

Compress tool call history to save context window

Show Compression Settings

enabled

boolean

Compression active

threshold

integer

Compress after N tool calls

instructions

string

Custom compression instructions

Knowledge Bases

knowledge_bases

array

Array of knowledge base IDs attached to this agent. Empty [] if none attached.

Knowledge bases and tools are attached to agents through the xpander.ai dashboard or Python SDK — not via the REST API PATCH endpoint.

Other Fields

access_scope

string

personal or organizational

is_latest

boolean

Whether this is the latest version of the agent

has_pending_changes

boolean

Whether there are undeployed changes

deep_planning

boolean

Deep planning mode enabled

on_prem_event_streaming

boolean

Server-sent events for on-prem deployments

notification_settings

object

Webhook notifications on task success/error

task_level_strategies

object

Task retry, iteration, and rate-limit strategies

Example Request

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>"

Example Response

The response is the complete agent configuration. Below is a condensed example showing the key structures — a real response includes full tool schemas and may be 1000+ lines.

{
  "id": "<agent-id>",
  "unique_name": "emerald-emu",
  "name": "Product Specialist",
  "description": "Processes queries to provide comprehensive product information...",
  "icon": "🚀",
  "avatar": "male-avatar",
  "status": "ACTIVE",
  "version": 78,
  "organization_id": "<org-id>",
  "created_by": "<user-id>",
  "created_by_details": {
    "id": "<user-id>",
    "name": "Jane Doe",
    "email": "jane@acme.com"
  },
  "created_at": "2026-02-05T18:54:51.388334Z",
  "deployment_type": "serverless",
  "framework": "agno",
  "type": "manager",
  "deletable": true,

  "instructions": {
    "role": [
      "You are a product specialist assistant",
      "Search the knowledge base before answering product questions"
    ],
    "goal": [
      "Help customers understand product features",
      "Provide accurate, sourced answers"
    ],
    "general": "You are a support agent. Use tools to answer questions accurately."
  },
  "expected_output": "Short answer, formatted in rich markdown text.",

  "model_provider": "anthropic",
  "model_name": "claude-sonnet-4-5-20250929",
  "llm_reasoning_effort": "medium",
  "llm_api_base": null,

  "output_format": "json",
  "output_schema": {
    "type": "object",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "required": ["name"],
    "properties": {
      "name": {
        "type": "string",
        "minLength": 1,
        "description": "Company name."
      },
      "industry": {
        "type": "string",
        "description": "Industry sector."
      },
      "website": {
        "type": "string",
        "format": "uri"
      }
    },
    "additionalProperties": false
  },

  "tools": [
    {
      "id": "TavilySearchServiceExecuteQueryAndReturnResults",
      "name": "Executes a search query using Tavily AI...",
      "raw_description": "Executes a search query using Tavily AI...",
      "function_description": "Executes a search query using Tavily AI...",
      "method": "post",
      "path": "/operation/TavilySearchServiceExecuteQueryAndReturnResults/search",
      "path_params": {},
      "query_params": {},
      "body_schema": {
        "query": {
          "type": "string",
          "description": "The search query to execute.",
          "example": "who is Leo Messi?"
        },
        "max_results": {
          "type": "integer",
          "minimum": 0,
          "maximum": 20,
          "default": 5
        },
        "search_depth": {
          "type": "string",
          "enum": ["basic", "advanced"],
          "default": "basic"
        },
        "topic": {
          "type": "string",
          "enum": ["general", "news"],
          "default": "general"
        }
      },
      "parameters": {
        "type": "object",
        "properties": {
          "body_params": {
            "type": "object",
            "properties": {
              "query": { "type": "string", "description": "The search query." }
            },
            "required": ["query"]
          },
          "path_params": { "type": "object", "properties": {} },
          "query_params": { "type": "object", "properties": {} },
          "headers": {
            "type": "object",
            "properties": {
              "toolcallreasoningtitle": {
                "type": "string",
                "description": "Action title (max 5 words)"
              },
              "toolcallreasoningdescription": {
                "type": "string",
                "description": "One-sentence summary (max 100 chars)"
              }
            }
          }
        },
        "required": ["body_params", "path_params", "query_params", "headers"]
      }
    },
    {
      "id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent",
      "name": "Sends an email with HTML body content...",
      "method": "post",
      "path": "/operation/XpanderEmailServiceSendEmailWithHtmlOrTextContent/messaging/send_email",
      "body_schema": {
        "to": { "type": "array", "items": { "type": "string" } },
        "subject": { "type": "string" },
        "body_html": { "type": "string" }
      },
      "parameters": { "..." : "..." }
    }
  ],

  "graph": [
    {
      "id": "<graph-node-id>",
      "item_id": "TavilySearchServiceExecuteQueryAndReturnResults",
      "name": "Execute Search Query and Retrieve Results",
      "type": "tool",
      "sub_type": null,
      "targets": ["<self-id>"],
      "is_first": false,
      "settings": {
        "description": "Search the web for relevant results...",
        "instructions": null,
        "use_cache": true,
        "schemas": {
          "input": {
            "type": "object",
            "required": ["query_params", "path_params", "body_params"],
            "properties": {
              "body_params": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": { "type": "string", "description": "The search query." }
                }
              }
            }
          },
          "output": {
            "type": "object",
            "properties": {
              "query": { "type": "string" },
              "results": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "url": { "type": "string" },
                    "title": { "type": "string" },
                    "content": { "type": "string" },
                    "score": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      }
    },
    {
      "id": "<graph-node-id>",
      "item_id": "MintlifySearchEngineSearchDocsBySubdomainAndQuery",
      "name": "Search Mintlify Documentation by Subdomain and Query",
      "type": "tool",
      "targets": ["<self-id>"],
      "settings": {
        "description": "Search in docs.xpander.ai for documentation",
        "use_cache": true,
        "schemas": {
          "input": {
            "type": "object",
            "properties": {
              "body_params": {
                "properties": {
                  "subdomain": {
                    "type": "string",
                    "permanentValue": "docs.xpander.ai"
                  },
                  "query": { "type": "string" }
                }
              }
            }
          }
        }
      }
    },
    {
      "id": "<graph-node-id>",
      "item_id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent",
      "name": "Send Email",
      "type": "tool",
      "targets": [],
      "settings": null
    }
  ],

  "attached_tools": [
    {
      "id": "<toolkit-id-1>",
      "operation_ids": ["68259fd3ff1266b1d6022eef"]
    },
    {
      "id": "<toolkit-id-2>",
      "operation_ids": ["6910a209b1c2df0f90058ca8"]
    },
    {
      "id": "<toolkit-id-3>",
      "operation_ids": [
        "68230439d76e61ed7e92e4c3",
        "68230439d76e61ed7e92e4c2"
      ]
    }
  ],

  "webhook_url": "https://webhook.xpander.ai/?agent_id=<agent-id>&asynchronous=false",

  "source_nodes": [
    { "id": "<node-id>", "type": "assistant", "targets": null, "metadata": {} },
    { "id": "<node-id>", "type": "sdk", "targets": null, "metadata": {} },
    { "id": "<node-id>", "type": "webhook", "targets": null, "metadata": {} }
  ],

  "knowledge_bases": [],

  "agno_settings": {
    "session_storage": true,
    "agent_memories": false,
    "user_memories": false,
    "session_summaries": false,
    "num_history_runs": 20,
    "tool_call_limit": 0,
    "coordinate_mode": true,
    "pii_detection_enabled": false,
    "prompt_injection_detection_enabled": false,
    "openai_moderation_enabled": false,
    "reasoning_tools_enabled": false,
    "tool_calls_compression": {
      "enabled": false,
      "threshold": 3,
      "instructions": ""
    }
  },

  "access_scope": "organizational",
  "is_latest": true,
  "has_pending_changes": false,
  "deep_planning": false,
  "on_prem_event_streaming": true,
  "notification_settings": { "on_success": {}, "on_error": {} },
  "task_level_strategies": {
    "retry_strategy": null,
    "iterative_strategy": null,
    "stop_strategy": null,
    "max_runs_per_day": null
  }
}

Common Use Cases

Quick Status Check

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '{name, status, model: .model_name, provider: .model_provider, version, tools: (.tools | length)}'

{
  "name": "Product Specialist",
  "status": "ACTIVE",
  "model": "claude-sonnet-4-5-20250929",
  "provider": "anthropic",
  "version": 78,
  "tools": 4
}

List All Tool IDs and Paths

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.tools[] | {id, method, path}'

{"id": "TavilySearchServiceExecuteQueryAndReturnResults", "method": "post", "path": "/operation/.../search"}
{"id": "XpanderEmailServiceSendEmailWithHtmlOrTextContent", "method": "post", "path": "/operation/.../send_email"}
{"id": "MintlifySearchEngineSearchDocsBySubdomainAndQuery", "method": "post", "path": "/operation/.../mintlify_search"}
{"id": "TavilyDataExtractionExtractContentFromUrls", "method": "post", "path": "/operation/.../extract"}

Extract the Output Schema

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.output_schema'

Get the Webhook URL

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.webhook_url'

"https://webhook.xpander.ai/?agent_id=<agent-id>&asynchronous=false"

Use the webhook_url to trigger agent tasks from external systems without the SDK. See the Webhook documentation for payload format, authentication, and how to switch between sync and async modes.

Inspect Graph Wiring

See how tools are connected and which have custom schemas:

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.graph[] | {name, type, item_id, targets, has_custom_schema: (.settings.schemas != null)}'

Extract Tool Body Schema for a Specific Tool

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.tools[] | select(.id == "TavilySearchServiceExecuteQueryAndReturnResults") | .body_schema'

Check Attached Toolkit References

curl -s -X GET "https://api.xpander.ai/v1/agents/<agent-id>" \
  -H "x-api-key: <your-api-key>" | \
  jq '.attached_tools'

[
  { "id": "<toolkit-id>", "operation_ids": ["68259fd3ff1266b1d6022eef"] },
  { "id": "<toolkit-id>", "operation_ids": ["6910a209b1c2df0f90058ca8"] },
  { "id": "<toolkit-id>", "operation_ids": ["68230439d76e61ed7e92e4c3", "68230439d76e61ed7e92e4c2"] }
]

attached_tools maps toolkit UUIDs → operation IDs. To manage which tools are attached, use the xpander.ai dashboard or the Python SDK. The REST API PATCH endpoint does not support modifying attached_tools.

Authorizations

x-api-key

string

header

required

API Key for authentication

Path Parameters

agent_id

string

required

Response

Successful Response

name

string

required

organization_id

string

required

webhook_url

string

required

read-only

created_by_details

CreatedByDetails · object

Show child attributes

string | null

unique_name

string | null

origin_template

string | null

environment_id

string | null

deployment_type

enum<string> | null

default:serverless

Available options:

serverless,

container

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

AIAgentConnectivityDetailsA2A
AIAgentConnectivityDetailsCurl
Connectivity Details

Show child attributes

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

Show child attributes

attached_tools

Connector · object[] | null

Show child attributes

access_scope

enum<string> | null

default:personal

Available options:

personal,

organizational

instructions

AIAgentInstructions · object

Show child attributes

oas

Oas · object

graph

AIAgentGraphItem · object[] | null

Show child attributes

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

Show child attributes

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

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

Show child attributes

llm_extra_headers

Llm Extra Headers · object

Show child attributes

expected_output

string | null

default:""

agno_settings

AgnoSettings · object

Show child attributes

on_prem_event_streaming

boolean | null

default:true

is_supervised

boolean | null

default:false

orchestration_nodes

OrchestrationNode · object[] | null

Show child attributes

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.

Show child attributes

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.

Show child attributes

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

Create Agent

Update Agent

⌘I

Documentation Index

​Path Parameters

​Response

​Identity & Status

​Instructions

​Model Configuration

​Structured Output

​Tools

​Tool Graph

​Attached Tools (Toolkit References)

​Webhook & Entry Points

​Agent Framework Settings

​Knowledge Bases

​Other Fields

​Example Request

​Example Response

​Common Use Cases

​Quick Status Check

​List All Tool IDs and Paths

​Extract the Output Schema

​Get the Webhook URL

​Inspect Graph Wiring

​Extract Tool Body Schema for a Specific Tool

​Check Attached Toolkit References

Authorizations

Path Parameters

Response

Path Parameters

Response

Identity & Status

Instructions

Model Configuration

Structured Output

Tools

Tool Graph

Attached Tools (Toolkit References)

Webhook & Entry Points

Agent Framework Settings

Knowledge Bases

Other Fields

Example Request

Example Response

Common Use Cases

Quick Status Check

List All Tool IDs and Paths

Extract the Output Schema

Get the Webhook URL

Inspect Graph Wiring

Extract Tool Body Schema for a Specific Tool

Check Attached Toolkit References