about summary refs log tree commit diff
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-10-08 13:44:05 +0000
committerPjotr <wrk@bosa.lan>2026-10-08 13:44:05 +0000
commit679136801effc34ff4b50e54abfc40592ee1d64d (patch)
tree56601c5971a7a876602e6faf2c9b09599cadb123
parent2edc685bb7c56d5f9f28da09378f300bfe81021d (diff)
downloadgenenetwork4-679136801effc34ff4b50e54abfc40592ee1d64d.tar.gz
* README.md (Endpoints): show real enveloped example responses.
The endpoint examples still showed the bare payloads from before the
success envelope. Each is now a real response in the current shape
(data, meta, notes, next), generated from a running server with long
lists and strings abbreviated by "...", took_ms and request_id fixed
to example values.

All 21 existing examples are replaced, and examples are added for
GET /search, GET /publications/{pubmed_id}/traits and
GET /datasets/{dataset}, which had none. The intro note that said the
examples show only `data` now describes this. All 29 JSON blocks in the
README parse.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
-rw-r--r--README.md579
1 files changed, 473 insertions, 106 deletions
diff --git a/README.md b/README.md
index 73757a2..cdbc412 100644
--- a/README.md
+++ b/README.md
@@ -45,8 +45,9 @@ entry below.
 
 Every success response is wrapped in one envelope (see
 [Success responses](#success-responses) below), except `/` (a
-plain-text greeting) and `/openapi.json`. The example responses in the
-details below show the envelope's `data` only.
+plain-text greeting) and `/openapi.json`. The example responses below
+are real ones, with long lists and strings abbreviated by `...`, and
+`took_ms` and `request_id` shortened to plausible values.
 
 Details, including example responses, below.
 
@@ -55,12 +56,17 @@ Details, including example responses, below.
 
   ```json
   {
-    "name": "GeneNetwork4",
-    "short_name": "GN4AI",
-    "version": 4.0,
-    "release": 1,
-    "date": "20261001",
-    "git": "457a463"
+    "data": {
+      "name": "GeneNetwork4", "short_name": "GN4AI", "version": 4.0,
+      "release": 1, "date": "20261008", "git": "208eeac"
+    },
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": []
   }
   ```
 
@@ -72,10 +78,24 @@ Details, including example responses, below.
   table, mirroring GeneNetwork3's `gn3.db.species.get_all_species`:
 
   ```json
-  [
-    {"name": "mouse", "menu_name": "Mouse (Mus musculus, mm10)", "family": "Vertebrates"},
-    ...
-  ]
+  {
+    "data": [
+      {"name": "human", "menu_name": "Human (Homo sapiens, hg19)",
+       "family": "Vertebrates"},
+      {"name": "mouse", "menu_name": "Mouse (Mus musculus, mm10)",
+       "family": "Vertebrates"},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/groups", "description": "Groups (populations); add ?species=<name> to list one species' groups"}
+    ]
+  }
   ```
 
   Needs a live MariaDB connection, configured via the `SQL_URI`
@@ -90,10 +110,24 @@ Details, including example responses, below.
   logic but only a 4-column subset). 404 if no species matches.
 
   ```json
-  {"id": 1, "species_id": 1, "species_name": "Mouse", "name": "mouse",
-   "menu_name": "Mouse (Mus musculus, mm10)", "full_name": "Mus musculus",
-   "family": "Vertebrates", "family_order_id": 1, "taxonomy_id": 10090,
-   "order_id": 15}
+  {
+    "data": {
+      "id": 1, "species_id": 1, "species_name": "Mouse", "name": "mouse",
+      "menu_name": "Mouse (Mus musculus, mm10)", "full_name": "Mus musculus",
+      "family": "Vertebrates", "family_order_id": 1, "taxonomy_id": 10090,
+      "order_id": 15
+    },
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/species/mouse/datasets", "description": "Expression datasets of this species"},
+      {"href": "/groups?species=mouse", "description": "Groups of this species"}
+    ]
+  }
   ```
 
   Needs `SQL_URI`, same as `/species` above.
