Chess Now! IconChess Now
API ReferenceChallenges

Request a challenge

POST
/api/challenge/request/{username}

Requests a new chess challenge to a user by their username. This creates a pending challenge record which, once the target user accepts, starts a match.

Triggers the challenge:request ws event to the target user.

Path Parameters

username*string

Header Parameters

cookie?string
authorization?string
Match^Bearer .*

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/api/challenge/request/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "success": true,  "data": {    "challenge": {      "id": 1,      "createdAt": "2024-01-01T12:00:00Z",      "fromId": "123e4567-e89b-12d3-a456-426614174000",      "toId": "987e6543-e21b-34d5-a678-426614174000",      "challengerColor": "random",      "status": "pending",      "matchId": null,      "from": {        "id": "123e4567-e89b-12d3-a456-426614174000",        "name": "John Doe",        "username": "johndoe",        "createdAt": "2024-01-01T12:00:00Z",        "updatedAt": "2024-01-01T12:00:00Z",        "botOwnerId": null,        "rating": 1200,        "rd": 350,        "vol": 0.06      },      "to": {        "id": "987e6543-e21b-34d5-a678-426614174000",        "name": "Jane Doe",        "username": "janedoe",        "createdAt": "2024-01-01T12:00:00Z",        "updatedAt": "2024-01-01T12:00:00Z",        "botOwnerId": null,        "rating": 1200,        "rd": 350,        "vol": 0.06      },      "ranked": true    }  }}

Get challenge info GET

Retrieves the full details of a specific challenge by its ID, including information about the challenger and the opponent.

Accept a challenge POST

Accepts a pending incoming challenge from another user. After accepting, a new chess match is created between both players. Triggers the `challenge:accepted` ws event to the target user.