Create and manage persistent voice agent configurations—identity, instructions, tools, voice, and knowledge base. Agents created here can be used with the Voice Agent API or called via phone through assigned phone numbers.

Agents

Create an agent

POST /v1/agents

Creates a new agent with the specified configuration.

Request body

Parameter	Type	Required	Description
`name`	string	Yes	Display name. Max 255 characters.
`instructions`	string	No	System prompt that controls agent behavior. Max 256,000 characters.
`tools`	array	No	Tools the agent can use. Max 200. Supports `function`, `web_search`, `x_search`, `file_search`, and `mcp`.
`voice`	object	No	Voice and VAD configuration. See Voice object.
`collection_ids`	string[]	No	Knowledge base collection IDs for file search. Max 10.

Voice object

Parameter	Type	Description
`voice_id`	string	Voice identifier (e.g., `"eve"`, `"ara"`, `"rex"`, `"sal"`, `"leo"`).
`vad_threshold`	number	Voice Activity Detection threshold. Range: 0.0–1.0. Lower values are more sensitive.
`vad_silence_duration_ms`	integer	Milliseconds of silence before a turn ends. Range: 0–10,000.

Example

Bash

curl -X POST https://api.x.ai/v1/agents \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order Support",
    "instructions": "You are a friendly order support agent. Help customers track their orders and process returns.",
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_order",
          "description": "Look up order status by order ID",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": { "type": "string", "description": "The order ID" }
            },
            "required": ["order_id"]
          }
        }
      },
      { "type": "web_search" }
    ],
    "voice": {
      "voice_id": "eve",
      "vad_threshold": 0.5,
      "vad_silence_duration_ms": 300
    }
  }'

Response

Returns the created agent.

JSON

{
  "agent": {
    "agent_id": "agent_abc123def456",
    "name": "Order Support",
    "instructions": "You are a friendly order support agent. Help customers track their orders and process returns.",
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_order",
          "description": "Look up order status by order ID",
          "parameters": {
            "type": "object",
            "properties": {
              "order_id": { "type": "string", "description": "The order ID" }
            },
            "required": ["order_id"]
          }
        }
      },
      { "type": "web_search" }
    ],
    "voice": {
      "voice_id": "eve",
      "vad_threshold": 0.5,
      "vad_silence_duration_ms": 300
    },
    "collection_ids": [],
    "created_at": "2025-07-15T10:30:00Z",
    "updated_at": "2025-07-15T10:30:00Z"
  }
}

List agents

GET /v1/agents

Returns a list of agents belonging to your team.

Parameter	Type	Required	Description
`limit`	integer	No	Max agents to return. Default: 100, max: 1,000.

Bash

curl https://api.x.ai/v1/agents?limit=10 \
  -H "Authorization: Bearer $XAI_API_KEY"

Get an agent

GET /v1/agents/{agent_id}

Retrieves a single agent by ID.

Bash

curl https://api.x.ai/v1/agents/agent_abc123def456 \
  -H "Authorization: Bearer $XAI_API_KEY"

Update an agent

PATCH /v1/agents/{agent_id}

Updates specific fields on an agent. Uses a field_mask to indicate which fields to modify; omitted fields are left unchanged.

Request body

Parameter	Type	Required	Description
`agent`	object	Yes	Agent object containing the updated fields.
`field_mask`	object	Yes	`{ "paths": ["field1", "field2"] }` — which fields to write.
`phone_number_id`	string	No	Assign a phone number to this agent. Pass `""` to unassign the current number.

Valid field_mask paths: name, instructions, tools, voice, collection_ids.

Phone assignment happens atomically with the field update. If the phone number is already assigned to another agent, the request returns 409 Conflict.

Examples

Update voice settings only:

Bash

curl -X PATCH https://api.x.ai/v1/agents/agent_abc123def456 \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "voice": { "voice_id": "leo", "vad_threshold": 0.7 }
    },
    "field_mask": { "paths": ["voice"] }
  }'

Update name and instructions:

Bash

curl -X PATCH https://api.x.ai/v1/agents/agent_abc123def456 \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "name": "Premium Support",
      "instructions": "You are a premium support agent for VIP customers."
    },
    "field_mask": { "paths": ["name", "instructions"] }
  }'

Clear instructions (set to null):

Bash

