Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.autoplay.ai/llms.txt

Use this file to discover all available pages before exploring further.

All callbacks receive typed dataclass instances, not raw dicts. Your IDE will autocomplete every field, and each model has a .to_text() method that returns an embedding-ready string.

​
ActionsPayload

Delivered when the connector forwards a batch of UI actions from a user session. 
from autoplay_sdk import ActionsPayload

def on_actions(payload: ActionsPayload):
    print(payload.session_id)   # identify the session
    print(payload.email)        # tie to a user identity
    print(payload.count)        # number of actions in this batch

    for action in payload.actions:
        print(action.title)
        print(action.description)
        print(action.canonical_url)
        print(action.session_id, action.user_id, action.email)

    # embedding-ready string — pass directly to your embedding API
    text = payload.to_text()
to_text() example output: 
Session ps_abc123 — 3 actions
[0] pageview: User landed on the dashboard page — https://app.example.com/dashboard
[1] click: User clicked Export CSV button — https://app.example.com/dashboard
[2] click: User opened billing settings — https://app.example.com/settings/billing

​
Fields

​
product_id
string
required
Connector product identifier.
​
session_id
string | None
User session identifier. None for anonymous sessions before identity linking.
​
user_id
string | None
External user identifier passed at session boot. None when the session is fully anonymous.
​
email
string | None
User email if available from the identity store.
​
actions
list[SlimAction]
Ordered list of UI actions in this batch. See SlimAction below.
​
count
int
Number of actions in this batch. Equals len(actions).
​
forwarded_at
float
Unix timestamp (float) when the connector forwarded this batch.

​
ActionsPayload.merge(payloads)

Merges a non-empty list of ActionsPayload objects for the same session into one.
  • Actions are concatenated and re-indexed sequentially from 0
  • user_id / email resolved from the first non-None value across all inputs
  • forwarded_at set to the latest timestamp across all inputs
  • Raises ValueError if payloads is empty
merged = ActionsPayload.merge([payload_a, payload_b])
# merged.actions == [*payload_a.actions, *payload_b.actions]  (re-indexed)
# merged.count   == len(merged.actions)
Used internally by AsyncAgentContextWriter when debounce_ms > 0 to combine payloads that arrive within the accumulation window before calling write_actions.

​
SummaryPayload

Delivered when the connector’s LLM summariser produces a prose description of a session. Replaces the raw action list for context-window efficiency in RAG pipelines. 
from autoplay_sdk import SummaryPayload

def on_summary(payload: SummaryPayload):
    print(payload.session_id)
    print(payload.replaces)    # how many actions this summary replaces

    # the prose summary string — pass directly to your embedding API
    text = payload.to_text()
to_text() example output: 
The user navigated to the Dashboard, exported a CSV report, then opened
account settings to update their billing plan.

​
Fields

​
product_id
string
required
Connector product identifier.
​
session_id
string | None
User session identifier.
​
summary
string
Prose description of what the user did during this session.
​
replaces
int
Number of individual actions this summary condenses.
​
forwarded_at
float
Unix timestamp when the connector forwarded this summary.

​
SlimAction

A single UI action inside ActionsPayload.actions. 
for action in payload.actions:
    action.index            # 0, 1, 2 ... position in the session
    action.type             # "pageview", "click", "submit", "type", ...
    action.title            # "Page Load: Dashboard" or "Click Export CSV button"
    action.description      # "User landed on the dashboard page"
    action.timestamp_start  # unix float — when the action began
    action.timestamp_end    # unix float — when the next action began
    action.raw_url          # "https://app.example.com/dashboard?ref=email"
    action.canonical_url    # "https://app.example.com/dashboard"
    action.session_id       # PostHog session id (or None)
    action.user_id          # distinct id / user id (or None)
    action.email            # email from PostHog properties (or None)
    action.to_text()        # "[0] pageview: User landed on the dashboard page — ..."

​
Fields

​
index
int
default:"0"
0-based position of this action in the session sequence.
​
type
string
default:"\"\""
Lowercase event type. One of "pageview", "click", "submit", "type", "focus", "blur".
​
title
string
Human-readable label for the event (e.g. "Page Load: Dashboard" or "Click Export CSV button").
​
description
string
Natural-language description of what the user did (e.g. "User landed on the dashboard page").
​
timestamp_start
float
default:"0.0"
Unix timestamp when this action began.
​
timestamp_end
float
default:"0.0"
Unix timestamp when this action ended (equals the next action’s timestamp_start). For the last action in a batch this equals timestamp_start.
​
raw_url
string
default:"\"\""
Original URL as captured, before canonicalization (includes query strings and fragments).
​
canonical_url
string
Normalised page URL with dynamic path segments collapsed to :id (e.g. https://app.example.com/projects/:id).
​
session_id
string | None
PostHog session id for this action. None when unknown (same semantics as batch-level session_id).
​
user_id
string | None
Distinct id or identified user id for this action. None when anonymous.
​
email
string | None
User email from PostHog identity properties when present.

​
Using .to_text() for embeddings

Both payload types expose .to_text() so you can embed either without branching: 
from autoplay_sdk import ActionsPayload, SummaryPayload

def embed_any(payload: ActionsPayload | SummaryPayload):
    text = payload.to_text()         # works on both types
    embedding = embed_api.encode(text)
    vector_store.upsert(id=payload.session_id, vector=embedding)