Create a new agent

POST

https://api.hmsovereign.com/api/v1/agents

Agents

Last modified:2026-01-30 13:43:45

Maintainer:Jesper Rietbergen

Create a new AI voice agent with custom STT, LLM, and TTS configurations. Only the name is required - defaults will be applied for other settings.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

Responses

🟢201

application/json

Agent created successfully

Body

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://api.hmsovereign.com/api/v1/agents' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Customer Support Agent",
    "business_name": "string",
    "notification_email": "user@example.com",
    "first_message": "string",
    "is_active": true,
    "max_duration_seconds": 1,
    "autonomous_silence_handling": false,
    "voicemail_detection": false,
    "voicemail_message": "string",
    "webhook_url": "http://example.com",
    "webhook_secret": "string",
    "webhook_events": [
        "string"
    ],
    "stt_config": {
        "provider": "deepgram",
        "model": "nova-3-general",
        "language": "multi",
        "keyterms": [
            "yes",
            "no",
            "okay",
            "Acme"
        ]
    },
    "llm_config": {
        "provider": "openai",
        "model": "gpt-5",
        "voice": "ara",
        "temperature": 0.7,
        "messages": [
            {
                "role": "system",
                "content": "string"
            }
        ],
        "tools": [
            {}
        ]
    },
    "tts_config": {
        "provider": "openai",
        "voice_id": "alloy",
        "model": "eleven_flash_v2_5",
        "language": "nl",
        "stability": 0.5,
        "similarity_boost": 0.75,
        "use_speaker_boost": true,
        "speed": 1,
        "style": 0
    }
}'

Response Example

{
    "agent": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "Customer Support Agent",
        "business_name": "Acme Corp",
        "notification_email": "support@acme.com",
        "first_message": "Hello, welcome to Acme. How can I help you today?",
        "is_active": true,
        "max_duration_seconds": 300,
        "autonomous_silence_handling": false,
        "voicemail_detection": false,
        "voicemail_message": "Hello, this is Acme Corp. We will call you back at a later time. Thank you!",
        "webhook_url": "http://example.com",
        "webhook_secret": "string",
        "webhook_events": [
            "string"
        ],
        "analysis_plan": {
            "structured_data_plan": {
                "enabled": true,
                "schema": {
                    "type": "object",
                    "properties": {
                        "intent": {
                            "type": "string"
                        },
                        "sentiment": {
                            "type": "string",
                            "enum": [
                                "positive",
                                "neutral",
                                "negative"
                            ]
                        },
                        "appointment_booked": {
                            "type": "boolean"
                        }
                    }
                },
                "messages": [
                    {
                        "role": "system",
                        "content": "Analyze the following call transcript according to this schema: {{schema}}"
                    }
                ]
            },
            "min_messages_threshold": 2
        },
        "stt_config": {
            "provider": "deepgram",
            "model": "nova-3-general",
            "language": "multi",
            "keyterms": [
                "yes",
                "no",
                "okay",
                "Acme"
            ]
        },
        "llm_config": {
            "provider": "openai",
            "model": "gpt-5",
            "voice": "ara",
            "temperature": 0.7,
            "messages": [
                {
                    "role": "system",
                    "content": "string"
                }
            ],
            "tools": [
                {}
            ]
        },
        "tts_config": {
            "provider": "openai",
            "voice_id": "alloy",
            "model": "eleven_flash_v2_5",
            "language": "nl",
            "stability": 0.5,
            "similarity_boost": 0.75,
            "use_speaker_boost": true,
            "speed": 1,
            "style": 0
        },
        "created_at": "2019-08-24T14:15:22.123Z",
        "updated_at": "2019-08-24T14:15:22.123Z"
    }
}

Modified at 2026-01-30 13:43:45

List all agents

Get an agent