> ## Documentation Index > Fetch the complete documentation index at: https://docs.tetherai.ca/llms.txt > Use this file to discover all available pages before exploring further. # Generate playground AI response > Runs a one-off playground turn against the specified prompt using the caller-supplied conversation history. Used by the prompt editor to preview replies; does not persist conversation state. ADMIN and SUPERADMIN callers also receive the captured MessageMetric for the turn. ## OpenAPI ````yaml /api-reference/openapi.yaml post /api/ai/playground openapi: 3.0.3 info: title: Tether Relay and Tether API version: 1.0.0 description: >- Route-derived OpenAPI contract generated from tether-relay backend sources. Regenerate with scripts/sync-openapi-from-backend.mjs. servers: - url: https://your-instance.example.com description: Production - url: http://localhost:2212 description: Local API service security: [] tags: - name: AI - name: Applications - name: Approval - name: Auth - name: Automations - name: Calls - name: Campaigns - name: Contact Analytics - name: Contact Metrics - name: Contact Notes - name: Contacts - name: Conversation Monitor - name: Conversations - name: Departments - name: Email - name: Escalation Dashboard - name: Event Logs - name: Google Sheets - name: Marketplace - name: Messages - name: Notification Sounds - name: Notifications - name: Org Snapshots - name: Organizations - name: Outreach - name: Outreach Metrics - name: Outreach Sources - name: Pipelines - name: Processes - name: Prompts - name: Reminders - name: Sms - name: Templates - name: Traces - name: Training - name: Upload - name: User Snapshots - name: Users - name: Vertical - name: Webchats - name: Webhook paths: /api/ai/playground: post: tags: - AI summary: Generate playground AI response description: >- Runs a one-off playground turn against the specified prompt using the caller-supplied conversation history. Used by the prompt editor to preview replies; does not persist conversation state. ADMIN and SUPERADMIN callers also receive the captured MessageMetric for the turn. operationId: post_ai_playground requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AIPlaygroundRequest' responses: '200': description: AI response generated content: application/json: schema: $ref: '#/components/schemas/AIPlaygroundResponse' '400': description: Message and prompt id are required content: application/json: schema: $ref: '#/components/schemas/AIErrorResponse' '404': description: User or prompt not found content: application/json: schema: $ref: '#/components/schemas/AIErrorResponse' '500': description: Failed to process playground message content: application/json: schema: $ref: '#/components/schemas/AIErrorResponse' security: - bearerAuth: [] components: schemas: AIPlaygroundRequest: type: object properties: message: type: string description: >- The latest user turn to send into the agent. Appended to `conversation` server-side; do not include it twice. promptId: type: string description: >- Identifies the saved prompt to run this turn against. Required — the playground refuses to run without a target prompt. conversationId: type: string description: >- Optional id of an existing conversation used for context lookup (variables, business context). The playground does not persist back into it. conversation: type: array description: >- 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. items: type: object properties: role: type: string content: type: string additionalProperties: true required: - message - promptId additionalProperties: true example: 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? AIPlaygroundResponse: type: object description: >- Playground turn result. `approvalCards` is only set when the agent paused for tool approval; `messageMetric` is only set for ADMIN/SUPERADMIN. properties: success: type: boolean enum: - true response: type: string approvalCards: type: array items: $ref: '#/components/schemas/AIApprovalCard' messageMetric: $ref: '#/components/schemas/AIPlaygroundMessageMetric' required: - success - response additionalProperties: true example: 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: [] AIErrorResponse: type: object description: >- Error envelope used across AI endpoints. The `error` field is a stable machine-readable code on approval-related failures (`approval_owner_mismatch`, `approval_org_mismatch`, `approval_expired`, `approval_service_unavailable`) and a human-readable string elsewhere. `message` is set alongside on the approval paths so the UI can render both. properties: success: type: boolean enum: - false error: type: string message: type: string required: - error additionalProperties: true example: success: false error: approval_expired message: >- This approval request has expired or was already handled. Please send a new playground message to retry. AIApprovalCard: type: object description: >- Pending tool-approval card surfaced by the playground when the agent wants to run a tool that requires sign-off. properties: approvalId: type: string toolName: type: string toolArgs: type: object additionalProperties: true createdAt: type: string format: date-time expiresAt: type: string format: date-time required: - approvalId - toolName additionalProperties: true example: approvalId: apr_64d2f9c5e8a1d4e001a0b1c2 toolName: sendSms toolArgs: phone: '+14165550100' message: Hi Alex — confirming your appointment for Friday at 2pm. createdAt: '2026-05-20T15:04:01.135Z' expiresAt: '2026-05-20T15:09:01.135Z' AIPlaygroundMessageMetric: type: object description: >- MessageMetric snapshot captured for the playground turn — only included for ADMIN/SUPERADMIN callers. Surfaces underlying AI calls and tool calls for debugging. properties: organizationId: type: string metricRunId: type: string aiAgentName: type: string aiCalls: type: array items: type: object additionalProperties: true toolCalls: type: array items: type: object additionalProperties: true additionalProperties: true 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 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````