Interviews API
An interview is one recorded AI session for one trader. Create it, send the link, read the report, record your decision.
Lifecycle#
created (link sent) then consented, in_progress (recording), submitted (trader finished) and report_ready (awaiting your decision). failed means the latest report generation could not complete; a previous completed report remains available. expired is computed from expires_at for links never started. The decision (approved, rejected, needs_review) is independent of the status.
The interview object#
List endpoints return InterviewListItem. The detail endpoint returns InterviewDetail, which extends it.
| Field | Type | Description |
|---|---|---|
id | uuid | Interview identifier. |
trader | object | Trader id, name, email, external_id. |
status | SessionStatus | One of created, consented, in_progress, submitted, report_ready, failed. |
expired | boolean | True when the invite expired before the trader started. |
language | string | null | Interview language code. |
risk_score | low | medium | high | null | Set once the report is ready. |
recommended_step | approve | human_review | reject_escalate | null | The AI recommendation. |
decision | approved | rejected | needs_review | null | Analyst decision, with decided_at. |
assigned_to | object | null | Analyst id and name. |
media | MediaSummary[] | Per track (webcam, screen, mic): status, duration_ms, error. |
created_at, started_at, submitted_at, expires_at | timestamp | Key moments of the session. |
communication_done_at | timestamp | null | When your team closed the loop with the trader. |
sort_at | timestamp | Last activity, used for the default ordering. |
Detail only fields
| Field | Type | Description |
|---|---|---|
report | Report | null | The AI assessment, see below. |
answers | Answer[] | Transcript: question_text, answer_text, answer_english, input_mode, speech timings. |
events | IntegrityEvent[] | Integrity signals with type and offset_ms from recording start. |
activity_summary | ActivitySummary | null | Observed trading statistics and generic review signals with hard or soft severity. Percentages use a 0-100 scale. |
activity_source | auto | csv | dev_fixture | null | Where the activity came from. |
assessment_context | AssessmentContext | Assessment scope, evidence availability and source, historical comparison applicability, and limitations. |
evidence_revision | integer | Current evidence revision. A report with a different revision remains visible with is_stale until recalculated. |
environment | production | sandbox | Sandbox sessions are short and not billed. |
capture_mode | desktop | mobile | Capture mode of the session. |
duration_ms, ip_address, user_agent, start_connection_mbps | mixed | Session facts. |
technical_analysis | object | enabled, symbol, date, transcript of the chart narration. |
decision_detail | object | Decision, AI assessment, error direction, reasons, confirmed behaviors, note, decider. |
share | object | Share link state: active, url, expires_at. |
invite | object | url, expires_at, opened. |
trader_rating, trader_feedback | number | string | null | What the trader said about the experience. |
redo_of_session_id | uuid | null | Set on retakes. |
Report
assessment_context states the verdict's scope and the evidence used. In pre_trading, approval recommends admission to evaluation and does not validate past performance. decision_reasons gives public explanations and review actions. Historical comparisons that cannot be performed remain unevaluated. is_stale and refresh_failed identify a retained report awaiting or failing recalculation.
{
"summary": "The AI recommends a human review before a decision.",
"answers_summary": null,
"risk_score": "medium",
"recommended_step": "human_review",
"reason": null,
"activity_label": "one_sided",
"bullets": [],
"verdicts": { "third_party": "clear", "cross_account": "likely", "gamification": "suspected" },
"flags": [],
"risk_synthesis": null,
"assessment": {
"consistency": { "coherent": 3, "inconsistent": 1, "unresolved": 1 },
"observations": [
{ "status": "coherent", "dimension": "Strategy ownership", "trading_evidence": "One login places the trades.", "interview_evidence": "Only the trader places the trades." }
]
},
"generated_at": "2026-09-23T11:42:10Z",
"decision_trace": null
}Each verdict is clear, suspected or likely. The assessment.consistency counts summarize evaluated cross-check outcomes. assessment.observations lists each one with its subject and the interview and trading evidence. assessment is null when no results are available. These counts are not a probability or confidence score.
Reports contain the final recommendation and observed outcomes. Legacy prose fields remain null, and bullets and flags remain empty arrays for compatibility. Activity signals use rule: "trading_review" with an empty detail.
Endpoints#
GET/v1/interviewsinterviews:read
Returns InterviewPage
Paginated list with organization wide KPIs. Status counts cover all unarchived interviews regardless of pagination or list filters; each interview belongs to exactly one status count. completed counts reviewed reports with status report_ready and a recorded analyst decision.
| Query | Type |
|---|---|
page, limit | number |
status | SessionStatus, active or expired |
risk | low | medium | high |
decision | Decision or pending |
search | string |
assigned_to | uuid, me or unassigned |
trader_id | uuid |
archived | boolean |
sort | date | created | activity | trader | status | risk | recommended_step | decision | media | duration |
order | asc | desc (default desc) |
Without sort, interviews are ordered by last activity (sort_at), newest first. sort=date orders by the date shown in the dashboard: submitted, else started, else created.
{ "total": 412, "invited": 100, "in_progress": 3, "processing": 8, "awaiting_review": 11, "decided_7d": 38, "completed": 286, "failed": 4, "approval_rate_30d": 0.71, "avg_duration_min": 21.4 }POST/v1/interviewsinterviews:create
Returns InterviewCreated
| Field | Type | Description |
|---|---|---|
trader_id | uuid | null | An existing trader. |
trader | object | null | Or inline: full_name, email, external_id. |
account_id | uuid | null | Focus the interview on one trading account. |
activity_file_expected | boolean | Set true when an activity file will be uploaded after creation. The assessment remains pending until the import is resolved. |
analyst_guidance | string | null | Private instructions for the interviewer and the report. |
window_hours | number | null | Link validity, clamped to 1 to 720 hours. Defaults to the organization setting, or 72 hours. |
technical_analysis | object | null | enabled, with both symbol and date (YYYY-MM-DD) required when enabled. |
sandbox | boolean | Short, unbilled test session. |
Returns interview, invite_url and expires_at. The invite URL is also available in the detail response while the interview is still in the created state.
GET/v1/interviews/{id}interviews:read
Returns InterviewDetail
POST/v1/interviews/{id}/decisioninterviews:decide
Returns InterviewDetail
| Field | Type | Description |
|---|---|---|
decision | approved | rejected | needs_review | Required. |
ai_assessment | correct | partially | wrong | null | How right the AI was. |
error_direction | over_flagged | under_flagged | null | When the AI was wrong. |
ai_error_reasons | string[] | Why the AI was wrong. |
confirmed_behaviors | string[] | Behaviors your team confirmed. |
reason, note | string | null | Decision reason and internal note. |
needs_review_reason | string | null | What is still open. |
POST/v1/interviews/{id}/reissue
Returns { invite_url, expires_at }
Issues a fresh invite link before the trader started, optionally with a new window_hours. The previous link stops working.
POST/v1/interviews/{id}/retake
Returns InterviewCreated
Creates a new interview for the same trader, linked through redo_of_session_id.
POST/v1/interviews/{id}/regenerate
Returns { queued: boolean }
Queues a new report, for example after uploading an activity file.
POST/v1/interviews/{id}/playbackinterviews:read
Returns Playback
Returns short lived signed HLS and DASH URLs per track, plus expires_at (unix seconds) and refresh_after_ms. Call it again before expiry to keep playing without losing the position. Tracks whose status is not ready are still processing: poll every 12 seconds.
GET/v1/interviews/{id}/subtitlesinterviews:read
Returns text/vtt
WebVTT captions. Answers 404 until built.
POST/v1/interviews/{id}/subtitles
Returns { queued: boolean }
POST/v1/interviews/{id}/activity-file
Returns InterviewDetail
Multipart upload with a file field: a CSV, TSV, XLSX, XLS or ODS trade export up to 8 MB, used when no integration covers the account. Column order and common regional formats are detected automatically. Review activity_summary.importDiagnostics and sheets for missing values or excluded rows; a successful upload can contain a partial analysis.
curl https://api.rubikyt.com/v1/interviews/$ID/activity-file \
-H "Authorization: Bearer $RUBI_API_KEY" \
-F "file=@trades.csv"POST/v1/interviews/{id}/activity-file/preview
Returns ActivityImportPreview
Upload the multipart file to inspect its columns, sample rows and provisional analysis. Returns an organization-scoped import_id that expires after 24 hours. Status is ready, needs_mapping or invalid. The committed dataset is retained until confirmation.
POST/v1/interviews/{id}/activity-file/confirm
Returns InterviewDetail
Send import_id and the validated mappings from the preview. Confirm initial positions and same-time ordering only when established by the source. Missing source information requires a fuller export. Confirmation increments the evidence revision and queues a report refresh for completed interviews; analyst decisions are preserved.
DELETE/v1/interviews/{id}/activity-file/preview/{import_id}
Returns InterviewDetail
Cancel an unconfirmed preview and restore the previous dataset or the verified absence-of-history context.
GET/v1/interviews/{id}/activity-file
Downloads the uploaded activity file.
POST/v1/interviews/{id}/assign
Returns InterviewDetail
Body { "user_id": "uuid" }, or null to unassign.
PATCH/v1/interviews/{id}/communication
Returns InterviewDetail
Body { "done": true } marks that the outcome was communicated to the trader.
PATCH/v1/interviews/{id}/archiveinterviews:decide
Returns InterviewDetail
Body { "archived": true } moves the interview to the archive; false restores it. Reports and recordings remain accessible. Archive status does not change evaluated usage.