API Integration

Base URL: https://api.toughtongueai.com/api/public All requests require Bearer token authentication.

Authentication

curl https://api.toughtongueai.com/api/public/scenarios \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get your token from Developer Portal → API Keys.

Proxy API calls through your backend. Never expose tokens client-side.

Core Workflows

1. Create Scenario

curl -X POST https://api.toughtongueai.com/api/public/scenarios \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Cold Call",
    "ai_instructions": "You are a skeptical VP of Engineering...",
    "is_public": true
  }'

Response:

{
  "id": "scenario_abc123",
  "name": "Sales Cold Call",
  "is_public": true
}

2. Create Session

curl -X POST https://api.toughtongueai.com/api/public/v2/sessions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario_id": "scenario_abc123",
    "user_email": "trainee@company.com",
    "metadata": {"team": "sales"}
  }'

Response:

{
  "session_id": "session_xyz789",
  "embed_url": "https://app.toughtongueai.com/embed/session/session_xyz789"
}

3. Analyze Session

curl -X POST https://api.toughtongueai.com/api/public/sessions/analyze \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "session_xyz789"}'

Response:

{
  "overall_score": 85,
  "strengths": ["Strong opening", "Good questions"],
  "improvements": ["Handle objections more confidently"]
}

Backend Proxy Example

Node.js
Python

import express from "express";

const app = express();
const TTAI_TOKEN = process.env.TTAI_TOKEN;

app.post("/api/analyze", async (req, res) => {
  const response = await fetch("https://api.toughtongueai.com/api/public/sessions/analyze", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${TTAI_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ session_id: req.body.session_id }),
  });
  res.json(await response.json());
});

from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)
TTAI_TOKEN = os.environ.get('TTAI_TOKEN')

@app.route('/api/analyze', methods=['POST'])
def analyze():
    response = requests.post(
        'https://api.toughtongueai.com/api/public/sessions/analyze',
        headers={'Authorization': f'Bearer {TTAI_TOKEN}'},
        json={'session_id': request.json['session_id']}
    )
    return jsonify(response.json())

Endpoint Reference

Scenarios

Method	Endpoint	Description
GET	`/scenarios`	List scenarios
POST	`/scenarios`	Create scenario
GET	`/scenarios/{id}`	Get scenario
PATCH	`/scenarios/{id}`	Update scenario
DELETE	`/scenarios/{id}`	Delete scenario

Sessions

Method	Endpoint	Description
GET	`/sessions`	List sessions
GET	`/sessions/{id}`	Get session
POST	`/sessions/analyze`	Analyze session
POST	`/v2/sessions`	Create session

Utilities

Method	Endpoint	Description
POST	`/test`	Test token
GET	`/balance`	Check balance

Error Codes

Code	Meaning
400	Invalid parameters
401	Invalid token
403	Insufficient permissions
404	Resource not found
429	Rate limited
500	Server error

Error format:

{
  "error": "Message",
  "details": {}
}

Best Practices

Cache scenarios — they rarely change
Poll or use callbacks — check session completion via iframe events or polling
Retry with backoff — handle transient failures
Log errors — monitor API health

Next: API Reference →

Introduction

Product Documentation

Developer Documentation

Authentication

Core Workflows

1. Create Scenario

2. Create Session

3. Analyze Session

Backend Proxy Example

Endpoint Reference

Scenarios

Sessions

Utilities

Error Codes

Best Practices

​Authentication

​Core Workflows

​1. Create Scenario

​2. Create Session

​3. Analyze Session

​Backend Proxy Example

​Endpoint Reference

​Scenarios

​Sessions

​Utilities

​Error Codes

​Best Practices

Authentication

Core Workflows

1. Create Scenario

2. Create Session

3. Analyze Session

Backend Proxy Example

Endpoint Reference

Scenarios

Sessions

Utilities

Error Codes

Best Practices