Introduction

Codewars API v1 is minimal and inconsistent. It was never actively developed.

API v2 is planned, but there's no ETA at the moment.

Authentication

Not required. API v1 endpoints are all public.

Content-Type

API v1 endpoints responds with JSON (application/json).

Users API

Get User

Returns a user information.

curl https://www.codewars.com/api/v1/users/some_user

Response

{
  "username": "some_user",
  "name": "Some Person",
  "honor": 544,
  "clan": "some clan",
  "leaderboardPosition": 134,
  "skills": [
    "ruby",
    "c#",
    ".net",
    "javascript",
    "coffeescript",
    "nodejs",
    "rails"
  ],
  "ranks": {
    "overall": {
      "rank": -3,
      "name": "3 kyu",
      "color": "blue",
      "score": 2116
    },
    "languages": {
      "javascript": {
        "rank": -3,
        "name": "3 kyu",
        "color": "blue",
        "score": 1819
      },
      "ruby": {
        "rank": -4,
        "name": "4 kyu",
        "color": "blue",
        "score": 1005
      },
      "coffeescript": {
        "rank": -4,
        "name": "4 kyu",
        "color": "blue",
        "score": 870
      }
    }
  },
  "codeChallenges": {
    "totalAuthored": 3,
    "totalCompleted": 230
  }
}

HTTP Request

https://www.codewars.com/api/v1/users/{user}

Path Parameters

Parameter	Description
`user`	Username or ID

User Object

Field	Type	Description
`username`	`string`	Username of the user.
`name`	`string`	Name of the user.
`honor`	`number`	Total honor points earned by the user.
`clan`	`string`	Name of the clan.
`leaderboardPosition`	`number`	The user's position on the overall leaderboard.
`skills`	`string[]`	Array of skills entered by the user.
`ranks`	`object`	Ranks object with overall and language ranks.
`codeChallenges`	`object`	Object with fields `totalAuthored` and `totalCompleted` for the number of authored and completed kata respectively.

Ranks Object

Field	Type	Description
`overall`	`object`	Overall rank.
`languages`	`object`	Ranks for each language trained.

Rank Object

Field	Type	Description
`rank`	`number`	Rank in integer. `[-8, -1]` maps to kyu, `[1, 8]` maps to dan.
`name`	`string`	Either `{-rank} kyu` or `{rank} dan`.
`color`	`string`	The color of the rank. Possible colors are `white` (7-8 kyu), `yellow` (5-6 kyu), `blue` (3-4 kyu), `purple` (1-2 kyu), `black` (1-4 dan), and `red` (5-8 dan).
`score`	`number`	The total score earned. This is the number that determines the rank.

List Completed Challenges

Lists challenges completed by a user, 200 items per page. Use page parameter (zero based) to paginate.

curl http://www.codewars.com/api/v1/users/some_user/code-challenges/completed?page=0

Response

{
  "totalPages": 1,
  "totalItems": 1, 
  "data": [
    {
      "id": "514b92a657cdc65150000006",
      "name": "Multiples of 3 and 5",
      "slug": "multiples-of-3-and-5",
      "completedAt": "2017-04-06T16:32:09Z",
      "completedLanguages": [ 
        "javascript",
        "coffeescript",
        "ruby",
        "javascript",
        "ruby",
        "javascript",
        "ruby",
        "coffeescript",
        "javascript",
        "ruby",
        "coffeescript"
      ]
    }
  ]
}

HTTP Request

https://www.codewars.com/api/v1/users/{user}/code-challenges/completed?page={page}

Path Parameters

Parameter	Description
`user`	Username or ID

Query Parameters

Parameter	Description	Default
`page`	The page offset. Each page contains at most 200 items.	0

CompletedChallenge Object

Field	Type	Description
`id`	`string`	ID of the kata.
`name`	`string`	Name of the kata.
`slug`	`string`	Slug of the kata.
`completedAt`	`string`	Date and time of the completion.
`completedLanguages`	`string[]`	Array of languages a user completed in.

