---
title: "Create a challenge"
method: POST
path: "/api/challenge/{username}"
tags: ["Challenges"]
---

# Create a challenge

`POST /api/challenge/{username}`

Challenge someone to play. The targeted player can choose to accept or decline.
If the challenge is accepted, you will be notified on the [event stream](#tag/board/GET/api/board/game/stream/{gameId})
that a new game has started. The game ID will be the same as the challenge ID.
Challenges for realtime games (not correspondence) expire after 20s if not accepted.
To prevent that, use the `keepAliveStream` flag described below.

## Path parameters

- `username` string, required

## Response `200`

The challenge was successfully created.

- ChallengeJson
  - `id` string, required
  - `url` string, uri, required
  - `status` 'created' | 'offline' | 'canceled' | 'declined' | 'accepted', required
  - `challenger` ChallengeUser, required
    - `id` string, required
    - `name` string, required
    - `rating` integer
    - `title` 'GM' | 'WGM' | 'IM' | 'WIM' | 'FM' | 'WFM' | 'NM' | 'CM' | 'WCM' | 'WNM' | 'LM' | 'BOT' — only appears if the user is a titled player or a bot user
    - `flair` string — See [available flair list and images](https://github.com/lichess-org/lila/tree/master/public/flair)
    - `patron` boolean — Use patronColor value instead to determine if player is a patron.
    - `patronColor` integer — Players can choose a color for their Patron wings. See [here for the color mappings](https://github.com/lichess-org/lila/blob/master/ui/lib/css/abstract/_patron-colors.scss). The presence of this field indicates the player is an active Patron.
    - `provisional` boolean
    - `online` boolean
    - `lag` integer
  - `destUser` ChallengeUser, required
    - `id` string, required
    - `name` string, required
    - `rating` integer
    - `title` 'GM' | 'WGM' | 'IM' | 'WIM' | 'FM' | 'WFM' | 'NM' | 'CM' | 'WCM' | 'WNM' | 'LM' | 'BOT' — only appears if the user is a titled player or a bot user
    - `flair` string — See [available flair list and images](https://github.com/lichess-org/lila/tree/master/public/flair)
    - `patron` boolean — Use patronColor value instead to determine if player is a patron.
    - `patronColor` integer — Players can choose a color for their Patron wings. See [here for the color mappings](https://github.com/lichess-org/lila/blob/master/ui/lib/css/abstract/_patron-colors.scss). The presence of this field indicates the player is an active Patron.
    - `provisional` boolean
    - `online` boolean
    - `lag` integer
  - `variant` Variant, required
    - `key` 'standard' | 'chess960' | 'crazyhouse' | 'antichess' | 'atomic' | 'horde' | 'kingOfTheHill' | 'racingKings' | 'threeCheck' | 'fromPosition', required
    - `name` string, required
    - `short` string
  - `rated` boolean, required
  - `speed` 'ultraBullet' | 'bullet' | 'blitz' | 'rapid' | 'classical' | 'correspondence', required
  - `timeControl` union, required
    - object
      - `type` 'clock'
      - `limit` integer
      - `increment` integer
      - `show` string
    - object
      - `type` 'correspondence'
      - `daysPerTurn` integer
    - object
      - `type` 'unlimited'
  - `color` 'white' | 'black' | 'random', required
  - `finalColor` 'white' | 'black'
  - `perf` object, required
    - `icon` string, required
    - `name` string, required
  - `direction` 'in' | 'out'
  - `initialFen` string
  - `rematchOf` string

## Other responses

- `400` — The creation of the challenge failed.

---

[API](https://skmtc.net/lichess/apis/lichess-org-api-reference.md) · [All operations](https://skmtc.net/lichess/apis/lichess-org-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lichess/lichess-org-api-reference/versions/1425db81eb3b/schema)