Skip to main content
The raw JSON Schema is available at already.so/schema. The Already Session Schema defines the canonical format for sessions. A session document has 6 top-level fields:
FieldRequiredDescription
versionYesSchema version ("1.0")
sessionYesSession metadata
timelineYesCapture events
mediaNoMedia files
commentsNoDiscussion
notesNoRich text notes

​
Session metadata

Session identity, timestamps, recording configuration, environment, and project management.
​
id
string (uuid)
required
Session identifier
​
createdAt
string (date-time)
required
Creation timestamp
​
endedAt
string (date-time)
End timestamp
​
duration
number
Duration in seconds
​
title
string
Session title
​
description
string
Session description
​
status
string
One of: in_session, uploading, todo, in_progress, needs_feedback, done, cancelled
​
assigneeId
string
Assignee identifier
​
assigneeUsername
string
Assignee username
​
labels
string[]
Label names
​
priority
integer
1 (highest) to 5 (lowest)
​
platform
string
One of: electron, web, ios, android
​
platformVersion
string
Platform version string
​
hasVideo
boolean
Whether session includes video
​
hasAudio
boolean
Whether session includes audio
​
videoCodec
string
One of: h264, h265, vp9, av1
​
resolutionWidth
integer
Video width in pixels
​
resolutionHeight
integer
Video height in pixels
​
fps
number
Frames per second
​
os
string
Operating system (e.g. macOS, Windows, iOS, Android)
​
osVersion
string
OS version string
​
device
string
Device name (e.g. MacBook Pro 16-inch, iPhone 15 Pro)
​
screenWidth
integer
Screen width in pixels
​
screenHeight
integer
Screen height in pixels
​
screenScale
number
Screen scale factor (e.g. 2 for Retina)
​
teamId
string
Team identifier
​
createdBy
string
Creator identifier

​
Timeline events

Capture events recorded during the session, sorted by timestamp. Every event has timestamp + type. Other fields depend on the event type.

​
Event types

window_focus, page_navigation, screen_change, app_state,
keystroke, text_typed, text_selected,
mouse_click, click, touch,
snapshot, annotation,
transcription,
recording_started, recording_ended,
console_error, network_request

​
Common fields

These fields are present on most events:
​
timestamp
number
required
Seconds from session start
​
type
string
required
Event type (see list above)
​
text
string
Text content. Used by: text_typed, transcription, annotation, console_error
​
x
number
X coordinate. Used by: mouse_click, click, touch, annotation
​
y
number
Y coordinate. Used by: mouse_click, click, touch, annotation
​
url
string
URL. Used by: page_navigation, click, annotation, console_error, network_request
​
mediaRef
string
ID of a media item. Used by: snapshot, annotation

​
Type-specific fields

​
appName
string
Application name (window_focus)
​
windowTitle
string
Window title (window_focus)
​
bundleId
string
macOS bundle ID or Windows process name (window_focus)
​
display
integer
Display index (window_focus)
​
title
string
Page title (page_navigation)
​
referrer
string
Referrer URL (page_navigation)
​
screenName
string
Current screen/activity (screen_change)
​
previousScreen
string
Previous screen (screen_change)
​
state
string
foreground or background (app_state)
​
key
string
Key identifier (keystroke)
​
button
string
left, right, or middle (mouse_click)
​
selectedText
string
Text highlighted by the user (text_selected)
​
elementPath
string
CSS selector path (click, annotation)
​
element
string
HTML tag name (click, annotation)
​
elementText
string
Visible text of the element (click, annotation)
​
boundingBox
object
Element bounding box with x, y, width, height (click, annotation)
​
reactComponents
string
React component tree (click, annotation)
​
cssClasses
string
Element class list (click, annotation)
​
accessibility
string
ARIA info (click, annotation)
​
nearbyText
string
Text around the element (click, annotation)
​
isFixed
boolean
Fixed/sticky positioning (click, annotation)
​
gesture
string
One of: tap, double_tap, long_press, swipe, pinch, rotate (touch)
​
points
number[][]
Multi-touch points as [[x,y], ...] (touch)
​
start
number
Audio start time in seconds (transcription)
​
end
number
Audio end time in seconds (transcription)
​
level
string
error, warn, or info (console_error)
​
stack
string
Stack trace (console_error)
​
method
string
HTTP method (network_request)
​
status
integer
HTTP status code (network_request)
​
duration
number
Request duration in ms (network_request)

​
Media

Media files (video, audio, images) associated with the session. Referenced by timeline events via mediaRef.
​
id
string
required
Media identifier, referenced by timeline events
​
type
string
required
One of: video, audio, image
​
filename
string
required
File name
​
category
string
One of: recording, snapshot, annotation, smart, pasted, converted
​
mimeType
string
MIME type
​
cloudUrl
string
Cloud storage URL
​
width
integer
Width in pixels
​
height
integer
Height in pixels
​
duration
number
Duration in seconds (video/audio)
​
sizeBytes
integer
File size in bytes
​
createdAt
string (date-time)
Creation timestamp

​
Comments

Threaded discussion on the session.
​
id
string
required
Comment identifier
​
createdAt
string (date-time)
required
Creation timestamp
​
authorId
string
required
Author identifier
​
body
string
required
Comment text
​
updatedAt
string (date-time)
Last update timestamp
​
authorUsername
string
Author username
​
parentId
string
Parent comment ID for threaded replies

​
Notes

Rich-text notes. Content is an array of nodes (paragraphs, headings, images, etc.) in Tiptap JSON format.
​
content
object[]
Array of content nodes, each with a required type field (e.g. paragraph, heading, image)