Go backend (preview)
What exists today
Section titled “What exists today”| Area | Status |
|---|---|
| Health and readiness probes | Implemented |
| Sign-in, current user, own password change | Implemented |
| User management with the five roles | Implemented |
| Laboratory settings (one laboratory per installation) | Implemented |
| Catalog of substances and disease models | Implemented |
| Subjects and body weights | Implemented |
| Experiments: groups with roles, regimens, timepoints, endpoints, allocation and exclusion | Implemented |
| Dosing: administrations, daily dosing schedule, induction outcomes | Implemented |
| Paradigm catalog with metric definitions for four paradigms | Implemented |
| Environments with measurement revisions and experiment test protocols | Implemented |
| Tests as sessions with one or more animals in arenas, trials and comments | Implemented |
| Video uploads to Google Cloud Storage, one current video per test | Implemented, live storage test pending |
| Calibration per arena with per-animal overrides | Implemented |
| Analysis service (jobs) for animals of tests and paradigm trials, human review of every animal’s result | Implemented for all four paradigms; the worker is tested on synthetic video only |
| Paradigm trials: a paradigm tried on one video outside any experiment | Implemented in the API; panel pages pending |
| Study report with role-based comparisons, CSV export, dashboard | Implemented |
| Vue panel on the new API | Scaffolded, not complete |
Installation
Section titled “Installation”You need Docker with Docker Compose. Run these commands from the repository root:
docker compose up -d dbdocker compose --profile setup run --rm migratedocker compose --profile setup run --rm setupdocker compose up --build -d backend jobscurl --fail http://127.0.0.1:4000/api/readydbstarts PostgreSQL in a new volume. The old installation’s data is not touched.migratecreates the tables in an empty database, or applies the migrations an existing one is missing. On an up-to-date database it does nothing.setupcreates the laboratory and the first administrator, then prints the administrator’s email and generated password once in your terminal. Run it again and it creates nothing.backendstarts the API on127.0.0.1:4000, andjobsqueues analysis runs.
If setup runs without a terminal (for example in CI), it refuses to start
unless you pass -credentials-file PATH. The password then goes into that new
file, readable only by its owner. It is never written to logs.
If you use your own PostgreSQL server instead of the Compose database, it must be
PostgreSQL 18 or later. The user that runs migrate needs permission to create
a schema in the database.
Databases from before the schema rebuild
Section titled “Databases from before the schema rebuild”The database schema was rebuilt from scratch for the study model described
below. migrate refuses a database that was installed with the earlier
migrations and changes nothing in it. Such a database must be reset: drop and
recreate it, or with Compose remove the volume with docker compose down -v,
then run migrate and setup again. Earlier data is not carried over.
Settings
Section titled “Settings”The Compose file contains development-only values. For any real installation, set your own values:
| Variable | Default | Meaning |
|---|---|---|
JWT_SECRET |
development value | Key that signs sign-in tokens. Use at least 32 random bytes. |
TOKEN_TTL |
12h |
How long a sign-in lasts, from 5 minutes to 7 days. |
BCRYPT_COST |
12 |
Password hashing strength, from 10 to 14. |
ADMIN_EMAIL |
admin@misko.local |
Email of the first administrator created by setup. |
LAB_NAME |
Misko Laboratory |
Laboratory name. |
LAB_TIMEZONE |
UTC |
Laboratory time zone, as an IANA name such as Europe/Istanbul. Day 0, dosing days and default test times use it. |
The backend README lists every variable, including database, storage and timeout settings.
Sign in
Section titled “Sign in”curl -X POST http://127.0.0.1:4000/api/auth/login \ -H 'Content-Type: application/json' \ -d '{"email":"admin@misko.local","password":"PASSWORD_FROM_SETUP"}'The response contains a token. Send it with every other request as
Authorization: Bearer TOKEN. GET /api/auth/me returns your user and the
permissions of your role. Change the generated password right away with
POST /api/auth/password (currentPassword, newPassword). The response holds
a new token, and all older tokens stop working.
Passwords need at least 8 characters and at most 72 bytes. Letters outside English (such as ş or ğ) take more than one byte each.
| Role | Can do |
|---|---|
| SUPERADMIN, LAB_MANAGER | Everything, including managing users, laboratory settings and analysis workers |
| RESEARCHER | Design studies, maintain the catalog, subjects, apparatus and protocols, plan and run tests; read everything |
| TECHNICIAN | Record weights, run tests, record doses and induction outcomes, calibrate one animal of a test, review analysis results, run paradigm trials; read everything |
| VIEWER | Read only |
| Permission | Covers |
|---|---|
study:write |
Catalog, experiment design and lifecycle, allocation and exclusion, protocols |
apparatus:write |
Environments, their revisions and arena calibrations |
subject:write |
Subjects |
weight:write |
Body weights |
test:write |
Planning tests: creating them, adding or removing animals, cancelling |
test:run |
Running tests and trials, videos, per-animal calibration overrides, doses, induction outcomes, manual analysis of an animal, result review |
trial:run |
Paradigm trials: creating them, uploading and calibrating their video, analysing them again, deleting them |
*:read |
Reading everything |
A role change takes effect on the user’s next request. Deleting a user signs them out immediately.
Manage users
Section titled “Manage users”Only SUPERADMIN and LAB_MANAGER can use these endpoints:
GET /api/userslists users withsearch,role,sort,order,pageandpageSize.POST /api/userscreates a user withemail,name,roleand an optionalpassword. Without a password, a strong one is generated and returned once.PATCH /api/users/{id}changesnameorrole.POST /api/users/{id}/reset-passwordsets a new password (or generates one) and signs that user out everywhere.DELETE /api/users/{id}deletes a user.
Two safety rules always apply. You cannot delete your own account, and the last SUPERADMIN or LAB_MANAGER cannot be deleted or given a lower role. There is no public sign-up.
Laboratory settings
Section titled “Laboratory settings”Every signed-in user can read GET /api/lab. SUPERADMIN and LAB_MANAGER can
change name, code and timezone with PATCH /api/lab. An empty code
clears it. GET /api/meta is public and returns the laboratory name for the
sign-in screen.
Catalog
Section titled “Catalog”Substances and disease models are shared by every study of the laboratory. Researchers and the roles above them maintain them; everyone can read them.
POST /api/catalog/substances(name,kind, optionaldescription).kindisCOMPOUND,REFERENCE_DRUG,VEHICLEorINDUCER; it only helps pickers. What a substance does in a study comes from the regimen that uses it.POST /api/catalog/disease-models(name,inductionTypeofCHEMICAL,SURGICAL,DIET,STRESSorOTHER, optionalconfirmationCriterionanddescription). Every disease model is induced; the inducing agent and its dose are part of each study’s regimen.- Both lists accept
search; substances filter bykindand disease models byinductionType. Change an entry withPATCH. An entry still in use cannot be deleted (substance.inUse,diseaseModel.inUse).
Subjects and weights
Section titled “Subjects and weights”Every signed-in user can read subjects. SUPERADMIN, LAB_MANAGER and RESEARCHER can change them.
POST /api/subjectscreates a subject withcode,species(MOUSEorRAT) andsex(FEMALE,MALEorUNKNOWN). Codes are unique regardless of upper or lower case.GET /api/subjectslists subjects withsearch,species,sex,unallocated=true,sort,order,pageandpageSize. Each subject shows itsallocation(experiment, group and whether it is excluded), or null.PATCH /api/subjects/{id}changes the fields you send.DELETE /api/subjects/{id}deletes a subject that is not allocated and has no weights.- Technicians and the roles above them record body weight with
POST /api/subjects/{id}/weights(grams,measuredAt). Weights belong to the animal and never change.
An animal can be registered before it joins a study, and it joins exactly one.
Experiments
Section titled “Experiments”An experiment is designed as a draft, started, and completed. Every signed-in user can read experiments. SUPERADMIN, LAB_MANAGER and RESEARCHER design and start them and allocate animals.
-
Create the experiment with
POST /api/experiments(code,title, optionaldescription,hypothesis,randomisationandblinded). It starts asDRAFT. -
Add groups with
POST /api/experiments/{id}/groups(codesuch asG1,name,role,diseaseModelId,targetSize). The role is one of:Role Disease model Receives Purpose HEALTHY_CONTROLnone vehicle, if any normal baseline SHAMrequired a vehicle in place of the induction controls for the induction procedure DISEASE_CONTROLrequired induction and vehicle the deficit POSITIVE_CONTROLrequired induction and a reference drug proves the test can detect a rescue TREATMENTrequired induction and the tested substance efficacy and dose response -
Describe what each group receives with
POST /api/experiments/{id}/regimen-items(groupId,purposeofINDUCTION,VEHICLEorTREATMENT,substanceId,amount,unit,route,frequencyofONCE,DAILY,TWICE_DAILY,WEEKLYorEVERY_N_DAYSwithintervalDays,startDay,endDay). Days are study days counted from day 0. A group has at most oneTREATMENTitem, so a treatment group has one substance at one dose. Several treatment groups of the same substance at different doses form the dose response. -
Add timepoints with
POST /api/experiments/{id}/timepoints(name,studyDay,position), for example Baseline on day -1 and Day 14 on day 14. -
Add a protocol (see below), then choose what the study is judged on with
POST /api/experiments/{id}/endpoints(timepointId,paradigmKey,metricKey,kindofPRIMARYorSECONDARY,directionofHIGHER_IS_BETTERorLOWER_IS_BETTER, optionalbaselineTimepointId).GET /api/experiments/{id}/metric-optionslists the metrics the protocol’s paradigms can measure. There is at most one primary endpoint. -
Check the design with
GET /api/experiments/{id}/readiness, which lists every unmet rule, then start withPOST /api/experiments/{id}/start(dayZero, a date). Starting needs at least one timepoint and one group, a target size on every group, one primary endpoint, and a regimen that matches each role: a treatment or positive control group has one treatment and an induction, a disease control has an induction and a vehicle, a sham has a vehicle and no induction, a healthy control has no induction or treatment, and every sham, treatment and positive control group has a disease control with the same disease model. -
When every test is completed or cancelled, close the study with
POST /api/experiments/{id}/complete. A completed experiment is read-only.
Starting freezes groups, regimen items, timepoints and endpoints. The code, title and description can still be edited until completion.
Allocation and exclusion
Section titled “Allocation and exclusion”- Put an animal in a group with
POST /api/experiments/{id}/allocations(subjectId,groupId, optionalcage), or let the system do it withPOST /api/experiments/{id}/allocations/randomise(subjectIds, optionalgroupIdsandcage). Randomisation fills the groups evenly up to their target sizes and allocates either every animal or none. - An animal belongs to one group of one experiment, for good. While the experiment is a draft you can move it to another group or remove it. Once the study runs, only its cage can change.
- If an animal leaves the study, exclude it with
POST /api/experiments/{id}/allocations/{allocationId}/exclusion(reason:DIED,HUMANE_ENDPOINT,INDUCTION_FAILED,TECHNICALorOTHER, optional note). An excluded animal is never deleted: it stays visible in the report, joins no new test and is not analyzed again. GET /api/experiments/{id}/allocationslists the animals (filter bygroupIdorexcluded) and each group’s count against its target.
Dosing
Section titled “Dosing”Technicians and the roles above them record what was actually given while the experiment runs.
GET /api/experiments/{id}/dosing?date=YYYY-MM-DDlists every dose due that day per animal, from the regimen items and day 0, with how many were already given and the dose for the animal’s latest weight. Withoutdateit uses today in the laboratory’s time zone.POST /api/experiments/{id}/allocations/{allocationId}/administrationsrecords one dose. WithregimenItemIdthe substance, dose and route come from the plan and you may enter a different actual amount or route; an unplanned dose names them all. Doses per kilogram (mg/kg,ug/kg,mL/kg,IU/kg) need a weight of the same animal from the previous 7 days; the latest one is used unless you nameweightMeasurementId, and the response shows the absolute dose. Disease induction is recorded the same way, with purposeINDUCTION.POST /api/experiments/{id}/allocations/{allocationId}/induction-outcomerecords once whether the animal’s disease model wasCONFIRMEDorNOT_CONFIRMED.GET /api/experiments/{id}/administrations,GET /api/subjects/{id}/administrationsandGET /api/experiments/{id}/induction-outcomeslist the records.
Write amounts as decimal text, for example "0.25". Records keep the names,
doses and weights they were saved with, and they never change.
Paradigm catalog
Section titled “Paradigm catalog”Every signed-in user can read the paradigm catalog. Paradigms are defined in the code and cannot be created, edited or deleted through the API.
GET /api/paradigmslists paradigms with their published versions. Four paradigms are published:MWM,NOVEL_OBJECT,POLEandTREADMILL, in two categories (LEARNING_MEMORYforMWMandNOVEL_OBJECT,MOTORforPOLEandTREADMILL). Every paradigm is analysed automatically: an analysis worker tracks the subject on the video once a worker is registered for the paradigm version, Misko derives every event and metric, and a person only reviews the result. There is no observer scoring.GET /api/paradigms/{key}returns the latest version, andGET /api/paradigms/{key}/versions/{version}returns one exact version. Each version lists its parameters, each with its scope (APPARATUSandANALYSISon an environment,SESSIONon a protocol step), label, help text, unit, allowed range and default; its zones and events; and for every metric a plain description, the definition, formula, inputs and what happens when data is missing. Names, labels and descriptions follow?lang=orAccept-Language(enortr).
Every paradigm is measured from the tracked position of the subject and its zones:
- The water maze derives its zones from the apparatus parameters (platform,
target quadrant, wall zone). The other paradigms declare zones marked
calibrated, drawn as circles or polygons with the calibration: the novel and the familiar object (novel_object,familiar_object), the pole and its base (pole,base) and the treadmill’s shock grid (shock_grid). eventslists what Misko derives from the positions and the zones: exploration bouts labellednovelorfamiliar, the pole turn, base and fall, treadmill shocks and exhaustion, water maze platform visits. Every rule threshold (minimum bout, turn descent, fall speed, time on the grid for a shock or for exhaustion) is anANALYSISparameter with a standard default that a lab can change per environment.inputEventsis always empty.
Results always name the paradigm version, the metric engine version and the
result schema version they were computed with. A metric that cannot be computed
is reported as missing with a reason, never as zero. For example, a probe trial
without an escape reports EVENT_NOT_OBSERVED, and a novel object trial whose
total exploration is below the minimum reports BELOW_EXPLORATION_CRITERION
for the discrimination index. A published version never
changes; a changed definition is published as a new version.
Environments and protocols
Section titled “Environments and protocols”An environment is one physical apparatus, such as a particular water tank or one of several novel object boxes under one camera, set up for one paradigm. In a test each animal is placed in an arena, which is one revision of an environment. Researchers, lab managers and super admins create and revise environments and protocols; every signed-in user can read them.
POST /api/environmentscreates an environment with its first revision. Give every apparatus measurement of the paradigm version inparameters, for example the tank and platform sizes forMWM, and optionally its analysis settings; omitted analysis settings use their defaults. Values outside the allowed ranges, or inconsistent values such as a platform outside the tank, are rejected.- When the apparatus changes, add a revision with
POST /api/environments/{id}/revisions. Earlier revisions never change and cannot be deleted. You can still rename an environment or edit its notes.GET /api/environment-revisionslists every revision for arena pickers.
A protocol is the test battery of an experiment. It can combine paradigms, for example a pole test followed by a treadmill run.
POST /api/experiments/{id}/protocolscreates a protocol with its first version. Each step gives its position, the paradigm and its version, the trial type, the number of trials, the pause between trials in seconds and any session parameters. A step names no apparatus: the arena is chosen per animal in each test.- Number the steps from 1 without gaps. A trial type the paradigm does not define and session values out of range are rejected. Session parameters you leave out get the paradigm defaults, and the stored version shows them.
- To change a protocol, add a version with
POST /api/experiments/{id}/protocols/{protocolId}/versions. Stored versions never change.
Tests, trials and comments
Section titled “Tests, trials and comments”A test is one session of a running experiment: one timepoint, one protocol step and one video. It films one or more animals, each in its own arena; usually one, sometimes up to three boxes under one camera. Animals of different groups may share a session. The group of every measurement comes from the animal’s allocation.
- Researchers, lab managers and super admins plan tests with
POST /api/experiments/{id}/tests: the timepoint, the protocol version and step, optionally the scheduled time, andsubjects, a list ofallocationIdandenvironmentRevisionIdpairs (up to 12). Without a time, the test is scheduled on day 0 plus the timepoint’s study day. Every arena must run the step’s paradigm, and an animal cannot be in two tests of the same timepoint and step. - While a test is planned, add an animal with
POST /api/tests/{id}/subjectsor remove one withDELETE /api/tests/{id}/subjects/{subjectId}. The last animal cannot be removed; cancel the test instead. - Technicians and the roles above them run tests:
POST /api/tests/{id}/start, then record each animal’s trials withPOST /api/tests/{id}/subjects/{subjectId}/trials, thenPOST /api/tests/{id}/complete. Every animal needs at least one trial. If a trial has to be repeated, record the same repetition again; it gets the next attempt number and the earlier trial is kept. - A test that has not been completed can be cancelled with a reason. A test with an excluded animal cannot start until that animal is removed.
GET /api/testsis the worklist across experiments, filtered by experiment, status, timepoint and date range.
Everyone who is signed in, including viewers, can comment on a test. You can edit only your own comments. Lab managers and super admins can delete any comment. Each user can post or edit up to 20 comments per minute.
Videos
Section titled “Videos”Videos are stored in a private Google Cloud Storage bucket. Until an
administrator sets GCS_BUCKET (and, with workload identity, GCS_SIGNER_EMAIL),
video routes answer 503 with media.storageNotConfigured. See
backend/README.md for the bucket, CORS and permission setup.
A test has one video, which shows all of its animals. Videos can be attached once the test has started.
- Technicians and the roles above them start an upload with
POST /api/tests/{id}/recordings, giving the file name, type (MP4, MOV or WebM), size and CRC32C checksum. The response contains a signed request; the browser uses it to upload the file directly to storage. - After the upload, the same person (or a lab manager or super admin) calls
POST /api/tests/{id}/recordings/{recordingId}/finalize. The server checks the stored file. A file that does not match is markedREJECTEDwith the reason, such asCHECKSUM_MISMATCH. - A new upload replaces the test’s video. The earlier one is kept for
provenance, and
GET /api/tests/{id}/recordings/currentreturns the newest verified one. - Everyone who is signed in can get a short-lived link to a verified video with
GET /api/tests/{id}/recordings/{recordingId}/read-url. Players can seek in it.
Calibration
Section titled “Calibration”Before a video can be turned into distances and times in zones, the system needs to know how camera pixels map to centimeters in each arena.
- A calibration belongs to the arena. When the rig is set up, someone who can
change apparatus opens a frame from the fixed camera and calibrates each
environment revision once, with
POST /api/environments/{id}/revisions/{number}/calibrations. Its crop is that arena’s region of the frame, so three arenas under one camera each get their own calibration. Every animal tested in that arena then uses it. - The camera and the arena can move. Nothing checks that yet: the status of an
animal that uses its arena’s calibration says
drift: UNCHECKED. If a video does not match, a technician (or a role above) calibrates that one animal by hand withPOST /api/tests/{id}/subjects/{testSubjectId}/calibrationson the test’s current video. The override replaces the arena calibration for that animal only, and if it is rejected the animal waits instead of falling back to the arena. A replacement video starts from the arena calibrations again. - Both kinds take the same points: at least 4 FIT points and at least 3 separate
CHECK points, each with its pixel position and its real position in
centimeters. The FIT points define the mapping and the CHECK points test it. If
a CHECK point is off by more than the paradigm allows (2 cm), the calibration
is stored as
REJECTED. The measurement plane isARENA_FLOOR,WATER_SURFACE,APPARATUS_TOP, orAPPARATUS_SIDEfor rigs filmed from the side (the pole and the treadmill lane). - A paradigm with
calibratedzones (novel object, pole, treadmill) also needs those zones drawn on the same frame. Send them aszonesin pixels, for example{"key": "base", "polygon": [{"x": 300, "y": 480}, ...]}or{"key": "novel_object", "circle": {"x": 960, "y": 540, "radius": 60}}; a key may have several shapes. Without a required zone the calibration is refused (calibration.missingZone). A per animal override on the test video carries its own zones, for example when the novel object is on the other side. Every required zone needs a shape and every shape must lie inside the frame. Misko converts them to centimeters with the calibration and returns each zone in both. The worker receives them with its job, and the metrics use the centimeter shapes. In the panel the visual calibrator places the points, the crop and the zones on a frame of a video: for an environment default a video file chosen on the computer (read in the browser, never uploaded), for an override the test’s current video. - World points must use the frame the paradigm’s zones are defined in. For the water maze that frame is tank-centred: (0, 0) is the tank centre, x points east and y north, so the wall points are (r, 0), (0, r), (-r, 0) and (0, -r) with r = tank diameter / 2. The novel object arena is seen from above with the origin at a corner of the floor, x to the right and y down the image, and its points lie within the arena. The pole is seen from the side with x horizontal and y the height above the base (base at 0, top at the pole length); the treadmill from the side with x along the lane from the shock grid (0) to the front. Use at least four non-collinear points of the rig.
- To fix a calibration, send a new one with
supersedesIdset to the latest calibration of the same arena or animal. Earlier calibrations are kept. GET /api/tests/{id}/calibration-statuslists every animal of a test:WAITING_FOR_VIDEO,WAITING_FOR_CALIBRATIONuntil a valid calibration with every required zone applies, thenCALIBRATED. Paradigms without video measurements, such as the pole test, showNOT_REQUIRED.
Video analysis
Section titled “Video analysis”Tracking runs in separate analysis workers that talk to the API. The worker in
the worker/ folder tracks the subject’s centroid in recorded fixed-camera
video of every paradigm at version 1. It has only been tested on synthetic video so far;
do not use its results for research until it has been checked against a
manually annotated recording.
The analysis service analyses one video with one paradigm version, its parameters and a copy of the calibration. Each piece of work is a job: what it analyses never changes, so analysing again creates a new job and earlier jobs stay. Jobs are requested by an animal of a test (an experiment) or by a paradigm trial; the service itself knows nothing about experiments.
- A lab manager registers a worker with
POST /api/analysis/workers, giving its name, model version and the paradigm versions it supports. Register the bundled worker with the paradigms it supports at version 1 (see Installation). Versions outside the catalog are refused withworker.unknownCapability. The response shows the worker’s token only once; store it in the worker’s secret configuration.POST /api/analysis/workers/{id}/disablerevokes it. Start the worker withMISKO_WORKER_TOKENset, for exampledocker compose --profile worker up -d worker. - Every
JOB_INTERVAL(10 seconds by default) thejobsprocess submits one job per animal of a test, when the experiment is running or completed, the animal is not excluded, the test’s video is verified and the animal’s calibration is valid with every required zone. It also analyses paradigm trials that became ready (below). A job waits in the queue until a worker that supports its paradigm claims it. - The worker finds the animal inside the calibration’s crop in every frame,
converts its position to centimeters, and uploads the positions (the
trajectory) and an annotated video. It never learns the animal’s group or
treatment. Misko computes every metric and event from the trajectory; a
worker cannot send its own numbers. If too many frames are lost or the
tracking confidence is too low, the job is
FAILEDwith aQC_FAILEDreason; the quality figures (lost and inferred ratios, mean confidence) are kept with the job either way. A worker may mark samples as inferred (the optionalinferredflag), for example while the animal is hidden: they count as tracked, but not in the confidence mean. The bundled worker sends none. - A job records exactly what was analysed: the video version, the clip, a copy
of the calibration with its zones, the paradigm version and the parameters.
To analyse an animal again, a technician (or a role above) calls
POST /api/analysis/test-subjects/{testSubjectId}/runs. Earlier results stay. GET /api/tests/{id}/analysis-runslists the jobs of a test’s animals.GET /api/analysis/jobs/{jobId}shows a job with its metrics, events and quality,GET /api/analysis/jobs/{jobId}/video-pairreturns short-lived links to the original and analysed video with the offsets needed to play them in sync, andGET /api/analysis/jobs/{jobId}/outputs/TRAJECTORY/read-urla link to the trajectory for drawing the track. The olderGET /api/analysis-runs/{jobId}routes still answer.
Paradigm trials
Section titled “Paradigm trials”A paradigm trial tries a paradigm version on one video in one arena, outside
any experiment: to check a new rig, a camera position or a threshold. It has no
groups, no review and no report, and its results never move into an
experiment. Technicians and the roles above them run trials (trial:run);
everyone can read them.
- Create the trial:
POST /api/trialswith a name, the paradigm key and version and an environment revision of that version. - Upload its video:
POST /api/trials/{id}/videoreturns a signed upload, thenPOST /api/trials/{id}/video/finalizeverifies it. - If the arena has no calibration, or the camera moved, calibrate on the
trial’s video:
POST /api/trials/{id}/calibrations(same body as an arena calibration, with the zones the paradigm needs). This never changes the arena’s calibration.GET /api/trials/{id}/calibration-statustells whether the trial is ready. - Once the video is verified and the calibration is ready, the trial is
analysed automatically (at once, or at the next tick after a later
calibration).
GET /api/trials/{id}shows every analysis with its metrics and quality. - To try other thresholds,
POST /api/trials/{id}/analyseswith{"overrides": {"min_bout_s": 1.5}}runs a new analysis of the same video with those ANALYSIS values; only ANALYSIS parameters of the paradigm are accepted. Earlier analyses stay for comparison. DELETE /api/trials/{id}hides the trial; its analyses stay readable by job.
Review
Section titled “Review”Every result of an animal of a test is approved by a person before it counts.
The first successful job of an animal opens its result as PENDING. Paradigm
trials are never reviewed.
GET /api/analysis/resultsis the review queue (status,experimentId). In a blinded experiment it shows no group, disease, substance or dose.- Technicians and the roles above them accept a result with
POST /api/analysis/results/{testSubjectId}/acceptor reject it withPOST .../rejectand areason(TRACKING_LOST,WRONG_ANIMAL,VIDEO_DEFECT,PROTOCOL_DEVIATION,OTHER).POST .../runwith ajobIdputs another successful job of the animal under review, andPOST /api/analysis/results/bulk-acceptaccepts up to 100 at once. - A newer job never replaces a reviewed result by itself. Once the experiment is completed, decisions cannot change.
Study report and dashboard
Section titled “Study report and dashboard”Everyone who is signed in can read reports. They only read records.
GET /api/experiments/{id}/reportreturns every endpoint, primary first. The unit is the animal: each animal contributes one value per timepoint, and only accepted results of animals that are not excluded count. Per group it shows n, mean, SD, SEM, minimum, maximum, change from baseline and how many animals are pending review, waiting for analysis, rejected or excluded.- Comparisons follow the group roles: model validity (disease control against healthy control and sham), assay sensitivity (positive control against disease control), efficacy of each treatment group against its disease control with rescue %, and dose response for the treatment groups of one substance.
- Results from different paradigm or metric engine versions are never mixed; the report lists the versions and leaves the comparison out.
GET /api/experiments/{id}/report/exportdownloads CSV, one row per animal (level=animals) or per group (level=groups);excel=1writes a file Excel opens directly.GET /api/dashboard/summarycounts experiments, tests, runs and results by status and animals waiting for calibration, and lists the latest results and the next planned sessions.
The panel
Section titled “The panel”The Vue panel in frontend/ is being moved to this API. Screens for
substances, disease models, the experiment tabs (design, allocation, dosing, tests, report) and the
review queue are scaffolded but not complete. Until they are, use the API
directly.
Errors
Section titled “Errors”Every error has a stable code, such as auth.forbidden,
experiment.notReady or allocation.frozen, and an English message. A 401
status means you are not signed in or your token is no longer valid. A 403 status
means your role does not allow the action. A 409 status means the record’s state
does not allow the change, for example editing the design of a running
experiment.