List Authored Challenges

List challenges authored by the user.

curl http://www.codewars.com/api/v1/users/some_user/code-challenges/authored

Response

{
  "data": [
    {
      "id": "5571d9fc11526780a000011a",
      "name": "The builder of things",
      "description": "For this kata you will be using some meta-programming ...",
      "rank": -3,
      "rankName": "3 kyu",
      "tags": [
        "Algorithms",
        "Metaprogramming",
        "Programming Paradigms",
        "Advanced Language Features",
        "Fundamentals",
        "Domain Specific Languages",
        "Declarative Programming"
      ],
      "languages": ["ruby", "javascript", "python", "coffeescript"]
    },
    {
      "id": "51ba717bb08c1cd60f00002f",
      "name": "Range Extraction",
      "description": "A format for expressing an ordered list of integers ...",
      "rank": -4,
      "rankName": "4 kyu",
      "tags": [
        "Algorithms",
        "String Formatting",
        "Formatting",
        "Logic",
        "Strings"
      ],
      "languages": [
        "javascript",
        "coffeescript",
        "ruby",
        "go",
        "python",
        "java",
        "haskell",
        "csharp",
        "cpp"
      ]
    }
  ]
}

HTTP Request

https://www.codewars.com/api/v1/users/{user}/code-challenges/authored

Path Parameters

Parameter	Description
`user`	Username or ID

AuthoredChallenge Object

Field	Type	Description
`id`	`string`	ID of the kata.
`name`	`string`	Name of the kata.
`description`	`string`	Description of the kata in Markdown.
`rank`	`number?`	Rank of the kata if approved.
`rankName`	`string?`	Rank name of the kata if approved.
`tags`	`string[]`	Array of tags associated with the kata.
`languages`	`string[]`	Array of language names the kata is available in.

Code Challenges API

Get Code Challenge

Return a code challenge information.

curl https://www.codewars.com/api/v1/code-challenges/valid-braces

Response

{
  "id": "5277c8a221e209d3f6000b56",
  "name": "Valid Braces",
  "slug": "valid-braces",
  "url": "http://www.codewars.com/kata/valid-braces",
  "category": "algorithms",
  "description": "Write a function called `validBraces` that takes a string ...",
  "tags": ["Algorithms", "Validation", "Logic", "Utilities"],
  "languages": ["javascript", "coffeescript"],
  "rank": {
    "id": -4,
    "name": "4 kyu",
    "color": "blue"
  },
  "createdBy": {
    "username": "xDranik",
    "url": "http://www.codewars.com/users/xDranik"
  },
  "approvedBy": {
    "username": "xDranik",
    "url": "http://www.codewars.com/users/xDranik"
  },
  "totalAttempts": 4911,
  "totalCompleted": 919,
  "totalStars": 12,
  "voteScore": 512,
  "publishedAt": "2013-11-05T00:07:31Z",
  "approvedAt": "2013-12-20T14:53:06Z"
}

HTTP Request

https://www.codewars.com/api/v1/code-challenges/{challenge}

Path Parameters

Parameter	Description
`challenge`	ID or slug

CodeChallenge Object

Field	Type	Description
`id`	`string`	ID of the kata.
`name`	`string`	Name of the kata.
`slug`	`string`	Slug of the kata.
`url`	`string`	URL of the kata.
`category`	`string`	Category of the kata.
`description`	`string`	Description of the kata in Markdown.
`tags`	`string[]`	Array of tags associated with the kata.
`languages`	`string[]`	Array of language names the kata is available in.
`rank`	`object?`	Object describing the rank of the kata if approved.
`createdBy`	`object`	The author of the kata.
`publishedAt`	`string`	Date and time when the kata was first published.
`approvedBy`	`object?`	The approver of the kata.
`approvedAt`	`string`	Date and time when the kata was approved.
`totalCompleted`	`number`	Total number of completions.
`totalAttempts`	`number`	Total number of attempts.
`totalStars`	`number`	The number of bookmarks.
`voteScore`	`number`	The sum of all votes casted.
`contributorsWanted`	`boolean`	Whether to allow contributions.
`unresolved`	`object`	Object with fields `issues` and `suggestions` for the number of unresolved issues and suggestions respectively.

