API Reference

Key Value

Per-device JSON application data, separate from preferences and available without Developer Mode. Allowed keys: last_file_path, quick_note_draft, recent_searches, recent_save_dirs, chat_input_text:peer:ID and chat_input_text:channel:ID (nonempty ID). Values are shared by clients of the same device.

Data currently stored through Key Value

These are the application data keys currently accepted by keyValue and setKeyValue. The table describes current client value shapes, not server-enforced JSON structures. ID must be nonempty. Values are persistent and shared by clients of the same device; they are not preferences. Missing values return null. The value argument is non-null JSON; null cannot be used to delete a key. Examples describe data structures, not actual saved user content.

KeyJSON value shapePurpose
last_file_path{ rootPath: string, fullPath: string, selectedPath: string }Last file-browser location: root, full path and selected path.
quick_note_draftstringUnsent quick-note text.
recent_searchesstring[]Recent search terms, newest first; list trimming is performed by the client.
recent_save_dirsstring[]Recently selected save or upload directories, newest first; list trimming is performed by the client.
chat_input_text:peer:IDstringUnsent chat text for the peer identified by ID.
chat_input_text:channel:IDstringUnsent chat text for the channel identified by ID.

Type Definitions

graphql
type Mutation {
  setKeyValue(key: String!, value: JSON!): Boolean!
}

type Query {
  keyValue(key: String!): JSON
}

scalar JSON

Operations

mutation

setKeyValue

Persist JSON application data for an allowed Key Value key. Encoded values must not exceed 65,536 bytes. Returns true when changed, false when identical; this API does not change preferences.

graphql
# Save JSON application data up to 65,536 encoded bytes; returns whether the stored value changed.
mutation setKeyValue($key: String!, $value: JSON!) {
  setKeyValue(key: $key, value: $value)
}
query

keyValue

Read JSON application data for an allowed Key Value key. Missing keys return null. This API does not read preferences.

graphql
# Read JSON application data by key; returns null when absent and does not read preferences.
query keyValue($key: String!) {
  keyValue(key: $key)
}