@@ -111,10 +145,26 @@ Details, including example responses, below.
   `/species` above.
 
   ```json
-  [
-    {"id": 1, "probe_freeze_id": 10, "name": "Br_U_0803_M", ...},
-    ...
-  ]
+  {
+    "data": [
+      {"id": 386, "probe_freeze_id": 156, "name": "B6D2ONCILM_0412",
+       "name2": "B6D2ONCILM_Apr12",
+       "full_name": "HEI ONC Retina B6D2 (Apr12) RankInv",
+       "short_name": "HEI ONC Retina B6D2 (Apr12) RankInv",
+       "create_time": "2012-05-17", "public": 1, "confidentiality": 0,
+       "data_scale": "log2", "tissue": "Retina mRNA"},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/species/mouse", "description": "The species these datasets belong to"}
+    ]
+  }
   ```
 
 - `GET /groups` - returns a JSON array of all groups in the `InbredSet`
@@ -122,14 +172,26 @@ Details, including example responses, below.
   response:
 
   ```json
-  [
-    {"id": 1, "species_id": 1, "display_name": "BXD", "name": "BXD",
-     "full_name": "BXD Family", "public": 2, "mapping_method_id": "1",
-     "genetic_type": "riset",
-     "family": "Reference Populations (replicate average, SE, N)",
-     "species": "mouse", "mapping_method": "qtlreaper"},
-    ...
-  ]
+  {
+    "data": [
+      {"id": 25, "species_id": 4,
+       "display_name": "Brain, Aging: AD, Normal Gene Expression (Liang)",
+       "name": "AD-cases-controls",
+       "full_name": "Brain, Aging: AD, Normal Gene Expression (Liang)",
+       "public": 2, "mapping_method_id": null, "genetic_type": null,
+       "family": null, "species": "human", "mapping_method": null},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/species", "description": "The species the groups belong to (filter groups with ?species=<name>)"}
+    ]
+  }
   ```
 
   `family` is the population category and `species` the species' short
@@ -158,12 +220,28 @@ Details, including example responses, below.
   themselves stay `InbredSet*`. 404 if no group matches.
 
   ```json
-  {"id": 1, "group_id": 1, "display_name": "BXD", "name": "BXD",
-   "species_id": 1, "full_name": "BXD Family", "public": 2,
-   "mapping_method_id": "1", "genetic_type": "riset",
-   "family": "Reference Populations (replicate average, SE, N)",
-   "family_order": 1, "menu_order_id": 0.0, "group_code": "BXD",
-   "description": "<p>...</p>", "mapping_method": "qtlreaper"}
+  {
+    "data": {
+      "id": 1, "group_id": 1, "display_name": "BXD", "name": "BXD",
+      "species_id": 1, "full_name": "BXD Family", "public": 2,
+      "mapping_method_id": "1", "genetic_type": "riset",
+      "family": "Reference Populations (replicate average, SE, N)",
+      "family_order": 1, "menu_order_id": 0.0, "group_code": "BXD",
+      "description": "<p>...</p>", "mapping_method": "qtlreaper"
+    },
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/groups/BXD/strains", "description": "The group's strains/samples"},
+      {"href": "/groups/BXD/case-attributes", "description": "Case-attribute names and per-strain values"},
+      {"href": "/groups/BXD/datasets", "description": "Expression (ProbeSet) datasets of the group"},
+      {"href": "/groups/BXD/traits", "description": "Published (phenotype) traits of the group (can be very large)"}
+    ]
+  }
   ```
 
   Needs `SQL_URI`, same as `/species` above.
@@ -176,11 +254,23 @@ Details, including example responses, below.
   same flag as a keyword argument):
 
   ```json
-  [
-    {"id": 1, "name": "B6D2F1", "used_for_mapping": false},
-    {"id": 4, "name": "BXD1", "used_for_mapping": true},
-    ...
-  ]
+  {
+    "data": [
+      {"id": 1, "name": "B6D2F1", "used_for_mapping": false},
+      {"id": 2, "name": "C57BL/6J", "used_for_mapping": false},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/groups/BXD", "description": "The group these strains belong to"},
+      {"href": "/groups/BXD/case-attributes", "description": "Case-attribute names and per-strain values"}
+    ]
+  }
   ```
 
   `GET /groups/BXD/strains?used_for_mapping=true` excludes BXD's
