API changes for curation agents

[oganm]

Gemma REST API — Gaps to Fill

https://github.com/PavlidisLab/gemma-curation-agents/blob/main/TODO-gemma-api.md

Bug Fixes

• §19 BioAssayValueObject.originalPlatform echoes arrayDesign for GENELIST stand-ins — should carry the real platform (e.g. Illumina HiSeq), not the Generic stub
• §15 /datasets/{id}/samples?useProcessedQuantitationType=true 404s when a preferred QT is set (filed by Paul 2026-04-27; workaround: pass use_processed_quantitation_type=False)
• §20 gemmapy drops evidenceCode from get_dataset_annotations (gemmapy fix, not Gemma REST; not yet filed upstream)

---

Read-Side Gaps (priority order)

• §3 Audit trail — GET /rest/v2/datasets/{id}/auditEvents returning full AuditEventValueObject list; empty History tab is the most-noticed UI gap
• §13 Publications — GET /rest/v2/datasets/{id}/publications returning BibliographicReferenceValueObject; description scrape is a thin fallback
• §14 Public/private state (read) — isPublic: bool on ExpressionExperimentValueObject; needed to gate "edit a public experiment safely" banner
• §2 Annotation usage counts — add usage_count to AnnotationSearchResultValueObject; biggest pick-quality lift in the typeahead
• §16 Cell-type subset structure for sc experiments — expose cell-type assignment per bioassay so the UI can group rows by cell type
• §17 URI → ontology-term lookup — GET /rest/v2/ontology/term?uri=...; unblocks S10 validator false "possible hallucination" warnings on real-but-novel URIs
• §1 Categories enum — GET /rest/v2/categories returning canonical EFO factor/statement categories; would eliminate duplicate static lists in UI and prompts
• §7 Predicates enum — GET /rest/v2/predicates returning curated allow-list with URIs; same shape as §1, smaller list
• §8 Design GET — GET /rest/v2/datasets/{id}/design returning full structured design (factors, FVs, statements, biomaterial assignments); import path works without it
• §9 Cleaner dataset search — free-text q= param on /datasets or a dedicated /datasets/search typeahead endpoint
• §11 Diagnostics / QC plot endpoints — REST access to sample correlation matrix, PCA scree, mean-variance plot, p-value distribution, predicted-outliers list (defer)
• §12 Curator user info — extend /users/me with roles and permissions (defer until multi-curator deployment)
• 21: gemmapy drops experimentalFactorType + per-FV measurement from get_dataset_samples (gemmapy fix, not Gemma REST). We talked about using direct API calls rather than relying on gemmapy for the agents. I believe the agent wants to use gemmapy because the design endpoint isn't as robust as it should be for now. Will refer back to this when the design endpoint is handled
• 22: Gene-symbol resolution on /annotations/search

---

Write Surfaces (defer until production rollout; priority order)

• §4 Curation write endpoints
  • GET/PUT /datasets/{id}/design
  • GET/PUT /datasets/{id}/curationDetails; without this the UI is a read-only inspector
• §5 Curation proposals — POST/GET/PATCH /rest/v2/curation-proposals; needed for agent integration and curator review loop
• §18 Structured detail on curation-commit audit event — versioned JSON in AuditEventValueObject.detail for rich History tab badges and downstream aggregation; pairs with §4
• §14b Public/private toggle (write) — PUT /datasets/{id}/permissions; pairs with §14 read
• §6 Quantitation Type editing — PUT /datasets/{id}/quantitationTypes/{qtid}; needed to close the pre-publish checklist
• §10 ETag / If-Match concurrency on writes — prevent last-write-wins race between concurrent curators

[oganm]

Gemma REST API — workflow management gaps

https://github.com/PavlidisLab/gemma-curation-agents/blob/main/TODO-gemma-api-2.md

• §2 pipeline dispatch — blocking; curators can't run steps from the new UI without it. DEA dispatch is the highest-priority sub-item.
• §1 pipeline status — needed for the workflow dashboard; partially derivable from audit trail + booleans already on the VO.
• §4c public/private toggle — gates the final publish step.
• §3 GEEQ scores — subscores UI is nice-to-have; the trigger is lower priority than dispatch.
• §4a outlier management — needed for the diagnostics tab workflow.
• §4b QT preferred — needed for the QT checklist item.
• §5 curation groups — high UX value but can live in the curation layer only initially (current mock implementation).
• §6 checklist endpoint — can be assembled client-side from existing endpoints in the short term; a server-side computation is cleaner.

[oganm]

Deviations from the recommendations

TODO 1

• 13: dois are not presented
• 2: usage_count is added to annotation children/parents and terms endpoints as well
• 17: annotations/term?uri=... instead of ontology/term?uri=...
• 1/7: annotations/predicates and annotations/categories instead of just predicates and categories
• 22: gene annotation terms are returned by genes endpoint instead
• 4: added a POST /datasets/{id}/designPreflight endpoint to assess the impact of the suggested change

TODO 2

• 2: delete differential returns a task ID like the others.
• 2: path names differ
  • POST /datasets/{id}/preprocess -> POST /datasets/{dataset}/tasks/preprocess
  • POST /datasets/{id}/preprocess/diagnostics -> POST /datasets/{dataset}/tasks/diagnostics
  • POST /datasets/{id}/batchInformation/fetch -> POST /datasets/{id}/batchInfo
  • POST /datasets/{id}/analyses/differential -> POST /datasets/{dataset}/tasks/differential
  • POST /datasets/{id}/analyses/differential/{analysisId}/redo -> POST /datasets/{dataset}/tasks/redo/{analysisId}
  • DELETE /datasets/{id}/analyses/differential/{analysisId} -> DELETE /datasets/{id}/tasks/differential/{analysisId}
• 2: output of the task running endpoints only includes task ids since in creation time all other fields are constants. current status can be acquired from the tasks/{taskId} endpoint
• 1: Additional status information for remaining tasks

[oganm]

check what's going on with corrupted platform files

[oganm]

consider making design put an async operation/task

[ppavlidis]

Gemma 2 disposition: Fixed (32541c9 and follow-ups: tickets write-side and curation-agents API changes)