diff --git a/include/olm/olm.h b/include/olm/olm.h
index 81b6602..3257e53 100644
--- a/include/olm/olm.h
+++ b/include/olm/olm.h
@@ -205,7 +205,21 @@ size_t olm_account_one_time_keys_length(
 );
 
 /** Writes the public parts of the unpublished one time keys for the account
- * into the one_time_keys output buffer. Returns olm_error() on failure.
+ * into the one_time_keys output buffer.
+ * <p>
+ * The returned data is a JSON-formatted object with the single property
+ * <tt>curve25519</tt>, which is itself an object mapping key id to
+ * base64-encoded Curve25519 key. For example:
+ * <pre>
+ * {
+ *     curve25519: {
+ *         "AAAAAA": "wo76WcYtb0Vk/pBOdmduiGJ0wIEjW4IBMbbQn7aSnTo",
+ *         "AAAAAB": "LRvjo46L1X2vx69sS9QNFD29HWulxrmW11Up5AfAjgU"
+ *     }
+ * }
+ * </pre>
+ * Returns olm_error() on failure.
+ * <p>
  * If the one_time_keys buffer was too small then olm_account_last_error()
  * will be "OUTPUT_BUFFER_TOO_SMALL". */
 size_t olm_account_one_time_keys(