Skip to main content

​
What is a session?

A session is the complete telemetry record of one candidate’s assessment. It contains an immutable event log of everything captured during the session: prompts, AI tool calls, file changes, commands, test runs, and architecture decisions.

​
Session object fields

​
string
Session UUID.
​
string
The AI tool the candidate used, e.g. claude-code, codex, cursor.
​
string
ISO 8601 timestamp of when the session started.
​
string | null
ISO 8601 timestamp of when the candidate ran promptster done, or null if the session has not ended.
​
string | null
ISO 8601 timestamp of the most recent event captured.
​
integer
Total number of events captured in the session.
​
integer
Number of architecture decisions captured during the session.
​
number | null
Estimated percentage of file changes attributed to the AI tool. null if attribution has not been computed yet.
For API endpoints to list, get, and delete sessions, see the Sessions API reference.

​
Timeline and events

The timeline is the ordered, immutable log of every event captured during a session. Each event has a kind field that identifies what it represents. Every event shares a common envelope with id, sessionId, kind, ts, data (event-specific payload), and provenance (attribution metadata). For the full timeline API, see GET /v1/sessions/:id/timeline.

​
Provenance and attribution

The provenance object on each event describes how the change came to exist.
Attribution is not a binary “AI wrote this / human wrote this” judgment. Promptster tracks provenance with confidence levels. A high likely_ai attribution with the candidate verifying and committing the result is normal and expected — prompting well is the work.

​
Reviewing decisions

When a candidate makes a significant architectural choice — switching a queue model, redesigning a schema, choosing between implementation approaches — Promptster captures their rationale as a decision_event. These are the highest-signal artifacts in a session. Unlike file diffs or commands, decisions represent the candidate’s reasoning, not just their actions. They answer the question: does this candidate think about tradeoffs, or just implement the first idea that works? Each decision includes a title, chosenOption, context, tradeoffs, rationale, and impactScore (1–5). For the full field reference, see GET /v1/sessions/:id/decisions.

​
What to look for

Decision count and significance — did the candidate capture meaningful tradeoffs, or only trivial ones? A session with high-impact changes and zero decisions may indicate the candidate is not thinking about consequences. Rationale quality — is the reasoning substantive? “I chose Postgres because it’s familiar” is thin. “I chose Postgres because this data is relational and we need strong consistency guarantees for the billing path; the tradeoff is schema rigidity if requirements change” is strong. Missed decisions — any decision with missedDecision: true was detected by Promptster but not explicitly documented by the candidate. These are worth probing in a follow-up interview. Tradeoff awareness — does the candidate acknowledge what they gave up? Recognizing that a choice has costs — even if the costs are acceptable — signals mature engineering judgment.
Candidates using promptster explain can document decisions at any point during the session. High-quality rationale — acknowledging tradeoffs and reasoning about reversibility — is a strong positive signal.