Create a brief

POST

/projects/:projectId/briefs

Creates a brief from free-form intent and dispatches a shaping turn. Returns the brief id and a WebSocket ticket for the shaping-log stream. Requires playbook:start on the project.

Authentication

AuthorizationBearer

WorkOS session JWT or an organization API key, sent as Authorization: Bearer <token>.

Path parameters

projectIdstringRequired

Request

This endpoint expects an object.

textstringRequired1-10000 characters

attachedFileIdslist of stringsOptionalDefaults to []

Response

The created brief id and shaping WebSocket ticket.

briefIdstring

wsTicketstring

Signed ticket for the shaping-log WebSocket.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

1	curl -X POST https:/https://api/projects/projectId/briefs \
2	-H "Authorization: Bearer <token>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"text": "Create a detailed project brief for the upcoming marketing campaign targeting Q3, focusing on social media engagement and influencer partnerships."
6	}'

1	{
2	"briefId": "b7f9c8d2-4a3e-4f1a-9c2d-8e5f7a1b2c3d",
3	"wsTicket": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.SGVsbG8gV29ybGQ=.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
4	}