@@ -203,10 +293,18 @@ Details, including example responses, below.
 
   ```json
   {
-    "names": ["Epoch", "RRID", "SeqCvge", "Status"],
-    "values": [
-      {"strain": "BXD1", "case_attributes": {"Epoch": "1", "RRID": "JAX:000036", "SeqCvge": "36+39L", "Status": "Live"}},
-      ...
+    "data": {
+      "names": ["Epoch", "RRID", ...],
+      "values": [{"strain": "B6D2F1", "case_attributes": {"Status": "Live", "SeqCvge": "", "RRID": "JAX:100006", "Epoch": "0 "}}, ...]
+    },
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/groups/BXD/strains", "description": "The group's strains/samples"}
     ]
   }
   ```
@@ -227,10 +325,33 @@ Details, including example responses, below.
   trait 17985 (an unknown abbreviation is an empty list).
 
   ```json
-  [
-    {"id": 10001, "phenotype_id": 4, "publication_id": 116, ...},
-    ...
-  ]
+  {
+    "data": [
+      {"id": 10001, "phenotype_id": 4, "publication_id": 116,
+       "mean": 52.13529418496525, "locus": "rs48756159",
+       "lrs": 13.497491147108706, "lod": 2.931687912056626,
+       "additive": 2.3944443506944437, "nsamples": 34,
+       "pre_publication_description": "Central nervous system, morphology: Cerebellum weight, whole, bilateral...",
+       "post_publication_description": "Central nervous system, morphology: Cerebellum weight, whole, bilateral...",
+       "original_description": "Original post publication description: Cerebellum weight [mg]",
+       "units": "mg", "pubmed_id": 11438585,
+       "title": "Genetic control of the mouse cerebellum: identification of quantitative...",
+       "authors": "Airey DC, Lu L, Williams RW", "journal": "J Neuroscience",
+       "volume": "21", "pages": "5099-5109", "month": null, "year": "2001",
+       "dataset": "BXDPublish", "abbreviation": "Cerebellum_Weight",
+       "url": "https://genenetwork.org/show_trait?trait_id=10001&dataset=BXDPublish"},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": ["lod = lrs / 4.604"],
+    "next": [
+      {"href": "/groups/BXD", "description": "The group these traits belong to"}
+    ]
+  }
   ```
 
 - `GET /groups/{group}/traits/{trait_id}` - returns one published
@@ -244,18 +365,32 @@ Details, including example responses, below.
 
   ```json
   {
-    "id": 10001, "phenotype_id": 4, "publication_id": 116,
-    "mean": 52.135, "locus": "rs48756159", "lrs": 13.497, "lod": 2.932,
-    "additive": 2.394, "nsamples": 34,
-    "pre_publication_description": "Central nervous system, morphology: Cerebellum weight, whole, bilateral in adults of both sexes [mg]",
-    "post_publication_description": "Central nervous system, morphology: Cerebellum weight, whole, bilateral in adults of both sexes [mg]",
-    "original_description": "Original post publication description: Cerebellum weight [mg]",
-    "units": "mg", "pubmed_id": 11438585,
-    "title": "Genetic control of the mouse cerebellum: identification of quantitative trait loci modulating size and architecture",
-    "authors": "Airey DC, Lu L, Williams RW", "journal": "J Neuroscience",
-    "volume": "21", "pages": "5099-5109", "month": null, "year": "2001",
-    "dataset": "BXDPublish", "abbreviation": "Cerebellum_Weight",
-    "url": "https://genenetwork.org/show_trait?trait_id=10001&dataset=BXDPublish"
+    "data": {
+      "id": 10001, "phenotype_id": 4, "publication_id": 116,
+      "mean": 52.13529418496525, "locus": "rs48756159",
+      "lrs": 13.497491147108706, "lod": 2.931687912056626,
+      "additive": 2.3944443506944437, "nsamples": 34,
+      "pre_publication_description": "Central nervous system, morphology: Cerebellum weight, whole, bilateral...",
+      "post_publication_description": "Central nervous system, morphology: Cerebellum weight, whole, bilateral...",
+      "original_description": "Original post publication description: Cerebellum weight [mg]",
+      "units": "mg", "pubmed_id": 11438585,
+      "title": "Genetic control of the mouse cerebellum: identification of quantitative...",
+      "authors": "Airey DC, Lu L, Williams RW", "journal": "J Neuroscience",
+      "volume": "21", "pages": "5099-5109", "month": null, "year": "2001",
+      "dataset": "BXDPublish", "abbreviation": "Cerebellum_Weight",
+      "url": "https://genenetwork.org/show_trait?trait_id=10001&dataset=BXDPublish"
+    },
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": ["lod = lrs / 4.604"],
+    "next": [
+      {"href": "/groups/BXD/traits/10001/values", "description": "The trait's value in each strain"},
+      {"href": "/groups/BXD", "description": "The group this trait belongs to"},
+      {"href": "/publications/11438585/traits", "description": "Every trait reported by this trait's publication"}
+    ]
   }
   ```
 
