Dashboard onboarding
Project-shared walkthrough state for authenticated enterprise dashboards.
These additive HTTP endpoints power the default project’s Get started in hosted and authenticated self-host dashboards. They require a login-session Bearer token and organization ownership of the project. Agent API keys cannot manage onboarding state. Existing publish, search, evaluation, and experiment APIs are unchanged.
The base path is /api/projects/{project_id}/onboarding.
| Method and path | Body | Result |
|---|---|---|
GET (base path) | None | Current status and linked evidence |
POST /start | { "fresh": false } | Idempotently initialize the example |
POST /start | { "fresh": true } | Start a new run; preserve earlier example records |
POST /refresh | None | Reconcile persisted evidence and save milestones |
PATCH (base path) | An acknowledgment below | Update shared UI progress |
Use the base path without a trailing slash. All responses contain project_id, eligible, run, steps, project_empty, show_full, core_complete, learning_status, learnings, evaluation_id, evaluation, evaluation_enabled, active_experiment_id, and prerequisites. Each step has id, complete, state (complete, ready, waiting, or blocked), reason_code, and an actionable reason.
eligible is true only for the workspace’s default project. Other projects return eligible: false, run: null, and an empty steps list; starting a run there returns 404. Additional projects do not repeat onboarding.
evaluation contains the verified example evaluation’s dashboard view, without embeddings, or null. It remains available when the result leaves the overview’s latest 100 evaluations.
run is null until initialized. It includes the walkthrough version, unique run/user/session IDs, discovered publish request IDs, source and agent version, milestone timestamps, structured reason_codes, dismissal state, viewed-evidence identifiers, retrieved_learning_ids from qualifying API-key searches (profile:<id> or user_playbook:<id>), and selected experiment ID. The dashboard uses returned IDs to prefill the evaluation example; no search response content is stored in onboarding state. Progress is shared with project teammates and persists across browsers.
A PATCH body contains run_id, action, and optional evidence_id (at most 255 characters). Allowed actions:
dismiss/resume: change full-checklist visibility.view_learning:evidence_idisprofile:<id>oruser_playbook:<id>returned by the status response.view_evaluation:evidence_idis the returned evaluation ID.defer_experiment: save Do it later for the optional experiment step; no evidence ID is needed. It counts toward checklist completion and recordsrun.milestones.experiment_deferredwithout selecting or starting an experiment. A deferred step hascomplete: trueandreason_code: "experiment_deferred".review_experiment:evidence_idmust identify the active workspace experiment.
The server validates the referenced evidence. Unknown actions or extra fields return 422; unrelated evidence returns 400; stale runs or concurrent-update conflicts return 409; an inaccessible project returns 404. Clients cannot directly set publish, retrieval, or grading milestones.
Technical progress is verified from persisted requests, extraction status, actual learning records, qualifying API-key searches, and stored evaluation results. Copying code, dashboard inspection, failed requests, empty searches and holdout responses do not prove retrieval. Retrying a search is safe when progress observation was temporarily unavailable.
The optional experiment step is satisfied by setup instructions reviewed or Do it later. Deferred setup remains available from Experiments. Neither state implies that traffic has arrived or an experiment has reached a conclusion. Rubrics and experiments remain workspace-wide and use their existing explicit configuration controls.