Welcome to KGS
Downloading and Installing CGoban, the KGS Client
CGoban Main Window
Introduction to KGS
KGS Plus
KGS on Android™
Terms of Service
Admin Announcements
Newbie FAQ
Main KGS Window
Set Preferences
Server Stats
"New Game" Window
Game Window
Playing Games
Game Types
Supported Rule Sets
Supported Time Systems
Tagged Games
Rating System
Rating System Math
Main FAQ

Information for Help Editors
Resources for Help Editors
Help Discussion
Recent Changes
Translations Available (click a flag to view):
English (United States)

KGS Protocol

KGS uses a binary stream-based protocol to communicate with clients. This is not suitable for use in a Javascript/HTML based client. There is a webapp that translates the KGS protocol into a JSON+HTTP based protocol. The webapp will run on tomcat or any other JSP web server. You can download it from

A reference with all the messages types, and what data they contain, is included in the webapp. A simple example client that lets you test messages is included also.


The webapp needs:

Discussion Mailing List

There is a google group to discuss the KGS protocol and coding clients in it. Please visit!forum/kgs-client-coding if you have any questions about it.

Change log:

  1. jsonClient-2016-03-01T01_02Z.war — Initial release.
  2. jsonClient-2016-03-22T00_25Z.war — Fixed server stats message.
  3. jsonClient-2016-03-23T00_30Z.war — Major cleanup in challenges and proposals, for both the webapp and the documentation.
  4. jsonClient-2016-04-09T20_52Z.war — Fixed crashes when joining a global game list or when leaving a non-game channel.
  5. jsonClient-2016-04-14T23_00Z.war — Fixed crashes when DONESCORING SGF property appeared in a file.
  6. jsonClient-2016-04-16T23_03Z.war — Changed JOIN downstream message to GAME_JOIN, etc., and hopefully fixed crash when joining some games.
  7. jsonClient-2016-04-20T18_02Z.war — Fixed crash problems related to joining games. Changed time from a string to a set of fields. Updated documentation.
  8. jsonClient-2016-04-30T20_45Z.war — More documentation updates. Moved "rules" in a proposal into its own object (upstream and downstream proposals now match).
  9. jsonClient-2016-05-18T23_23Z.war — Added observer count to games in game lists.
  10. jsonClient-2016-05-20T02_02Z.war — Fixed DETAILS_JOIN message handling.
  11. jsonClient-2016-05-21T00_26Z.war — Made the score fields of all downstream messages work the same.
  12. jsonClient-2016-05-24T23_59Z.war — Fixed SGF upload handling. Added a line to force the javascript client to use UTF-8.
  13. jsonClient-2016-05-27T00_49Z.war — Fixed SGF uploading for real.
  14. jsonClient-2016-05-27T23_40Z.war — Fixed "pass" uploads.
  15. jsonClient-2016-05-28T00_44Z.war — Fixed DETAILS_JOIN_REQUEST.
  16. jsonClient-2016-05-29T21_54Z.war — Fixed RESULT SGF properties.
  17. jsonClient-2016-05-31T00_02Z.war — Fixed the automatch problem.
  18. jsonClient-2016-06-02T23_21Z.war — Added "empty" color for ADDSTONE SGF property.
  19. jsonClient-2016-06-06T23_14Z.war — Fixed the upload for the RE[] property.
  20. jsonClient-2016-06-11T03_33Z.war — Fixed AVATAR downstream message.
  21. jsonClient-2016-06-18T17_10Z.war — Added fields to game lists, game summary (archive) lists, and DETAILS_NONEXISTANT.
  22. jsonClient-2016-06-27T03_32Z.war — Fixed GAME_REVIEW message and documentation.
  23. jsonClient-2016-08-22T02_36Z.war — Fixed some documentation issues, fixed GAME_SET_ROLES upstream command.
  24. jsonClient-2016-08-26T02_21Z.war — Fixed handling up archive channel update messages.
  25. jsonClient-2016-09-17T21_43Z.war — Fixed CHALLENGE_CREATE.

Edit this page (requires admin or translator privilege)