Skip to main content
POST
/
api
/
ai
/
playground
Generate playground AI response
curl --request POST \
  --url https://your-instance.example.com/api/ai/playground \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "Hi, I was hoping to book a tour for next Tuesday.",
  "promptId": "5f7b1c2e8a1d4e0012c3b4a5",
  "conversationId": "64d2f9c5e8a1d4e001a0b1c2",
  "conversation": [
    {
      "role": "user",
      "content": "Hello there"
    },
    {
      "role": "assistant",
      "content": "Hi! How can I help today?"
    }
  ]
}
'
{
  "success": true,
  "response": "Great — I can book you for Friday at 2pm. Want me to send a confirmation text?",
  "messageMetric": {
    "organizationId": "64a1b2c3d4e5f60012345678",
    "metricRunId": "run_64d2f9c5e8a1d4e001a0b1c2",
    "aiAgentName": "Leasing Specialist",
    "aiCalls": [],
    "toolCalls": []
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
message
string
required

The latest user turn to send into the agent. Appended to conversation server-side; do not include it twice.

​
promptId
string
required

Identifies the saved prompt to run this turn against. Required — the playground refuses to run without a target prompt.

​
conversationId
string

Optional id of an existing conversation used for context lookup (variables, business context). The playground does not persist back into it.

​
conversation
object[]

Prior turns the editor is replaying for this playground session. The server does not load history from storage — whatever is sent here is the entire visible history.

Response

AI response generated

Playground turn result. approvalCards is only set when the agent paused for tool approval; messageMetric is only set for ADMIN/SUPERADMIN.

​
success
enum<boolean>
required
Available options:
true
​
response
string
required
​
approvalCards
object[]
​
messageMetric
object

MessageMetric snapshot captured for the playground turn — only included for ADMIN/SUPERADMIN callers. Surfaces underlying AI calls and tool calls for debugging.

Example:
{
  "organizationId": "64a1b2c3d4e5f60012345678",
  "metricRunId": "run_64d2f9c5e8a1d4e001a0b1c2",
  "aiAgentName": "Leasing Specialist",
  "aiCalls": [
    {
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "inputTokens": 412,
      "outputTokens": 88,
      "durationMs": 1742
    }
  ],
  "toolCalls": [
    {
      "name": "getContact",
      "args": { "phone": "+14165550100" },
      "durationMs": 84
    }
  ]
}