 API = (obj) ->
     # obj could be message version 1 or 2!
     exports.api_messages[obj.event] = true
+
+###
+
+API messages
+
+These options appear on all API messages:
+- event: the command to be executed, for example "ping"
+- id: uuid for the API call, will be returned in response. If id not provided
+  in the API message, a random id will be generated and returned in the response
+
+Additional notes:
+- Options with default of "undefined" may be omitted.
+- A valid API key is required on all API calls, including ping.
+- The structure of the response to each API message is given in the
+  immediately following "message" object definition.
+- Some API messages, for example "query" and "get_usernames", require
+  options to be passed as a JSON object, as noted in message comments.
+- If JSON is not required for API message options, it is still valid.
+- If API message options are sent as JSON, the message must be sent with
+  a request header of "Content-Type: application/json".
+
+###
 
 ############################################
 # Compute server messages

    password       : required
    agreed_to_terms: required
    token          : undefined   # only required when token is set.

message
    event      : 'account_created'

# Information about several projects or accounts
#############################################

API message2
    event       : 'get_usernames'
    id          : undefined
    account_ids : required
    desc        : """
Get first and last names for a list of account ids

Note: Options for the 'get_usernames' API message must be sent as JSON object.

Example:
  curl -u sk_abcdefQWERTY090900000000: -H "Content-Type: application/json" \
    -d '{"account_ids":["cc3cb7f1-14f6-4a18-a803-5034af8c0004","9b896055-920a-413c-9172-dfb4007a8e7f"]}' \
    https:// cocalc.com/api/v1/get_usernames
  ==>  {"event":"usernames",
        "id":"32b485a8-f214-4fda-a622-4dbfe0db2b9c",
        "usernames": {
           "cc3cb7f1-14f6-4a18-a803-5034af8c0004":{"first_name":"John","last_name":"Smith"},
           "9b896055-920a-413c-9172-dfb4007a8e7f":{"first_name":"Jane","last_name":"Doe"}}}
"""

message
    event       : 'usernames'