curl -X PATCH https://api.x.ai/v1/agents/agent_abc123def456 \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {},
    "field_mask": { "paths": ["instructions"] }
  }'

Assign a phone number to an agent:

Bash

curl -X PATCH https://api.x.ai/v1/agents/agent_abc123def456 \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "name": "Order Support"
    },
    "field_mask": { "paths": ["name"] },
    "phone_number_id": "phone_xyz789"
  }'

Unassign the phone number:

Bash

curl -X PATCH https://api.x.ai/v1/agents/agent_abc123def456 \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {},
    "field_mask": { "paths": ["name"] },
    "phone_number_id": ""
  }'

Delete an agent

DELETE /v1/agents/{agent_id}

Permanently deletes an agent.

Bash

curl -X DELETE https://api.x.ai/v1/agents/agent_abc123def456 \
  -H "Authorization: Bearer $XAI_API_KEY"

Returns 204 No Content on success.

Phone numbers

Phone numbers let agents make and receive calls. Numbers are purchased through the API and assigned to agents.

Purchase a phone number

POST /v1/phone-numbers

Purchases a US phone number in the specified area code.

Parameter	Type	Required	Description
`area_code`	string	Yes	3-digit US area code (e.g., `"415"`).
`name`	string	Yes	Display name. Max 255 characters.
`description`	string	No	Description. Max 1,000 characters.

Bash

curl -X POST https://api.x.ai/v1/phone-numbers \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "area_code": "415",
    "name": "Sales Line",
    "description": "Primary sales hotline"
  }'

Response

JSON

{
  "phone_number": {
    "phone_number_id": "phone_xyz789",
    "phone_number": "+14155551234",
    "name": "Sales Line",
    "description": "Primary sales hotline",
    "area_code": "415",
    "agent_id": null,
    "created_at": "2025-07-15T10:30:00Z",
    "updated_at": "2025-07-15T10:30:00Z"
  }
}

List phone numbers

GET /v1/phone-numbers

Parameter	Type	Required	Description
`limit`	integer	No	Max results. Default: 100, max: 1,000.

Bash

curl https://api.x.ai/v1/phone-numbers \
  -H "Authorization: Bearer $XAI_API_KEY"

Get a phone number

GET /v1/phone-numbers/{phone_number_id}

Bash

curl https://api.x.ai/v1/phone-numbers/phone_xyz789 \
  -H "Authorization: Bearer $XAI_API_KEY"

Update a phone number

PATCH /v1/phone-numbers/{phone_number_id}

Updates specific fields on a phone number. Like agent updates, uses a field_mask to specify which fields to write.

Request body

Parameter	Type	Required	Description
`name`	string	No	New display name. Max 255 characters.
`description`	string	No	New description. Max 1,000 characters.
`field_mask`	object	Yes	`{ "paths": ["field1", "field2"] }` — which fields to write.

Valid field_mask paths: name, description.

Bash

curl -X PATCH https://api.x.ai/v1/phone-numbers/phone_xyz789 \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Line",
    "description": "Customer support number",
    "field_mask": { "paths": ["name", "description"] }
  }'

Release a phone number

DELETE /v1/phone-numbers/{phone_number_id}

Permanently releases the number. This cannot be undone.

Bash

curl -X DELETE https://api.x.ai/v1/phone-numbers/phone_xyz789 \
  -H "Authorization: Bearer $XAI_API_KEY"

Returns 204 No Content on success.

Errors

Status	Meaning
`400`	Invalid request—missing required fields, validation error, or invalid `field_mask` path.
`401`	Authentication failed.
`403`	Permission denied—API key does not have agent access.
`404`	Agent or phone number not found.
`409`	Conflict—e.g., phone number already assigned to another agent.
`500`	Internal server error.

Limits

Resource	Limit
Agent name	255 characters
Agent instructions	256,000 characters
Tools per agent	200
Collection IDs per agent	10
Phone number name	255 characters
Phone number description	1,000 characters
List results (default / max)	100 / 1,000

Did you find this page helpful?

Inference API

Agents API

Agents

Create an agent

Request body

Voice object

Example

Response

List agents

Get an agent

Update an agent

Request body

Examples

Delete an agent

Phone numbers

Purchase a phone number

Response

List phone numbers

Get a phone number

Update a phone number

Request body

Release a phone number

Errors

Limits