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

# Get Omni Agent

> Get your Omni agent, the built-in agent every user has, resolved from the API key you call with.

Returns the Omni agent of the user who owns the API key. Each user has one Omni; if yours does not exist yet, this call creates it. Repeated calls return the same agent.

Use the returned `id` with any `/v1/agents/{agent_id}` route, for example [Run Conversation Turn](/api-reference/v1/agents/conversations/run-turn) to talk to Omni or [Get Agent Tasks](/api-reference/v1/agents/get-agent-tasks) to read its history.

Call it with your **personal key**, so the Omni returned is yours. A key with no user attached has no Omni, and the call returns `400`. See [Authentication](/api-reference/rest-api#authentication) for the two kinds of key.

```bash theme={"dark"}
curl -X GET "https://api.xpander.ai/v1/agents/omni" \
  -H "x-api-key: YOUR_PERSONAL_API_KEY"
```

## Response

The same simplified agent view that [Get Agent](/api-reference/v1/agents/get-agent) returns.

**id** `string`

Omni's agent UUID. Pass it as `agent_id` to the other agent routes.

**name** `string`

Display name

**description** `string`

What the agent does

**status** `string`

`DRAFT`, `ACTIVE` (deployed) or `INACTIVE`

**model\_provider** `string`

LLM provider (e.g., `anthropic`)

**model\_name** `string`

LLM model (e.g., `claude-sonnet-5`)

**tools** `array`

The agent's attached skills, in the `AgentTool` shape described on [Get Agent](/api-reference/v1/agents/get-agent)

**created\_at** `string`

ISO 8601 creation timestamp

**created\_by** `string | null`

UUID of the user the Omni belongs to

## Errors

| Status | When |
| - | - |
| `400` | The API key has no user attached. Use a personal key. |
| `401` / `403` | The API key is missing or invalid. |
| `503` | Another call is creating your Omni right now. Retry the request. |


## OpenAPI

````yaml GET /v1/agents/omni
openapi: 3.1.0
info:
  title: xpander.ai API Service
  description: |2-

        The xpander.ai API Service provides a unified REST API for managing AI agents,
        executing tasks, managing knowledge bases, and integrating with external systems.
        
        Features:
        - Agent Management: Create, update, deploy, and delete AI agents
        - Task Execution: Invoke agents with support for sync, async, and streaming modes
        - Knowledge Bases: Manage knowledge bases and documents for RAG workflows
        - Tools: Discover, connect, and attach tools (connectors, custom functions, MCP servers, sub-agents, workflows) to agents and workflows
        - MCP Integration: Model Context Protocol support for standardized AI interactions
        
        Authentication: All endpoints require authentication via either an API key (`x-api-key`) or an OAuth2 JWT (`Authorization: Bearer <jwt>`).
        
  version: '0.001'
servers:
  - url: https://api.xpander.ai
security: []
paths:
  /v1/agents/omni:
    get:
      tags:
        - API v1
        - Agents
      summary: Get Omni Agent
      description: >-
        Return the Omni agent of the user the API key belongs to, creating it on
        first call. Omni is per-user: call it with a personal API key; a key
        with no user attached is rejected with 400.
      operationId: Get_Omni_Agent_v1_agents_omni_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimplifiedAIAgent'
              example:
                id: a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5
                name: Omni
                icon: 🚀
                status: ACTIVE
                organization_id: 0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e
                deployment_type: serverless
                model_provider: anthropic
                model_name: claude-sonnet-5
                type: manager
                created_at: '2026-07-28T20:55:54.042725Z'
        '400':
          description: The API key has no user attached; use a personal API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              example:
                detail: >-
                  This API key has no user attached, and Omni is a per-user
                  agent. Use a personal API key from the xpander.ai app.
        '503':
          description: Another request is creating the user's Omni; retry
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              example:
                detail: Omni provisioning in progress, please retry
      security:
        - APIKeyHeader: []
components:
  schemas:
    SimplifiedAIAgent:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: Agent id.
        name:
          type: string
          title: Name
          description: Agent name.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Agent description.
        icon:
          anyOf:
            - type: string
            - type: 'null'
          title: Icon
          description: Agent icon.
        type:
          anyOf:
            - $ref: '#/components/schemas/AgentType'
            - type: 'null'
          description: Agent type.
        status:
          anyOf:
            - $ref: '#/components/schemas/AgentStatus'
            - type: 'null'
          description: Agent status.
        model_provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Provider
          description: LLM provider.
        model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Model Name
          description: LLM model.
        framework:
          anyOf:
            - type: string
            - type: 'null'
          title: Framework
          description: >-
            Runtime: agno (built-in) or external-harness (Claude Code / Codex /
            OpenCode).
        deployment_type:
          anyOf:
            - $ref: '#/components/schemas/AIAgentDeploymentType'
            - type: 'null'
          description: serverless or container.
        harness_settings:
          anyOf:
            - $ref: '#/components/schemas/HarnessSettings'
            - type: 'null'
          description: >-
            External harness settings (default CLI, per-CLI models, permission
            mode, per-turn resources ceilings); absent for built-in agents.
        instructions:
          anyOf:
            - $ref: '#/components/schemas/AIAgentInstructions'
            - type: 'null'
          description: Agent instructions.
        knowledge_base_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Knowledge Base Ids
          description: Attached knowledge base ids.
          default: []
        source_node_types:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Source Node Types
          description: Trigger source types (sdk, webhook, slack, ...).
          default: []
        tools:
          items:
            $ref: '#/components/schemas/AgentTool'
          type: array
          title: Tools
          description: Tools attached to this agent.
          default: []
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: Creation timestamp.
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
          description: Creator user id.
        created_by_details:
          anyOf:
            - $ref: '#/components/schemas/CreatedByDetails'
            - type: 'null'
          description: Creator details.
      type: object
      required:
        - name
      title: SimplifiedAIAgent
      description: >-
        Lean agent view exposing tools as one simple list, hiding low-level
        graph/oas internals.
    AgentType:
      type: string
      enum:
        - manager
        - regular
        - a2a
        - curl
        - orchestration
      title: AgentType
      description: |-
        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.
    AgentStatus:
      type: string
      enum:
        - DRAFT
        - ACTIVE
        - INACTIVE
      title: AgentStatus
      description: |-
        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.
    AIAgentDeploymentType:
      type: string
      enum:
        - serverless
        - container
      title: AIAgentDeploymentType
    HarnessSettings:
      properties:
        permission_mode:
          anyOf:
            - $ref: '#/components/schemas/HarnessPermissionMode'
            - type: 'null'
          default: full
        max_concurrent_tasks:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 64
            - type: 'null'
          title: Max Concurrent Tasks
          default: 12
        workdir_gc_days:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Workdir Gc Days
          default: 14
          description: Days an idle working directory is kept.
        image_tag:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Tag
          description: >-
            Pinned build of the platform harness image; null means the current
            build.
        approval_hold_hours:
          anyOf:
            - type: integer
              minimum: 1
              maximum: 72
            - type: 'null'
          title: Approval Hold Hours
          default: 4
          description: Hours a turn waits for an approval before giving up.
        cli_auto_update:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Cli Auto Update
          default: true
          description: Platform-managed; always reads back true.
        default_cli:
          anyOf:
            - $ref: '#/components/schemas/HarnessCli'
            - type: 'null'
          description: CLI that runs the agent's turns. A new agent gets 'claude-code'.
        models:
          additionalProperties:
            type: string
          type: object
          title: Models
          default: {}
          description: >-
            One model per CLI, keyed by CLI name, e.g. {"claude-code":
            "claude-sonnet-5"}. A missing key means the platform default for
            that CLI.
        available_clis:
          items:
            $ref: '#/components/schemas/HarnessCli'
          type: array
          title: Available Clis
          default: []
          description: CLIs the agent's runtime reports as installed; read-only.
        runtime:
          anyOf:
            - $ref: '#/components/schemas/HarnessRuntime'
            - type: 'null'
          description: '''fleet'' for new agents; ''legacy'' keeps one pod per agent.'
        resources:
          anyOf:
            - $ref: '#/components/schemas/HarnessResources'
            - type: 'null'
      type: object
      title: HarnessSettings
      description: >-
        Runtime settings for an agent whose framework is 'external-harness';
        null for 'agno' agents.
    AIAgentInstructions:
      properties:
        role:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Role
          default: []
        goal:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Goal
          default: []
        general:
          anyOf:
            - type: string
            - type: 'null'
          title: General
          default: ''
      type: object
      title: AIAgentInstructions
    AgentTool:
      properties:
        id:
          type: string
          title: Id
          description: >-
            Stable handle for this attached tool. Pass it to DELETE to remove
            the tool.
        type:
          $ref: '#/components/schemas/AgentToolType'
          description: The kind of attached tool.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Human-readable tool name.
        connection_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Connection Id
          description: Connector connection id. Actions only.
        operation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation Id
          description: Operation catalog id. Actions only.
        operation_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Operation Name
          description: OpenAPI operationId. Actions only.
        use_mock:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Use Mock
          description: >-
            Operation serves AI-generated mock data instead of the real API.
            Actions only.
        custom_function_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Custom Function Id
          description: Custom function id. Custom functions only.
        mcp_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Id
          description: MCP registry id. MCP only.
        allowed_tools:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Allowed Tools
          description: Subset of MCP tools exposed. MCP only.
        mcp_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Url
          description: MCP server url. MCP only.
        mcp_auth_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Auth Type
          description: MCP auth type (api_key/oauth2/custom_headers/none). MCP only.
        mcp_registry_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Registry Id
          description: >-
            Registry entry id when this MCP is attached from the shared org
            registry (editing it affects every agent). Absent for inline MCPs.
            MCP only.
        mcp_transport:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Transport
          description: MCP transport (streamable-http/sse/stdio). MCP only.
        mcp_headers:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Mcp Headers
          description: >-
            Custom header names configured on the MCP (keys only; values are
            never returned). MCP only.
        mcp_client_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mcp Client Id
          description: OAuth2 client id for the MCP, if set. MCP only.
        mcp_additional_scopes:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Mcp Additional Scopes
          description: Extra OAuth2 scopes for the MCP. MCP only.
        mcp_share_user_token:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Mcp Share User Token
          description: >-
            Whether the authorized MCP token is shared across the org's other
            agents. MCP only.
        mcp_has_api_key:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Mcp Has Api Key
          description: >-
            Whether an API key is stored for the MCP (the value is never
            returned). MCP only.
        mcp_has_client_secret:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Mcp Has Client Secret
          description: >-
            Whether an OAuth2 client secret is stored for the MCP (the value is
            never returned). MCP only.
        target_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Target Id
          description: Referenced sub-agent or workflow id.
        skill_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Skill Name
          description: Skill name from the xpander skills catalog. Skills only.
      type: object
      required:
        - id
        - type
      title: AgentTool
      description: >-
        A tool attached to an agent — the simplified, unified view of one graph
        entry.
    CreatedByDetails:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        email:
          type: string
          title: Email
      type: object
      required:
        - id
        - name
        - email
      title: CreatedByDetails
    HarnessPermissionMode:
      type: string
      enum:
        - full
        - gated
      title: HarnessPermissionMode
      description: >-
        Permission mode for an external-harness agent's workspace commands.
        'full' runs them; 'gated' holds the ones matched by gated_commands for
        approval.
    HarnessCli:
      type: string
      enum:
        - claude-code
        - codex
        - opencode
        - xpander
      title: HarnessCli
      description: A CLI the harness container can run.
    HarnessRuntime:
      type: string
      enum:
        - fleet
        - legacy
      title: HarnessRuntime
      description: >-
        Where a harness agent's turns run: the shared executor fleet ('fleet',
        the default for new agents) or one always-on pod per agent ('legacy').
    HarnessResources:
      properties:
        memory_limit:
          anyOf:
            - type: string
            - type: 'null'
          title: Memory Limit
          description: >-
            Memory ceiling per turn, e.g. '24Gi', '512Mi' or a byte count (128Mi
            to 24Gi).
        memory_high:
          anyOf:
            - type: string
            - type: 'null'
          title: Memory High
          description: >-
            Throttle threshold below memory_limit; set together with
            memory_limit.
        cpu:
          anyOf:
            - type: number
              minimum: 0.1
              maximum: 8
            - type: 'null'
          title: Cpu
          description: CPU cores per turn (0.1 to 8; '500m' is accepted).
        pids:
          anyOf:
            - type: integer
              minimum: 64
              maximum: 8192
            - type: 'null'
          title: Pids
          description: Process limit per turn (64 to 8192).
        disk:
          anyOf:
            - type: string
            - type: 'null'
          title: Disk
          description: Disk ceiling per turn, e.g. '10Gi' (1Gi to 50Gi).
      additionalProperties: false
      type: object
      title: HarnessResources
      description: >-
        Per-turn sandbox ceilings for a harness agent on the fleet; every unset
        field keeps the runner default. A value past the platform caps is
        rejected with 422.
    AgentToolType:
      type: string
      enum:
        - action
        - custom_function
        - mcp
        - agent
        - workflow
        - skill
      title: AgentToolType
      description: Type of a tool attached to an agent.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: API Key for authentication
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.