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": [
    {}
  ]
}
'

{
  "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": [
    {}
  ]
}
'

{
  "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

Authorization

string

required

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

Content-Type

string

required

Must be application/json

Body Parameters

name

string

required

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

1-100 characters

greeting

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

system_prompt

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

voice_id

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)

llm_model

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

language

string

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

agent_type

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

organization_name

string

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

owner_name

string

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

agent_role

string

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

transfer_phone_number

string

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

is_active

boolean

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

temperature

number

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

functions

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."
  }
}

dynamic_variables

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.

agent

object

Show Agent object

string

Unique identifier (UUID) for the agent config row.

name

string

Agent display name.

greeting

string

Call greeting message.

system_prompt

string

Agent instructions.

voice_id

string

Selected voice ID.

is_active

boolean

Active status.

created_at

string

ISO 8601 creation timestamp.

updated_at

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"
  }'

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

MCP Server Get Agent

​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