> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coraltalk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roleplay

> Create and manage roleplay speaking scenarios via the Platform API.

# Roleplay

A **roleplay** is a scenario-based speaking assignment where students practice a conversation in a defined role.

## Endpoints

| Method   | Path            | Description                 |
| -------- | --------------- | --------------------------- |
| `POST`   | `/roleplay`     | Create                      |
| `GET`    | `/roleplay`     | List (`?classId=` optional) |
| `GET`    | `/roleplay/:id` | Get                         |
| `PUT`    | `/roleplay/:id` | Update                      |
| `DELETE` | `/roleplay/:id` | Delete                      |

## Create

| Field                     | Required | Description                                                                                                        |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `name`                    | Yes      | Scenario title                                                                                                     |
| `classId`                 | Yes      | Class ID                                                                                                           |
| `roleplayStudentRole`     | Yes      | Student's role                                                                                                     |
| `roleplayCoralRole`       | Yes      | Coral's role                                                                                                       |
| `roleplayScenario`        | Yes      | What the student will play (the student-side scenario/context). Min `150`, max `3000` characters.                  |
| `roleplayScenarioDetails` | Yes      | How you want CoralTalk to perform (tone, behavior, constraints, response style). Min `300`, max `6000` characters. |
| `roleplayDuration`        | No       | Max duration (seconds, default `600`)                                                                              |

```bash theme={null}
curl -X POST "https://app.coraltalk.com/api/v1/prod/roleplay" \
  -H "Authorization: Bearer ct_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Salary negotiation",
    "classId": "CLASS_ID",
    "roleplayStudentRole": "Job candidate",
    "roleplayCoralRole": "Hiring manager",
    "roleplayScenario": "You are a job candidate negotiating a starting salary.",
    "roleplayScenarioDetails": "CoralTalk should act as a professional but budget-conscious hiring manager, ask clarifying questions, and offer a counterproposal before agreeing."
  }'
```

## Student URL

```
https://app.coraltalk.com/exam/{EXAM_ID}/roleplay
```

Or on a [custom domain](/coraltalk-apis/custom-domains): `https://exams.yourschool.edu/exam/{EXAM_ID}/roleplay`

## Custom domain sign-in

On a custom domain, use [Student sign-in token](/coraltalk-apis/student-sign-in-token) from your backend (`POST /api/v1/prod/students/sign-in-token`) before launching the roleplay session.