Create Agent

curl --request POST \
  --url https://api.magpipe.ai/functions/v1/create-agent \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "<string>",
  "greeting": "<string>",
  "system_prompt": "<string>",
  "voice_id": "<string>",
  "llm_model": "<string>",
  "language": "<string>",
  "agent_type": "<string>",
  "organization_name": "<string>",
  "owner_name": "<string>",
  "agent_role": "<string>",
  "transfer_phone_number": "<string>",
  "is_active": true,
  "temperature": 123,
  "functions": {},
  "dynamic_variables": [
    {}
  ]
}
'

import requests

url = "https://api.magpipe.ai/functions/v1/create-agent"

payload = {
    "name": "<string>",
    "greeting": "<string>",
    "system_prompt": "<string>",
    "voice_id": "<string>",
    "llm_model": "<string>",
    "language": "<string>",
    "agent_type": "<string>",
    "organization_name": "<string>",
    "owner_name": "<string>",
    "agent_role": "<string>",
    "transfer_phone_number": "<string>",
    "is_active": True,
    "temperature": 123,
    "functions": {},
    "dynamic_variables": [{}]
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    name: '<string>',
    greeting: '<string>',
    system_prompt: '<string>',
    voice_id: '<string>',
    llm_model: '<string>',
    language: '<string>',
    agent_type: '<string>',
    organization_name: '<string>',
    owner_name: '<string>',
    agent_role: '<string>',
    transfer_phone_number: '<string>',
    is_active: true,
    temperature: 123,
    functions: {},
    dynamic_variables: [{}]
  })
};

fetch('https://api.magpipe.ai/functions/v1/create-agent', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.magpipe.ai/functions/v1/create-agent",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'greeting' => '<string>',
    'system_prompt' => '<string>',
    'voice_id' => '<string>',
    'llm_model' => '<string>',
    'language' => '<string>',
    'agent_type' => '<string>',
    'organization_name' => '<string>',
    'owner_name' => '<string>',
    'agent_role' => '<string>',
    'transfer_phone_number' => '<string>',
    'is_active' => true,
    'temperature' => 123,
    'functions' => [
        
    ],
    'dynamic_variables' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.magpipe.ai/functions/v1/create-agent"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"greeting\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"llm_model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"agent_type\": \"<string>\",\n  \"organization_name\": \"<string>\",\n  \"owner_name\": \"<string>\",\n  \"agent_role\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"is_active\": true,\n  \"temperature\": 123,\n  \"functions\": {},\n  \"dynamic_variables\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.magpipe.ai/functions/v1/create-agent")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"name\": \"<string>\",\n  \"greeting\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"llm_model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"agent_type\": \"<string>\",\n  \"organization_name\": \"<string>\",\n  \"owner_name\": \"<string>\",\n  \"agent_role\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"is_active\": true,\n  \"temperature\": 123,\n  \"functions\": {},\n  \"dynamic_variables\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.magpipe.ai/functions/v1/create-agent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"name\": \"<string>\",\n  \"greeting\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"llm_model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"agent_type\": \"<string>\",\n  \"organization_name\": \"<string>\",\n  \"owner_name\": \"<string>\",\n  \"agent_role\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"is_active\": true,\n  \"temperature\": 123,\n  \"functions\": {},\n  \"dynamic_variables\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "error": {
    "code": "missing_param",
    "message": "name is required"
  }
}

POST

functions

create-agent

Create Agent

curl --request POST \
  --url https://api.magpipe.ai/functions/v1/create-agent \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "<string>",
  "greeting": "<string>",
  "system_prompt": "<string>",
  "voice_id": "<string>",
  "llm_model": "<string>",
  "language": "<string>",
  "agent_type": "<string>",
  "organization_name": "<string>",
  "owner_name": "<string>",
  "agent_role": "<string>",
  "transfer_phone_number": "<string>",
  "is_active": true,
  "temperature": 123,
  "functions": {},
  "dynamic_variables": [
    {}
  ]
}
'

import requests

url = "https://api.magpipe.ai/functions/v1/create-agent"