User Object

Field	Type	Description
`username`	`string`	Username of the user.
`url`	`string`	URL of the user's profile.

Webhooks

Webhooks allows you to receive notifications when events occur.

Like API v1, webhooks feature was never actively developed and poorly documented. It's not very usable at the moment.

Structure

Sample Event (Code Challenge Created)

User-Agent: Codewars Hookbot
Content-Type: application/json
X-Webhook-Event: code_challenge
X-Webhook-Secret: some-shared-secret

{
  "action": "created",
  "code_challenge": {
    "id": "50654ddff44f800200000001",
    "created_by_id": "508f2708b3be0c0200000002"
  }
}

When an event occurs in the Codewars system, any relevant webhooks will be triggered to the specified URL. Typically, events are categorized into event and actions. Typically an event references what type of model (i.e. code_challenge) and the action references what happened to it (i.e. created).

Webhooks typically contain a very small payload (often times, it only contains the id of some object). You may need to query the rest of the API to get more information about a particular object.

Register your Webhook

Webhook Ping Event

User-Agent: Codewars Hookbot
Content-Type: application/json
X-Webhook-Event: webhook

{
  "action": "updated",
  "webhook": {
    "id": "53aa3f265b97485984000001"
  }
}

Visit your Codewars account page and add a webhook. A webhook takes the following input:

Input	Meaning
Payload URL	The server endpoint that will relieve the webhook payload (e.g, `https://example.com/my/endpoint`)
Secret	An optional secret shared between you and our webhook service. Ensures only Codewars is sending you the webhook

Once you create or update your webhook, your endpoint will receive a webhook updated event.

Code Challenges

Sample Webhook Payload

User-Agent: Codewars Hookbot
Content-Type: application/json
X-Webhook-Event: code_challenge

{
  "action": "<action - i.e. 'created'>",
  "code_challenge": {
    "id": "53aa3f265b97485984000001",
    "created_by_id": "53af25145b97487568000001"
  }
}

The solution_finalized also includes the following json:

{
  "solution": {
    "id": "53aa3f265b97485984000001",
    "user_id": "53417de006654f4171000587"
  }
}

The following actions are supported:

Action	Meaning
`created`	Code challenge was created
`approved`	A code challenge was successfully approved (no longer in beta state)
`voted`	Someone voted on the code challenge. Does not specify what type of vote.
`solution_finalized`	Someone submitted a solution to the code challenge

User

Webhook Headers

User-Agent: Codewars Hookbot
Content-Type: application/json
X-Webhook-Event: user

rank_earned Event

{
  "action": "rank_earned",
  "user": {
    "id": "53aa3f265b97485984000001",
    "rank": -5
  },
  "language": null
}

honor_changed Event

{
  "action": "honor_changed",
  "user": {
    "id": "53aa3f265b97485984000001",
    "honor": 420,
    "honor_delta": 3
  }
}

The following actions are supported:

Action	Meaning
`rank_earned`	The user's rank has been upgraded. Could be a global rank, or a language rank
`honor_changed`	The user's honor has changed (usually in a positive direction)

Errors

Codewars uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with Codewars' servers.

Error Code	Meaning
400	Bad Request -- Something went wrong
401	Unauthorized -- Your API key is wrong
403	Forbidden -- You do not have permission to access this resource
404	Not Found -- The specified resource could not be found
405	Method Not Allowed -- You tried to access a resource with an invalid method
406	Not Acceptable -- You requested a format that isn't json
422	Unprocessable Entity -- Your input failed validation.
429	Too Many Requests -- You're making too many API requests.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.