Assign

Assignments place published scenarios prominently in a learner’s portal. They are persistent recommendations, not an access-control boundary.

Before you assign

You need:

A learner userId from GET /users.
A published scenario slug from GET /scenarios or the TrainerTwin dashboard.

Scenario and persona configuration remains dashboard-only.

Create an assignment

curl "https://dash.trainertwin.com/api/v1/assignments" \
  --request POST \
  --header "x-api-key: $TRAINERTWIN_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "userId": "user_123",
    "scenario": "react-mock-interview"
  }'

A new assignment returns 201:

{
  "assignment": {
    "id": "assignment_123",
    "assignedAt": "2026-09-01T09:30:00.000Z",
    "userId": "user_123",
    "scenario": "react-mock-interview"
  },
  "practiceUrl": "https://your-org.trainertwin.com/s/AbC123",
  "created": true,
  "emailSent": true
}

practiceUrl is the learner’s direct practice link — send it through your own channel instead of (or alongside) the TrainerTwin email. Creating the same learner-scenario pair again is safe. TrainerTwin returns the existing assignment with created: false and does not send another email.

Assignment persistence succeeds even when email delivery fails. Check emailSent instead of retrying the assignment immediately.

Change an assignment

Move an assignment to another learner, scenario, or both:

curl "https://dash.trainertwin.com/api/v1/assignments/assignment_123" \
  --request PATCH \
  --header "x-api-key: $TRAINERTWIN_API_KEY" \
  --header "content-type: application/json" \
  --data '{ "scenario": "system-design-interview" }'

A changed assignment sends a notification to the target learner and returns a new practiceUrl (the old link stops working). A no-op update returns changed: false, the existing practiceUrl, and sends no email.

Inspect an assignment

curl "https://dash.trainertwin.com/api/v1/assignments/assignment_123" \
  --header "x-api-key: $TRAINERTWIN_API_KEY"

Returns the learner, scenario, current status (pending, used, expired, or cancelled), and practiceUrl.

Remove an assignment

curl "https://dash.trainertwin.com/api/v1/assignments/assignment_123" \
  --request DELETE \
  --header "x-api-key: $TRAINERTWIN_API_KEY"

Removing an assignment does not remove the scenario or historical practice sessions.

Get started

Guides

Resources

Before you assign

Create an assignment

Change an assignment

Inspect an assignment

Remove an assignment

​Before you assign

​Create an assignment

​Change an assignment

​Inspect an assignment

​Remove an assignment

Before you assign

Create an assignment

Change an assignment

Inspect an assignment

Remove an assignment