payload = {
    "name": "<string>",
    "greeting": "<string>",
    "system_prompt": "<string>",
    "voice_id": "<string>",
    "llm_model": "<string>",
    "language": "<string>",
    "agent_type": "<string>",
    "organization_name": "<string>",
    "owner_name": "<string>",
    "agent_role": "<string>",
    "transfer_phone_number": "<string>",
    "is_active": True,
    "temperature": 123,
    "functions": {},
    "dynamic_variables": [{}]
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    name: '<string>',
    greeting: '<string>',
    system_prompt: '<string>',
    voice_id: '<string>',
    llm_model: '<string>',
    language: '<string>',
    agent_type: '<string>',
    organization_name: '<string>',
    owner_name: '<string>',
    agent_role: '<string>',
    transfer_phone_number: '<string>',
    is_active: true,
    temperature: 123,
    functions: {},
    dynamic_variables: [{}]
  })
};

fetch('https://api.magpipe.ai/functions/v1/create-agent', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.magpipe.ai/functions/v1/create-agent",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'greeting' => '<string>',
    'system_prompt' => '<string>',
    'voice_id' => '<string>',
    'llm_model' => '<string>',
    'language' => '<string>',
    'agent_type' => '<string>',
    'organization_name' => '<string>',
    'owner_name' => '<string>',
    'agent_role' => '<string>',
    'transfer_phone_number' => '<string>',
    'is_active' => true,
    'temperature' => 123,
    'functions' => [
        
    ],
    'dynamic_variables' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.magpipe.ai/functions/v1/create-agent"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"greeting\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"llm_model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"agent_type\": \"<string>\",\n  \"organization_name\": \"<string>\",\n  \"owner_name\": \"<string>\",\n  \"agent_role\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"is_active\": true,\n  \"temperature\": 123,\n  \"functions\": {},\n  \"dynamic_variables\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.magpipe.ai/functions/v1/create-agent")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"name\": \"<string>\",\n  \"greeting\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"llm_model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"agent_type\": \"<string>\",\n  \"organization_name\": \"<string>\",\n  \"owner_name\": \"<string>\",\n  \"agent_role\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"is_active\": true,\n  \"temperature\": 123,\n  \"functions\": {},\n  \"dynamic_variables\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.magpipe.ai/functions/v1/create-agent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"name\": \"<string>\",\n  \"greeting\": \"<string>\",\n  \"system_prompt\": \"<string>\",\n  \"voice_id\": \"<string>\",\n  \"llm_model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"agent_type\": \"<string>\",\n  \"organization_name\": \"<string>\",\n  \"owner_name\": \"<string>\",\n  \"agent_role\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"is_active\": true,\n  \"temperature\": 123,\n  \"functions\": {},\n  \"dynamic_variables\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "error": {
    "code": "missing_param",
    "message": "name is required"
  }
}

Overview

Creates a new AI agent that can handle phone calls, SMS messages, and chat conversations. Agents are fully customizable with their own personality, voice, and capabilities.

Request

Headers

string

required

Bearer token — either a Supabase JWT or a mgp_ API key.

string

required

Must be application/json

Body Parameters

string

required

Display name for the agent.Example: "Reception Agent"Constraints:

1-100 characters

string

The message the agent says when answering a call.Example: "Hello, thanks for calling Acme Corp. How can I help you today?"Constraints:

Maximum 500 characters
Should be under 15 seconds when spoken

string

Instructions that define the agent’s personality, knowledge, and behavior. This is the most important setting for customizing agent responses.Example:

You are Sarah, a friendly receptionist for Acme Corp.

Your responsibilities:
- Answer questions about our services
- Help callers schedule appointments
- Take messages when needed

Business hours: Monday-Friday, 9am-5pm
Location: 123 Main St, Vancouver BC

Always be professional and helpful.

Constraints:

Maximum 10,000 characters
Supports markdown formatting

string

ID of the voice to use for phone calls. Use the List Voices endpoint to get all available options, including any cloned voices on your account.ElevenLabs voices:

