Create a new agent

API keys: knowledge documents listed in abilities are attached only if the key has knowledge.edit. Custom functions are never attached by a key. Skipped items are reported in warnings (knowledge_docs_skipped, function_assign_skipped); the agent is still created.

POST /agents

Create a new agent

cURL

curl --request POST \
  --url https://api.pineyard.ai/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "voice": "<string>",
  "prompt": "<string>"
}
'

201

{
  "id": "<string>",
  "name": "<string>",
  "prompt": "<string>",
  "greeting": "<string>",
  "voice": "<string>",
  "status": "<string>",
  "preCallVariables": [
    "<string>"
  ],
  "variables": [
    "<string>"
  ],
  "systemVariables": [
    "<string>"
  ],
  "extractionConfig": {
    "prompt": "<string>",
    "keys": [
      {
        "name": "<string>",
        "type": "string",
        "description": "<string>"
      }
    ],
    "includeToolLogs": false
  },
  "agentType": "<string>",
  "enableRecording": true,
  "endCallEnabled": true,
  "endCallMessage": "<string>",
  "endCallTriggers": [
    "<string>"
  ],
  "maxCallDurationSecs": 123,
  "backgroundAudioId": "<string>",
  "backgroundAudioVolume": 123,
  "voicemailDetectionEnabled": true,
  "voicemailMessage": "<string>",
  "screenerHandlingEnabled": true,
  "transferEnabled": true,
  "transferNumber": "<string>",
  "transferMessage": "<string>",
  "transferTriggers": [
    "<string>"
  ],
  "language": "<string>",
  "studioConfig": {
    "agentName": "<string>",
    "companyName": "<string>",
    "languages": [
      "<string>"
    ],
    "primaryLanguage": "<string>",
    "gender": "female",
    "tone": "warm_professional",
    "goal": "<string>",
    "flowSteps": [
      {
        "id": "<string>",
        "title": "<string>",
        "detail": "<string>"
      }
    ],
    "faqs": [
      {
        "question": "<string>",
        "answer": "<string>"
      }
    ],
    "industry": "<string>",
    "designation": "<string>",
    "companyDescription": "<string>",
    "briefText": "<string>",
    "welcomeMessage": "<string>",
    "guardrails": [],
    "flowGraph": {
      "nodes": [
        {
          "id": "<string>",
          "type": "step",
          "title": "<string>",
          "detail": "<string>",
          "position": {
            "x": 123,
            "y": 123
          }
        }
      ],
      "edges": [
        {
          "id": "<string>",
          "source": "<string>",
          "target": "<string>",
          "condition": "<string>"
        }
      ]
    },
    "closingBehavior": "confirm_and_end",
    "abilities": {
      "transfer": {
        "number": "<string>",
        "triggers": [
          "CALLER_ASKS_HUMAN"
        ]
      },
      "booking": {
        "types": [
          "site_visit"
        ]
      },
      "callback": true,
      "whatsapp": {
        "collectionIds": [
          "<string>"
        ],
        "templateIds": [
          "<string>"
        ]
      },
      "knowledgeDocIds": [
        "<string>"
      ],
      "functionIds": [
        "<string>"
      ]
    },
    "languageSwitching": "fast",
    "keyTerms": [
      "<string>"
    ],
    "sampleDialogue": "<string>",
    "promptSpec": 1,
    "overrides": {
      "namesPolicy": "use_name",
      "identityConfirm": "by_name",
      "silenceHandling": "ask",
      "endCallEtiquette": "close_only",
      "mixRatio": "balanced"
    }
  },
  "abilities": {
    "transfer": {
      "number": "<string>",
      "triggers": [
        "CALLER_ASKS_HUMAN"
      ]
    },
    "booking": {
      "types": [
        "site_visit"
      ]
    },
    "callback": true,
    "whatsapp": {
      "collectionIds": [
        "<string>"
      ],
      "templateIds": [
        "<string>"
      ]
    },
    "knowledgeDocIds": [
      "<string>"
    ],
    "functionIds": [
      "<string>"
    ]
  },
  "promptEditedManually": true,
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "warnings": [
    {
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

Required scope: agents.edit

Authorizations

Authorization · string · header · required

Your API key, e.g. pk_live_xxxxxxxxxxxxxxxxxxxxxxxx.

Body

application/json

name · string · required

Required string length: 1 - 100

voice · string · required

Minimum string length: 1

prompt · string

Maximum string length: 128000

greeting · string

Maximum string length: 2000

preCallVariables · string[]

Maximum array length: 100

Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$

extractionConfig · object

Show child attributes

agentType · enum<string>

Available options: OUTBOUND, INBOUND

enableRecording · boolean

endCallEnabled · boolean

endCallMessage · string

Maximum string length: 500

endCallTriggers · enum<string>[]

Maximum array length: 4

Available options: CALLER_GOODBYE, GOAL_COMPLETED, IDLE, REMOVE_FROM_LIST

maxCallDurationSecs · integer

Required range: 60 <= x <= 3600

backgroundAudioId · string | null

backgroundAudioVolume · number | null

Required range: 0 <= x <= 1

voicemailDetectionEnabled · boolean

voicemailMessage · string | null

Maximum string length: 500

screenerHandlingEnabled · boolean

transferEnabled · boolean

transferNumber · string

Maximum string length: 32

Pattern: ^\+\d{8,15}$

transferMessage · string

Maximum string length: 500

transferTriggers · enum<string>[]

Available options: CALLER_ASKS_HUMAN, FRUSTRATED, ASKS_MANAGER, UNKNOWN_QUESTION, BILLING

studioConfig · object

Show child attributes

abilities · object

Show child attributes

Response

201

application/json

Created

id · string · required

name · string · required

prompt · string · required

greeting · string | null · required

voice · string · required

status · string · required

preCallVariables · string[] | null · required

variables · string[] · required

systemVariables · string[] · required

extractionConfig · object | null · required

Show child attributes

agentType · string · required

enableRecording · boolean · required

endCallEnabled · boolean · required

endCallMessage · string | null · required

endCallTriggers · string[] | null · required

maxCallDurationSecs · number | null · required

backgroundAudioId · string | null · required

backgroundAudioVolume · number | null · required

voicemailDetectionEnabled · boolean · required

voicemailMessage · string | null · required

screenerHandlingEnabled · boolean · required

transferEnabled · boolean · required

transferNumber · string | null · required

transferMessage · string | null · required

transferTriggers · string[] | null · required

language · string · required

studioConfig · object | null · required

Show child attributes

abilities · object | null · required

Show child attributes

promptEditedManually · boolean · required

createdAt · string · required

updatedAt · string · required

warnings · object[]

Show child attributes