@@ -279,11 +414,22 @@ Details, including example responses, below.
   ProbeSet (expression) or Geno (genotype) traits.
 
   ```json
-  [
-    {"name": "BXD1", "value": 61.400002},
-    {"name": "BXD2", "value": 49.0},
-    ...
-  ]
+  {
+    "data": [
+      {"name": "BXD1", "value": 61.400001525878906},
+      {"name": "BXD11", "value": 53.099998474121094},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/groups/BXD/traits/10001", "description": "The trait's metadata"}
+    ]
+  }
   ```
 
   Needs `SQL_URI`, same as `/species` above.
@@ -294,15 +440,26 @@ Details, including example responses, below.
   matches. Needs `SQL_URI`, same as `/species` above.
 
   ```json
-  [
-    {"id": 1, "probe_freeze_id": 10, "name": "Br_U_0803_M",
-     "name2": "BXDMicroArray_ProbeSet_August03",
-     "full_name": "Brain U74Av2 08/03 MAS5",
-     "short_name": "Brain U74Av2 08/03 MAS5", "create_time": "2003-08-01",
-     "public": 0, "confidentiality": 0, "data_scale": "log2",
-     "tissue": "Brain mRNA"},
-    ...
-  ]
+  {
+    "data": [
+      {"id": 386, "probe_freeze_id": 156, "name": "B6D2ONCILM_0412",
+       "name2": "B6D2ONCILM_Apr12",
+       "full_name": "HEI ONC Retina B6D2 (Apr12) RankInv",
+       "short_name": "HEI ONC Retina B6D2 (Apr12) RankInv",
+       "create_time": "2012-05-17", "public": 1, "confidentiality": 0,
+       "data_scale": "log2", "tissue": "Retina mRNA"},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/groups/BXD", "description": "The group these datasets belong to"}
+    ]
+  }
   ```
 
   `tissue` is what the dataset was measured in (the `Tissue` its
@@ -317,7 +474,22 @@ Details, including example responses, below.
   above.
 
   ```json
-  [{"id": 1, "name": "qtlreaper"}, {"id": 2, "name": "Rqtl"}, ...]
+  {
+    "data": [
+      {"id": 1, "name": "qtlreaper"},
+      {"id": 2, "name": "Rqtl"},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/groups", "description": "Groups, each with the mapping tool offered for it (`mapping_method`)"}
+    ]
+  }
   ```
 
 - `GET /accessions/{accession}` - resolves a GeneNetwork accession
@@ -329,9 +501,23 @@ Details, including example responses, below.
   dataset has the accession. Needs `SQL_URI`, same as `/species` above.
 
   ```json
-  {"accession": 602, "name": "BXDPublish",
-   "title": "BXD Published Phenotypes", "category": "publish",
-   "group": "BXD"}
+  {
+    "data": {
+      "accession": 602, "name": "BXDPublish",
+      "title": "BXD Published Phenotypes", "category": "publish",
+      "group": "BXD"
+    },
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/groups/BXD", "description": "The group the dataset belongs to"},
+      {"href": "/groups/BXD/traits", "description": "The dataset's published traits (can be very large)"}
+    ]
+  }
   ```
 
 - `GET /publications/{pubmed_id}/traits` - returns every published
@@ -345,6 +531,36 @@ Details, including example responses, below.
   and there is no pagination yet. Needs `SQL_URI`, same as `/species`
   above.
 
+  ```json
+  {
+    "data": [
+      {"id": 17967, "phenotype_id": 16502, "publication_id": 13584,
+       "mean": 6038.655919692095, "locus": "rsm10000012868",
+       "lrs": 10.535408722907198, "lod": 2.2883164037591652,
+       "additive": -647.5889092087912, "nsamples": 34,
+       "pre_publication_description": "Blood chemistry: Blood 5-hydroxytryptamine (5-HT, serotonin) level in ad...",
+       "post_publication_description": "Blood chemistry: Blood 5-hydroxytryptamine (5-HT, serotonin) level in ad...",
+       "original_description": null, "units": "[pg/ul]", "pubmed_id": 24102824,
+       "title": "Evaluation of heritable determinants of blood and brain serotonin homeos...",
+       "authors": "Ye R, Carneiro AM, Airey D, Sanders-Bush E, Williams RW, Lu L, Wang J, Z...",
+       "journal": "Genes, brain, and behavior", "volume": null,
+       "pages": "247-260", "month": "Mar", "year": "2014",
+       "dataset": "BXDPublish", "abbreviation": "5HT_Blood_M",
+       "url": "https://genenetwork.org/show_trait?trait_id=17967&dataset=BXDPublish"},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": ["lod = lrs / 4.604"],
+    "next": [
+      {"href": "/traits/BXDPublish/17967", "description": "Metadata of the first trait"}
+    ]
+  }
+  ```
+
 - `GET /datasets/{dataset}` - returns every column of the matching row
   of the `ProbeSetFreeze` table, matched against `Name`, `Name2`,
   `FullName`, `ShortName` or numeric `Id` (matching GeneNetwork2's
@@ -354,6 +570,28 @@ Details, including example responses, below.
   endpoint isn't scoped under `/groups/{group}`. Needs `SQL_URI`, same
   as `/species` above.
 
+  ```json
+  {
+    "data": {
+      "id": 1, "probe_freeze_id": 10, "name": "Br_U_0803_M",
+      "name2": "BXDMicroArray_ProbeSet_August03",
+      "full_name": "Brain U74Av2 08/03 MAS5",
+      "short_name": "Brain U74Av2 08/03 MAS5", "create_time": "2003-08-01",
+      "public": 0, "confidentiality": 0, "data_scale": "log2",
+      "tissue": "Brain mRNA"
+    },
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/datasets/Br_U_0803_M/probesets", "description": "The expression traits (probesets) of this dataset (can be very large)"}
+    ]
+  }
+  ```
+
 - `GET /datasets/{dataset}/probesets` - returns every expression
   (ProbeSet) trait belonging to a dataset, the listing equivalent of
   `/datasets/{dataset}/probesets/{probeset}` (same fields, same join,
@@ -364,10 +602,25 @@ Details, including example responses, below.
   see docs/gn-auth.md. Needs `SQL_URI`, same as `/species` above.
 
   ```json
-  [
-    {"probeset_id": 1, "name": "100001_at", "symbol": "Cd3g", ...},
-    ...
-  ]
+  {
+    "data": [
+      {"probeset_id": 1, "name": "100001_at", "symbol": "Cd3g",
+       "description": "CD3d antigen, gamma polypeptide", "chr": "9",
+       "mb": 44.970689, "mean": 5.48794285714286, "locus": "rs13480619",
+       "lrs": 12.590069931048, "lod": 2.7345938164743697, "p_value": 0.269,
+       "additive": -0.28515625},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": ["lod = lrs / 4.604"],
+    "next": [
+      {"href": "/datasets/Br_U_0803_M", "description": "The dataset these probesets belong to"}
+    ]
+  }
   ```
 
 - `GET /datasets/{dataset}/probesets/{probeset}` - returns one
@@ -381,11 +634,25 @@ Details, including example responses, below.
   no dataset matches, or if the dataset has no such probeset.
 
   ```json
-  {"probeset_id": 1, "name": "100001_at", "symbol": "Cd3g",
-   "description": "...", "chr": "9", "mb": 44.96,
-   "mean": 5.487942857142857, "locus": "rs13480619",
-   "lrs": 12.590069931048, "lod": 2.735, "p_value": 0.269,
-   "additive": -0.28515625}
+  {
+    "data": {
+      "probeset_id": 1, "name": "100001_at", "symbol": "Cd3g",
+      "description": "CD3d antigen, gamma polypeptide", "chr": "9",
+      "mb": 44.970689, "mean": 5.48794285714286, "locus": "rs13480619",
+      "lrs": 12.590069931048, "lod": 2.7345938164743697, "p_value": 0.269,
+      "additive": -0.28515625
+    },
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": ["lod = lrs / 4.604"],
+    "next": [
+      {"href": "/datasets/Br_U_0803_M/probesets/100001_at/values", "description": "The probeset's value in each strain"},
+      {"href": "/datasets/Br_U_0803_M", "description": "The dataset this probeset belongs to"}
+    ]
+  }
   ```
 
   Needs `SQL_URI`, same as `/species` above.
@@ -398,11 +665,22 @@ Details, including example responses, below.
   matches, or if the dataset has no such probeset.
 
   ```json
-  [
-    {"name": "B6D2F1", "value": 5.742},
-    {"name": "BXD1", "value": 6.414},
-    ...
-  ]
+  {
+    "data": [
+      {"name": "B6D2F1", "value": 5.742000102996826},
+      {"name": "BXD1", "value": 6.414000034332275},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/datasets/Br_U_0803_M/probesets/100001_at", "description": "The probeset's metadata"}
+    ]
+  }
   ```
 
   Needs `SQL_URI`, same as `/species` above.
@@ -440,19 +718,53 @@ accepts: the `PublishFreeze`'s own `Name`/`ShortName`/`Id` (e.g.
   stops at the token.
 
   ```json
-  [
-    {"category": "probeset", "probeset_id": 1, "name": "100001_at", ...},
-    ...
-  ]
+  {
+    "data": [
+      {"category": "probeset", "probeset_id": 1, "name": "100001_at",
+       "symbol": "Cd3g", "description": "CD3d antigen, gamma polypeptide",
+       "chr": "9", "mb": 44.970689, "mean": 5.48794285714286,
+       "locus": "rs13480619", "lrs": 12.590069931048,
+       "lod": 2.7345938164743697, "p_value": 0.269, "additive": -0.28515625},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": ["lod = lrs / 4.604"],
+    "next": []
+  }
   ```
 
   or, for a Publish dataset:
 
   ```json
-  [
-    {"category": "publish", "id": 10001, "phenotype_id": 4, ...},
-    ...
-  ]
+  {
+    "data": [
+      {"category": "publish", "id": 10001, "phenotype_id": 4,
+       "publication_id": 116, "mean": 52.13529418496525, "locus": "rs48756159",
+       "lrs": 13.497491147108706, "lod": 2.931687912056626,
+       "additive": 2.3944443506944437, "nsamples": 34,
+       "pre_publication_description": "Central nervous system, morphology: Cerebellum weight, whole, bilateral...",
+       "post_publication_description": "Central nervous system, morphology: Cerebellum weight, whole, bilateral...",
+       "original_description": "Original post publication description: Cerebellum weight [mg]",
+       "units": "mg", "pubmed_id": 11438585,
+       "title": "Genetic control of the mouse cerebellum: identification of quantitative...",
+       "authors": "Airey DC, Lu L, Williams RW", "journal": "J Neuroscience",
+       "volume": "21", "pages": "5099-5109", "month": null, "year": "2001",
+       "dataset": "BXDPublish", "abbreviation": "Cerebellum_Weight",
+       "url": "https://genenetwork.org/show_trait?trait_id=10001&dataset=BXDPublish"},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": ["lod = lrs / 4.604"],
+    "next": []
+  }
   ```
 
 - `GET /traits/{dataset}/{trait}` - one trait's metadata, tagged by
@@ -467,8 +779,24 @@ accepts: the `PublishFreeze`'s own `Name`/`ShortName`/`Id` (e.g.
   couldn't be reached. Needs `SQL_URI`, same as `/species` above.
 
   ```json
-  {"category": "probeset", "probeset_id": 1, "name": "100001_at",
-   "symbol": "Cd3g", "mean": 5.487942857142857, ...}
+  {
+    "data": {
+      "category": "probeset", "probeset_id": 1, "name": "100001_at",
+      "symbol": "Cd3g", "description": "CD3d antigen, gamma polypeptide",
+      "chr": "9", "mb": 44.970689, "mean": 5.48794285714286,
+      "locus": "rs13480619", "lrs": 12.590069931048, "lod": 2.7345938164743697,
+      "p_value": 0.269, "additive": -0.28515625
+    },
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": ["lod = lrs / 4.604"],
+    "next": [
+      {"href": "/traits/Br_U_0803_M/100001_at/values", "description": "The trait's value in each strain"}
+    ]
+  }
   ```
 
 - `GET /traits/{dataset}/{trait}/values` - that trait's value in each
@@ -478,11 +806,22 @@ accepts: the `PublishFreeze`'s own `Name`/`ShortName`/`Id` (e.g.
   `/traits/{dataset}/{trait}`.
 
   ```json
-  [
-    {"name": "BXD1", "value": 61.400002},
-    {"name": "BXD2", "value": 49.0},
-    ...
-  ]
+  {
+    "data": [
+      {"name": "BXD1", "value": 61.400001525878906},
+      {"name": "BXD11", "value": 53.099998474121094},
+      ...
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": [],
+    "next": [
+      {"href": "/traits/BXDPublish/10001", "description": "The trait's metadata"}
+    ]
+  }
   ```
 - `GET /search` - free-text search across GN traits (see
   `docs/search-engines.md` for switching between the gn3 proxy and
@@ -509,6 +848,34 @@ accepts: the `PublishFreeze`'s own `Name`/`ShortName`/`Id` (e.g.
   Needs a reachable gn3, configured via the `GN3_URL` config key
   (default `http://127.0.0.1:5003/api/`).
 
+  ```json
+  {
+    "data": [
+      {"name": "17994", "dataset": "BXDPublish",
+       "dataset_fullname": "BXD Published Phenotypes", "group": "BXD",
+       "species": "mouse", "authors": ["Ye R", "Carneiro AM", ...],
+       "year": 2014,
+       "description": "Central nervous system, protein expression: Midbrain serotonin transport...",
+       "mean": 1627.7004466337316, "additive": 233.98946836805567,
+       "lrs": 16.49128337950074, "lod": 3.5819468678324804,
+       "locus": "rsm10000013922", "abbreviation": "SERT_MB_M",
+       "geno_chr": "19", "geno_mb": 58.673324, "inbredsetcode": "BXD",
+       "pubmed_id": 24405699,
+       "pubmed_link": "http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?cmd=Retrieve&db=PubMed&lis..."}
+    ],
+    "meta": {
+      "state": "complete",
+      "took_ms": 3,
+      "request_id": "d4f1f9a0-62d7-4a52-9d51-62b0c8bfa5f5"
+    },
+    "notes": ["lod = lrs / 4.604"],
+    "next": [
+      {"href": "/search?q=serotonin+AND+midbrain+AND+group%3ABXD&limit=1&page=2", "description": "The next page of hits"},
+      {"href": "/traits/BXDPublish/17994", "description": "Metadata of the top hit"}
+    ]
+  }
+  ```
+
 - `GET /openapi.json` - returns an OpenAPI 3.1 document describing the
   endpoints above; see [OpenAPI](#openapi) below.