Skip to main content
POST
/
agents
curl --request POST \
  --url https://client-api.tryvox.co/v3/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer support agent"
}
'
{
  "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "created_at": 123,
  "updated_at": 123,
  "production_version": "<string>",
  "data": {
    "prompt": {
      "prompt": "",
      "firstLine": "",
      "firstLineType": "aiFirstDynamic",
      "pauseBeforeSpeakingSeconds": 0,
      "isFirstMessageInterruptible": true
    },
    "stt": {
      "languages": [
        "<string>"
      ],
      "speed": "high"
    },
    "llm": {
      "model": "<string>",
      "temperature": 1
    },
    "voice": {
      "id": "<string>",
      "provider": "<string>",
      "model": "<string>",
      "speed": 1,
      "volume": 1,
      "language": "<string>",
      "temperature": 0.9
    },
    "speech": {
      "responsiveness": 1,
      "boostedKeywords": "<string>"
    },
    "callSettings": {
      "backgroundMusic": "none",
      "backgroundMusicVolume": 0.5,
      "noiseCancellation": "bvc",
      "activationThreshold": 0.55,
      "callTimeoutInSeconds": 900,
      "silenceCallTimeoutInSeconds": 30,
      "ringDurationInSeconds": 30,
      "dtmfTerminationEnabled": false,
      "dtmfTerminationKey": "#",
      "dtmfTimeoutSeconds": 3
    },
    "postCall": {
      "actions": [
        {
          "name": "<string>",
          "isNullable": false,
          "description": "<string>",
          "enumOptions": [
            "<string>"
          ]
        }
      ]
    },
    "security": {
      "optOutSensitiveDataStorage": false
    },
    "webhookSettings": {
      "callDataWebhookUrl": "<string>",
      "inboundCallWebhookUrl": "<string>",
      "inboundCallWebhookSigningEnabled": false
    },
    "knowledge": {
      "ragEnabled": false,
      "knowledgeIds": [
        123
      ]
    },
    "presetDynamicVariables": {},
    "toolIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "builtInTools": [
      {
        "toolType": "<string>",
        "name": "end_call",
        "description": "<string>",
        "speakDuringExecution": {
          "enabled": false,
          "messages": [
            "<string>"
          ]
        }
      }
    ]
  },
  "flow_data": {
    "nodes": [
      {
        "id": "<string>",
        "type": "<string>",
        "data": {
          "name": "<string>",
          "prompt": "<string>",
          "staticSentence": "<string>",
          "loopCondition": "<string>",
          "isAllowInterruption": true,
          "isSkipUserResponse": true,
          "globalNodeSettings": {
            "isGlobalNode": false,
            "transitionCondition": "<string>"
          },
          "transitions": [
            {
              "id": "<string>",
              "condition": "<string>",
              "isSkipUserResponse": true,
              "isFallback": true,
              "isGlobalTransition": true
            }
          ],
          "firstLineType": "aiFirst",
          "pauseBeforeSpeakingSeconds": 2.5
        },
        "position": {
          "x": 123,
          "y": 123
        }
      }
    ],
    "edges": [
      {
        "id": "<string>",
        "source": "<string>",
        "target": "<string>",
        "type": "custom",
        "sourceHandle": "<string>"
      }
    ]
  },
  "version": {
    "version": "<string>",
    "is_production": true,
    "created_at": 123,
    "description": "<string>"
  },
  "validation_message": ""
}

Authorizations

​
Authorization
string
header
required

조직 API 키를 Authorization: Bearer <token> 형식으로 보냅니다.

Body

application/json

에이전트 생성 요청입니다. 에이전트 설정은 data, flow 그래프는 flow_data로 보냅니다.

에이전트 생성 요청입니다.

single_prompt는 name만 필수입니다. data를 보내지 않거나 일부만 보내면 서버 기본값으로 채웁니다. flow는 생성 시점부터 flow_data가 필요합니다.

​
name
string
required

대시보드와 목록 응답에 표시되는 에이전트 이름입니다.

Required string length: 1 - 255
​
type
enum<string>
default:single_prompt

에이전트 유형입니다. single_prompt는 data를 사용하고, flow는 생성 시 flow_data 그래프가 필요합니다.

Available options:
single_prompt,
flow
​
data
AgentDataCreate · object

에이전트 설정 요청입니다. 구조는 agent-schema/agent-data-create에 공개되어 있으며, 누락되거나 일부만 전달된 값은 서버 기본값과 병합됩니다.

​
flow_data
FlowData · object

flow 에이전트의 그래프입니다. flow-schema/flow-data와 동일한 FlowData 구조를 사용하며, type이 flow이면 필수입니다. OpenAPI에서 nodes, edges, 노드별 data shape를 직접 확인할 수 있습니다.

​
folder_id
string | null

에이전트를 생성할 폴더입니다. 생략하거나 null이면 조직 루트에 생성됩니다.

Response

성공 응답

create/update 응답입니다. AgentResponse와 flow validator 메시지를 함께 반환합니다.

validation_message는 schema 검증을 통과해 200/201로 저장된 요청의 flow_data validator warning을 줄바꿈으로 합친 요약 문자열입니다. warning이 없거나 single_prompt 에이전트이면 빈 문자열입니다. Tier 3 reject 케이스는 400으로 처리하므로 이 필드에는 포함되지 않습니다.

​
agent_id
string<uuid>
required

에이전트 UUID입니다.

​
name
string
required

에이전트 이름입니다. 버전 스냅샷을 조회하더라도 현재 최상위 이름을 반환합니다.

​
type
enum<string>
required

에이전트 유형입니다. single_prompt 또는 flow 값을 사용합니다.

Available options:
single_prompt,
flow
​
created_at
integer
required

리소스 생성 시각입니다. unix milliseconds 형식입니다.

​
updated_at
integer
required

리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다.

​
production_version
string | null

현재 게시된 production 버전입니다. 없으면 null입니다.

​
data
AgentDataResponse · object

선택된 에이전트 설정 스냅샷입니다. 구조는 agent-schema/agent-data-response에 공개되어 있습니다.

​
flow_data
FlowData · object

선택된 flow 그래프 스냅샷입니다. flow 에이전트에는 값이 있고, single_prompt 에이전트는 null입니다.

​
version
AgentVersionMeta · object

스냅샷 조회 시에만 populated (version=v{n} 또는 production).

​
validation_message
string
default:""

flow_data validator 가 발견한 warning 들의 줄바꿈 구분 요약. warning 이 없거나 single_prompt 에이전트면 빈 문자열.