Grails API Documentation

POST /api/v1/watchlist/lists

Create a new named watchlist. Maximum 20 lists per user. List names must be unique per user.

Authentication: Required

Cache: None

Request Body

Field	Type	Required	Description
`name`	string	Yes	List name (1–100 chars, trimmed)

Sample Request


curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.grails.app/api/v1/watchlist/lists \
  -d '{ "name": "My New List" }'

Response


// 201 Created
{
  "success": true,
  "data": {
    "id": 3,
    "name": "My New List",
    "isDefault": false,
    "itemCount": 0,
    "createdAt": "2026-04-08T00:00:00.000Z",
    "updatedAt": "2026-04-08T00:00:00.000Z"
  },
  "meta": {
    "timestamp": "2026-04-08T00:00:00.000Z",
    "version": "1.0.0"
  }
}

Error Responses

Status	Code	Description
400	`LIST_LIMIT_REACHED`	Maximum 20 lists reached
400	`VALIDATION_ERROR`	Invalid request body
409	`DUPLICATE_LIST_NAME`	A list with this name already exists