Voice ID	Name	Description
`EXAVITQu4vr4xnSDxMaL`	Sarah	Professional, American female
`MF3mGyEYCl7XYWbV9V6O`	Elli	Youthful, American female
`TxGEqnHWrfWFTfGW9XjX`	Josh	Strong, American male
`pFZP5JQG7iQjIQuC4Bku`	Lily	Confident, British female
`nPczCjzI2devNBz1zQrb`	Brian	Classy, American male
`onwK4e9ZLuTAKqWW03F9`	Daniel	Formal, British male
`cjVigY5qzO86Huf0OWal`	Eric	Friendly, American male
`cgSgspJ2msm6clMCkdW9`	Jessica	Expressive, American female
`XrExE9yKIg1WjnnlVkGX`	Matilda	Upbeat, American female
`CwhRBWXzGAHq8TQ4Fs17`	Roger	Classy, American male
`FGY2WhTYpPnrIDTdsKH5`	Laura	Sassy, American female
`IKne3meq5aSn9XLyUdCD`	Charlie	Hyped, Australian male
`JBFqnCBsd6RMkjVDRZzb`	George	Mature, British male
`N2lVS1w4EtoT3dr4eOWO`	Callum	Husky, American male
`SAz9YHcvj6GT2YYXdXww`	River	Calm, neutral American
`SOYHLrjzK2X1ezoPC6cr`	Harry	Rough, American male
`TX3LPaxmHKxFdv7VOQHJ`	Liam	Confident, American male
`Xb7hH8MSUJpSbSDYk0k2`	Alice	Professional, British female
`bIHbv24MWmeRgasZH58o`	Will	Chill, American male
`hpp4J3VqNfWAUOO0d1Us`	Bella	Professional, American female
`iP95p4xoKVk53GoZ742B`	Chris	Casual, American male
`pNInz6obpgDQGcFmaJgB`	Adam	Deep, American male
`pqHfZKP75CvOlQylNhV4`	Bill	Trustworthy, American male

OpenAI voices (prefix openai-):

Voice ID	Name	Description
`openai-alloy`	Alloy	Neutral, professional
`openai-echo`	Echo	Warm, friendly
`openai-fable`	Fable	Expressive, dynamic
`openai-nova`	Nova	Bright, energetic
`openai-onyx`	Onyx	Deep, authoritative
`openai-shimmer`	Shimmer	Soft, calm

Default: EXAVITQu4vr4xnSDxMaL (Sarah)

string

LLM model for conversations. Use the List Models endpoint to get all available options.

Model ID	Description
`gpt-4.1`	Recommended — best balance of speed and quality (default)
`gpt-4o-mini`	Fast and cost-effective
`gpt-4o`	Most capable, higher latency

Default: gpt-4.1

string

Primary language for the agent.Default: en-USSupported: en-US, en-GB, es-ES, fr-FR, de-DE

string

The channel type this agent handles.

Value	Description
`inbound_voice`	Answers incoming phone calls (default)
`outbound_voice`	Places outgoing phone calls
`text`	Handles SMS conversations
`chat_widget`	Handles web chat widget conversations
`whatsapp`	Handles WhatsApp messages
`email`	Handles email conversations

Default: inbound_voice

string

Name of the organization the agent represents.Example: "Acme Corp"

string

Name of the agent’s owner.Example: "Jane Smith"

string

Description of the agent’s role.Example: "Front desk receptionist"

string

Phone number to transfer calls to when requested.Example: "+14155551234"

boolean

Whether the agent is active and can receive calls.Default: true

number

LLM temperature for response creativity.Default: 0.7Range: 0 to 1

object

Configuration for agent functions (capabilities) the agent can use during calls.

end_call

Property	Type	Description
`enabled`	boolean	Allow agent to hang up when conversation is complete. Default: `true`
`description`	string	When to end calls. Default: “End the call when the conversation is complete or caller says goodbye.”

transfer

Property	Type	Description
`enabled`	boolean	Allow agent to transfer calls. Default: `false`
`numbers`	array	Transfer destinations. Each: `{ number, label, description }`
`description`	string	General instruction for transfer behavior

Transfer number format:

{
  "number": "+14155551234",
  "label": "Sales",
  "description": "Transfer for sales inquiries"
}

sms

Property	Type	Description
`enabled`	boolean	Allow agent to send SMS messages. Default: `false`
`description`	string	When to send SMS
`templates`	array	Pre-defined message templates

extract_data

Property	Type	Description
`enabled`	boolean	Extract structured data from conversations. Default: `false`
`schema`	object	JSON schema defining fields to extract
`description`	string	What data to collect

booking

Property	Type	Description
`enabled`	boolean	Allow agent to book appointments. Default: `false`
`calendar_id`	string	Connected calendar ID
`description`	string	Booking behavior instruction
`get_availability`	object	`{ enabled, description }` for availability checks

Example:

