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.

​
Listing sessions

GET /v1/sessions Returns a paginated list of sessions for your organization. Filter by assessment to see only the candidates you’re reviewing.

​
Query parameters

​
assessmentId
string
Filter to sessions linked to a specific assessment. Recommended — without this filter, the response includes sessions from all assessments in your organization.
​
sourceService
string
Filter by the AI tool the candidate used, e.g. claude-code or cursor.
​
limit
integer
default:"20"
Number of sessions to return. Maximum is 100.
​
offset
integer
default:"0"
Number of sessions to skip. Use with limit for pagination.

​
Example request

curl "https://api.promptster.ai/v1/sessions?assessmentId=ASSESSMENT_ID&limit=20" \
  -H "Authorization: Bearer <your-token>"

​
Example response

{
  "sessions": [...],
  "total": 42,
  "limit": 20,
  "offset": 0
}

​
Session object fields

​
id
string
Session UUID.
​
sourceService
string
The AI tool the candidate used, e.g. claude-code, cursor.
​
startedAt
string
ISO 8601 timestamp of when the session started.
​
endedAt
string | null
ISO 8601 timestamp of when the candidate ran promptster done, or null if the session has not ended.
​
lastActivityAt
string | null
ISO 8601 timestamp of the most recent event captured.
​
eventCount
integer
Total number of events captured in the session.
​
decisionFlagCount
integer
Number of architecture decisions captured during the session.
​
aiAttributionPct
number | null
Estimated percentage of file changes attributed to the AI tool. null if attribution has not been computed yet.

​
Getting a single session

GET /v1/sessions/:id Returns the full session object for the given session ID. 
curl "https://api.promptster.ai/v1/sessions/SESSION_ID" \
  -H "Authorization: Bearer <your-token>"

​
Deleting a session

DELETE /v1/sessions/:id Hard-deletes the session and all associated data from Promptster. 
curl -X DELETE "https://api.promptster.ai/v1/sessions/SESSION_ID" \
  -H "Authorization: Bearer <your-token>"
Returns { "ok": true, "id": "<session-id>" } on success.
Session deletion is permanent and cannot be undone. All timeline events, artifacts, and scores for the session are removed.