Create agent

Creates a new agent in your company. When you use a Specific agents key, the new agent is automatically added to that key's allowed list, so you can manage it right away.

Endpoint

POST /v1/agents

Request body

{
  "name": "API Test Agent",
  "greeting": "Hello!",
  "prompt": "You are a helpful assistant.",
  "farewell": "Goodbye!",
  "voiceId": "YOUR_VOICE_ID",
  "outputVariables": [
    {
      "name": "customerName",
      "description": "The caller's full name",
      "type": "string"
    }
  ]
}

Parameters

Field	Type	Required	Description
name	string	Yes	Agent name (must not be empty).
greeting	string	No	Opening message the agent says when the call starts.
prompt	string	No	System prompt that defines the agent behavior.
farewell	string	No	Closing message said at the end of the call.
voiceId	string	No	Voice identifier for the agent.
outputVariables	array	No	Variables to capture during the call. See below.

outputVariables items

Field	Type	Required	Description
name	string	Yes	Variable name.
description	string	No	What the variable represents.
type	string	No	Variable data type (e.g. string).
value	string	No	Default value.
enum	string[]	No	Allowed values, if restricted to a set.

Request example

curl -X POST "https://api.fonema.ai/v1/agents" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Test Agent",
    "greeting": "Hello!",
    "prompt": "You are a helpful assistant.",
    "farewell": "Goodbye!",
    "voiceId": "YOUR_VOICE_ID",
    "outputVariables": []
  }'

Response

Returns 201 Created:

{
  "name": "API Test Agent",
  "slug": "api-test-agent-x1y2z3w4",
  "message": "Agent created successfully"
}

Use the returned slug to further configure the agent with Edit agent.

Errors

Status	Description
400	Invalid request body (e.g. missing name).
403	No company is associated with the API key.