{
  "end_call": {
    "enabled": true,
    "description": "End the call when the customer confirms their order or says goodbye."
  },
  "transfer": {
    "enabled": true,
    "numbers": [
      { "number": "+14155551234", "label": "Sales", "description": "Transfer for sales inquiries" },
      { "number": "+14155555678", "label": "Support", "description": "Transfer for technical issues" }
    ],
    "description": "Transfer when caller requests to speak with a specific department."
  },
  "sms": {
    "enabled": true,
    "description": "Send order confirmation via SMS after completing an order."
  }
}

array

Dynamic variables for extracting structured data from conversations. These are stored separately from the agent config and define what information the AI should capture during calls.Each variable object:

name (string, required) — Variable name (e.g., caller_name)
description (string) — What to extract
var_type (string) — text (default), number, boolean, or enum
enum_options (array) — Required when var_type is enum

[
  {"name": "caller_name", "description": "Full name of the caller", "var_type": "text"},
  {"name": "caller_email", "description": "Email address", "var_type": "text"},
  {"name": "priority", "description": "Call priority level", "var_type": "enum", "enum_options": ["low", "medium", "high"]}
]

You can also manage dynamic variables independently via the Dynamic Variables API.

Response

Returns the full agent object wrapped in an agent key.

object

Show Agent object

string

Unique identifier (UUID) for the agent config row.

string

Agent display name.

string

Call greeting message.

string

Agent instructions.

string

Selected voice ID.

boolean

Active status.

string

ISO 8601 creation timestamp.

string

ISO 8601 last update timestamp.

Example Request

curl -X POST "https://api.magpipe.ai/functions/v1/create-agent" \
  -H "Authorization: Bearer mgp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reception Agent",
    "greeting": "Hello, thanks for calling! How can I help you today?",
    "system_prompt": "You are a friendly receptionist. Be helpful and professional.",
    "voice_id": "EXAVITQu4vr4xnSDxMaL"
  }'

const response = await fetch('https://api.magpipe.ai/functions/v1/create-agent', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer mgp_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Reception Agent',
    greeting: 'Hello, thanks for calling! How can I help you today?',
    system_prompt: 'You are a friendly receptionist. Be helpful and professional.',
    voice_id: 'EXAVITQu4vr4xnSDxMaL',
  }),
});

const data = await response.json();
console.log(data.agent);

import requests

response = requests.post(
    'https://api.magpipe.ai/functions/v1/create-agent',
    headers={
        'Authorization': 'Bearer mgp_your_api_key',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Reception Agent',
        'greeting': 'Hello, thanks for calling! How can I help you today?',
        'system_prompt': 'You are a friendly receptionist. Be helpful and professional.',
        'voice_id': 'EXAVITQu4vr4xnSDxMaL',
    },
)

print(response.json()['agent'])

Example Response

{
  "agent": {
    "id": "c72ea2b8-1234-5678-9abc-def012345678",
    "name": "Reception Agent",
    "greeting": "Hello, thanks for calling! How can I help you today?",
    "system_prompt": "You are a friendly receptionist. Be helpful and professional.",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "llm_model": "gpt-4.1",
    "language": "en-US",
    "is_active": true,
    "created_at": "2024-01-15T10:00:00.000Z",
    "updated_at": "2024-01-15T10:00:00.000Z",
    "dynamic_variables": []
  }
}

Error Responses

{
  "error": {
    "code": "missing_param",
    "message": "name is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized"
  }
}

List Agents - Get all agents
Get Agent - Get agent details
Update Agent - Modify an agent
Delete Agent - Remove an agent

API Reference

Agents

Custom Functions

Dynamic Variables

Memory

Calls

Call Whitelist

Skills

Batch Calls

Testing

Messages

Phone Numbers

Chat Widget

Knowledge Base

Voice

Models

Calendar

Contacts

Billing

Scheduled Actions

API Keys & Webhooks

Create Agent

Overview

Request

Headers

Body Parameters

end_call

transfer

sms

extract_data

booking

Response

Example Request

Example Response

Error Responses

​Overview

​Request

​Headers

​Body Parameters

​end_call

​transfer

​sms

​extract_data

​booking

​Response

​Example Request

​Example Response

​Error Responses

​Related Endpoints

Overview

Request

Headers

Body Parameters

end_call

transfer

sms

extract_data

booking

Response

Example Request

Example Response

Error Responses

Related Endpoints