Create Collab Scene
POST /api/v1/collab-scenes: open a multi-performer scene with per-scene consent collection.
The uploader is the producer. Whoever this call is made for is recorded as the 18 U.S.C. § 2257 primary producer, and Easy2257 is Custodian of Records. Content stays on your platform until the collab_scene.greenlit webhook fires.
Not idempotent. Every call creates a new scene, emails every performer, and charges fees: $5 per scene (500 cents), plus $25 (2500 cents) for each performer who does not already have an active Easy2257 account. Guard it behind your own dedupe key.
Not available on platform-funded accounts yet. If your partner account pays for its creators, this call returns 409 with code collab_scenes_not_available_on_platform_pays before anything is created: the fees above are charged to the uploader's card, and a platform-funded creator has none. Log each creator's own uploads through POST /api/v1/solo-accounts/{accountId}/content; for scenes with more than one creator, ask Easy2257 before launch.
Authorization
BearerAuth Partner API key from partner.easy2257.com/api-keys. Only ez_live_ keys are accepted. A key beginning with ez_test_ is rejected with 403 and code TEST_MODE_UNAVAILABLE before any handler runs: there is no sandbox, and every handler writes production records, provisions real users, and sends real email. New partner accounts start with a test key, so create a live key before your first call.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://easy2257.com/api/v1/collab-scenes" \ -H "Content-Type: application/json" \ -d '{ "title": "April 2026 Scene", "performers": [ { "email": "performer@example.com" } ], "uploaderAttestation": { "ip": "203.0.113.7", "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...", "clickedAt": "2026-04-24T18:00:00Z", "attestationText": "I coordinated this scene, all performers were 18+ and consented on set" }, "callbackUrl": "https://your-platform.com/webhooks/ez2257" }'{
"sceneId": "cmd5r9a4t0001qz8hb6k2m3xd",
"status": "pending_signatures",
"performers": [
{
"email": "performer@example.com",
"status": "pending_consent"
}
],
"fees": {
"sceneFeeCents": 500,
"onboardingFeeCents": 2500,
"totalCents": 3000,
"charged": true,
"stripeChargeId": "pi_3NabcDEfghIJklmn",
"chargeError": null
},
"expiresAt": "2026-05-08T18:00:00Z"
}{
"error": "email, externalUserId, and callbackUrl are required",
"code": "missing_parameter",
"field": "contentType"
}{
"error": "email, externalUserId, and callbackUrl are required",
"code": "missing_parameter",
"field": "contentType"
}{
"error": "email, externalUserId, and callbackUrl are required",
"code": "missing_parameter",
"field": "contentType"
}{
"error": "Too many requests. Please slow down.",
"retryAfter": 14,
"limit": 60,
"remaining": 0,
"reset": 1714000060000
}{
"error": "email, externalUserId, and callbackUrl are required",
"code": "missing_parameter",
"field": "contentType"
}