Collaborative BrAPI v2.1 MCP workspace: studies, germplasm, genotypes across Breedbase, T3, more.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Pull observations across one or more studies and pivot them into a germplasm × trait matrix materialized as a canvas dataframe. Returns a dataframe handle (read it with brapi_dataframe_describe and brapi_dataframe_query) plus a summary of dimensions and aggregate method. Long-form output is suitable for downstream GROUP BY analysis by study, germplasm, or variable. A study whose pull fails is named in warnings and the rest still build the matrix; the call fails only when every study failed.
studyDbIds to include in the matrix. At least one is required — the tool is study-anchored to avoid full-table scans.
Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here.
Matrix shape. `wide` — one row per germplasm, one column per variable, cell = aggregated value. `long` — one row per observation with columns: germplasmDbId, observationVariableDbId, studyDbId, value, replicateIndex. When `aggregate:"all"` is combined with `shape:"wide"`, the output falls back to long form with a replicateIndex column.
How to aggregate replicate observations (multiple readings of the same variable on the same germplasm). `mean` and `median` attempt numeric conversion and skip non-numeric values (e.g. categorical traits). `first` keeps the first value seen. `all` keeps every replicate as a separate row (produces long-form output even when shape is "wide"). Default: `mean`.
Optional subset of germplasmDbIds to include. Omit to include all germplasm found in the queried studies.
Cap on matching observations collected per study. Omit for the deployment default. A study that stops at it is reported as truncated.
Optional subset of observationVariableDbIds to include. Omit to include all variables found in the queried studies.
Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.
Pull observations across one or more studies and pivot them into a germplasm × trait matrix materialized as a canvas dataframe. Returns a dataframe handle (read it with brapi_dataframe_describe and brapi_dataframe_query) plus a summary of dimensions and aggregate method. Long-form output is suitable for downstream GROUP BY analysis by study, germplasm, or variable. A study whose pull fails is named in warnings and the rest still build the matrix; the call fails only when every study failed.
| Argument | Type | Description |
|---|---|---|
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| shape | string | Matrix shape. `wide` — one row per germplasm, one column per variable, cell = aggregated value. `long` — one row per observation with columns: germplasmDbId, observationVariableDbId, studyDbId, value, replicateIndex. When `aggregate:"all"` is combined with `shape:"wide"`, the output falls back to long form with a replicateIndex column. |
| studies* | array | studyDbIds to include in the matrix. At least one is required — the tool is study-anchored to avoid full-table scans. |
| aggregate | string | How to aggregate replicate observations (multiple readings of the same variable on the same germplasm). `mean` and `median` attempt numeric conversion and skip non-numeric values (e.g. categorical traits). `first` keeps the first value seen. `all` keeps every replicate as a separate row (produces long-form output even when shape is "wide"). Default: `mean`. |
| germplasm | array | Optional subset of germplasmDbIds to include. Omit to include all germplasm found in the queried studies. |
| loadLimit | integer | Cap on matching observations collected per study. Omit for the deployment default. A study that stops at it is reported as truncated. |
| variables | array | Optional subset of observationVariableDbIds to include. Omit to include all variables found in the queried studies. |
| extraFilters | object | Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"studies"
],
"properties": {
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"shape": {
"enum": [
"wide",
"long"
],
"type": "string",
"default": "wide",
"description": "Matrix shape. `wide` — one row per germplasm, one column per variable, cell = aggregated value. `long` — one row per observation with columns: germplasmDbId, observationVariableDbId, studyDbId, value, replicateIndex. When `aggregate:\"all\"` is combined with `shape:\"wide\"`, the output falls back to long form with a replicateIndex column."
},
"studies": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"minItems": 1,
"description": "studyDbIds to include in the matrix. At least one is required — the tool is study-anchored to avoid full-table scans."
},
"aggregate": {
"enum": [
"mean",
"median",
"first",
"all"
],
"type": "string",
"default": "mean",
"description": "How to aggregate replicate observations (multiple readings of the same variable on the same germplasm). `mean` and `median` attempt numeric conversion and skip non-numeric values (e.g. categorical traits). `first` keeps the first value seen. `all` keeps every replicate as a separate row (produces long-form output even when shape is \"wide\"). Default: `mean`."
},
"germplasm": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Optional subset of germplasmDbIds to include. Omit to include all germplasm found in the queried studies."
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap on matching observations collected per study. Omit for the deployment default. A study that stops at it is reported as truncated.",
"exclusiveMinimum": 0
},
"variables": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Optional subset of observationVariableDbIds to include. Omit to include all variables found in the queried studies."
},
"extraFilters": {
"type": "object",
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"additionalProperties": false
}Open a connection to a BrAPI v2 server, authenticate, and return the full orientation envelope (server identity, capability profile, content summary, suggested next tools). Other BrAPI tools connect an alias the server has a URL configured for (a built-in or operator-configured alias, or `default` on a deployment with a default server) on first use; call this to connect any other server by `baseUrl`, to pass `auth`, or to re-point an alias. Supports multiple concurrent connections via named aliases. Credentials can be configured server-side and omitted from this call. When a request carries no MCP session on a deployment without per-user auth, aliases live in one namespace shared by every such caller: re-registering an alias re-points their later calls to it. Built-in known servers (callable with no `baseUrl` or `auth` — public BrAPI v2 endpoints): `bti-breedbase-demo`, `bti-cassava`, `bti-sweetpotato`. Operator-configured aliases on this deployment (credentials and/or baseUrl read from server env vars): `default`, `cassava`. Aliases are shortcuts only; any other BrAPI v2 server is reachable by passing `baseUrl` directly.
| Argument | Type | Description |
|---|---|---|
| auth | any | Auth payload. Omit to use credentials configured server-side for this alias (or no auth when none are configured). |
| alias | string | Alias for this connection. Use distinct aliases to register multiple BrAPI servers in one session. |
| baseUrl | string | BrAPI v2 base URL (absolute URL) including any path prefix — e.g. https://test-server.brapi.org/brapi/v2. Omit to use the configured default for this alias. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"auth": {
"oneOf": [
{
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"type": "string",
"const": "none",
"description": "No authentication."
}
},
"description": "No-auth variant — public BrAPI endpoints."
},
{
"type": "object",
"required": [
"mode",
"token"
],
"properties": {
"mode": {
"type": "string",
"const": "bearer",
"description": "Pre-obtained bearer token."
},
"token": {
"type": "string",
"minLength": 1,
"description": "Pre-obtained access token, sent verbatim with each BrAPI request."
}
},
"description": "Bearer-token variant — caller already has an access token."
},
{
"type": "object",
"required": [
"mode",
"apiKey"
],
"properties": {
"mode": {
"type": "string",
"const": "api_key",
"description": "Static API key in a custom header."
},
"apiKey": {
"type": "string",
"minLength": 1,
"description": "API key issued by the BrAPI server."
},
"headerName": {
"type": "string",
"description": "HTTP header to send the API key in. Defaults to `Authorization`."
}
},
"description": "API-key variant — static key sent in a configurable header."
},
{
"type": "object",
"required": [
"mode",
"username",
"password"
],
"properties": {
"mode": {
"type": "string",
"const": "sgn",
"description": "Breedbase/SGN username+password; exchanged for a bearer token at /token."
},
"password": {
"type": "string",
"minLength": 1,
"description": "Password for the SGN/Breedbase username supplied above."
},
"username": {
"type": "string",
"minLength": 1,
"description": "SGN account username."
}
},
"description": "SGN variant — username/password exchanged at /token for a session bearer."
},
{
"type": "object",
"required": [
"mode",
"clientId",
"clientSecret"
],
"properties": {
"mode": {
"type": "string",
"const": "oauth2",
"description": "OAuth2 client-credentials flow; exchanged for an access token at connect time."
},
"clientId": {
"type": "string",
"minLength": 1,
"description": "OAuth2 client identifier registered with the upstream IdP."
},
"tokenUrl": {
"type": "string",
"description": "OAuth2 token endpoint (absolute URL). Defaults derived from the base URL when omitted."
},
"clientSecret": {
"type": "string",
"minLength": 1,
"description": "OAuth2 client secret paired with the clientId."
}
},
"description": "OAuth2 client-credentials variant."
}
],
"description": "Auth payload. Omit to use credentials configured server-side for this alias (or no auth when none are configured)."
},
"alias": {
"type": "string",
"default": "default",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Alias for this connection. Use distinct aliases to register multiple BrAPI servers in one session."
},
"baseUrl": {
"type": "string",
"description": "BrAPI v2 base URL (absolute URL) including any path prefix — e.g. https://test-server.brapi.org/brapi/v2. Omit to use the configured default for this alias."
}
},
"additionalProperties": false
}Start here after a spillover. Lists dataframes (or describes one) with columns, row counts, and originating-source provenance. The dataframe name appears inline on every find_* response that spilled (`result.dataframe.tableName`) — pass it as `dataframe` to inspect schema and provenance before writing the first brapi_dataframe_query. On a shared HTTP endpoint without per-caller auth, listing without a name is available only where each MCP session has its own workspace, and never to a request without a session; pass a known name instead.
| Argument | Type | Description |
|---|---|---|
| dataframe | string | When set, return only the named dataframe. Omit to list all dataframes. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"dataframe": {
"type": "string",
"minLength": 1,
"description": "When set, return only the named dataframe. Omit to list all dataframes."
}
},
"additionalProperties": false
}Run SQL across in-memory dataframes. Dataframes auto-populate when find_* tools spill (named `df_<uuid>`) — the dataframe name appears inline on every find_* response that spilled (`result.dataframe.tableName`), so the typical flow is find_* → read the name → query here. Use brapi_dataframe_describe to inspect schema and provenance for a known name. SELECT only — writes/DDL/COPY/PRAGMA/ATTACH/file-reads are rejected. Use SQL as the paging idiom: `LIMIT/OFFSET` to walk results, projection to trim columns, aggregation to summarize. Use `registerAs` to chain — the result lands as a new dataframe.
| Argument | Type | Description |
|---|---|---|
| sql* | string | SELECT statement against dataframes. Single statement only — writes, DDL, DESCRIBE / SUMMARIZE, file reads, and exports are rejected. Use brapi_dataframe_describe to discover available dataframes. SQL is the primary paging idiom: use `LIMIT/OFFSET` to walk a large dataframe, projection to trim columns, and aggregation (`COUNT`, `GROUP BY`, `AVG`) to summarize without materializing every row. |
| preview | integer | Cap the number of rows returned in this response. A value above `rowLimit` (or, when `rowLimit` is omitted, above the deployment-wide response cap) returns rows up to that ceiling. When omitted, the ceiling applies. Lower this with `registerAs` when you only need a sample to verify the query. |
| rowLimit | integer | Hard cap on rows materialized into the response, bounded by the deployment-wide response cap. For larger result sets, use `registerAs` to keep the full result queryable instead of raising this. |
| registerAs | string | Persist the full result as a new dataframe under this name. The response is bounded by preview and a 24,000-byte row budget. Conflicts fail — choose a different name, or remove the existing dataframe with brapi_dataframe_drop where this deployment enables it. Identifier rules: letters, digits, and underscores; must start with a letter or underscore; max 63 characters. |
List the valid filter names for a BrAPI endpoint (studies, germplasm, observations, variables, images, variants, locations) — companion lookup for the `extraFilters` passthrough on any `find_*` tool. Entries reflect the BrAPI v2.1 spec; individual servers may implement subsets.
| Argument | Type | Description |
|---|---|---|
| endpoint* | string | BrAPI endpoint to describe filters for. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"endpoint"
],
"properties": {
"endpoint": {
"enum": [
"germplasm",
"images",
"locations",
"observations",
"studies",
"variables",
"variants"
],
"type": "string",
"description": "BrAPI endpoint to describe filters for."
}
},
"additionalProperties": false
}Pull genotype calls for a germplasm × variant set and pivot them into a matrix. `matrix-json` registers a wide canvas dataframe; `vcf-lite` adds VCF-subset text in `vcf`; `plink` adds .ped/.map text in `ped`/`map`. Text formats pull /variants metadata and convert zero-based BrAPI start to one-based positions; missing/invalid positions use `.`/`0`. Read the dataframe with brapi_dataframe_describe and brapi_dataframe_query (SQL). `variantColumnLegend` maps SQL-safe columns to original variant IDs.
| Argument | Type | Description |
|---|---|---|
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| format* | string | Output format. `matrix-json` registers a wide canvas dataframe only. `vcf-lite` returns VCF-subset text and registers the dataframe. `plink` returns .ped/.map text and registers the dataframe. |
| maxCalls | integer | Lower the pull cap for this call. Omit to use the deployment ceiling. Cannot raise it: a value above the deployment ceiling is clamped down to it and the effective cap is reported in `warnings`. |
| maxColumns | integer | Lower the distinct-variant column cap for this call. Omit to use the deployment ceiling. Cannot raise it: a value above the deployment ceiling is clamped down to it. When the variant set resolves more distinct variants than the effective cap, the matrix is capped at that many variant columns, `truncated` is set, and the effective cap is reported in `warnings`. Independent of `maxCalls`, which bounds the row (call) pull. |
Pull genotype calls for a germplasm × variant set. Filter to bound cost — at minimum, set `variantSetDbId` or `germplasmDbIds`. The upstream pull is capped by deployment policy; when the pull is truncated, narrow the filters. results[] holds the leading calls up to `loadLimit` and a 24,000-byte budget; when it holds fewer than were collected, every collected call is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL) instead of paging row-by-row.
| Argument | Type | Description |
|---|---|---|
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| loadLimit | integer | Cap on rows returned inline. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any call was collected. When results[] holds fewer rows than were collected, every collected call lands in a dataframe — query it with brapi_dataframe_query (SQL) for the rest. Upstream pageSize is fixed for genotype calls, so this knob only affects the inline preview here (no spillover capacity tradeoff). |
| callFormat | string | Requested call-encoding format, when the server honors it. |
| callSetDbIds | array | Restrict to these call sets directly. |
Find germplasm by name, synonym, accession number, PUI, crop, or free-text query. Matches across registered synonyms. results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL) instead of paging row-by-row.
| Argument | Type | Description |
|---|---|---|
| text | string | Free-text query. Applied client-side as a case-insensitive substring match on germplasmName, germplasmPUI, accessionNumber, defaultDisplayName, and registered synonyms — no BrAPI server reliably supports a server-side free-text filter. Every upstream row is scanned when the filtered set fits one dataframe walk; above that, a miss on the first page stops the scan, and the warnings report how many rows were checked. Combine with `crops` / `genus` / etc. to narrow the upstream pull first. |
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| crops | array | Filter by common crop names. |
| genus | string | Botanical genus. |
| names | array | Filter by germplasm display names. |
Filter images by observation unit, observation, study, descriptive ontology term, file name, or MIME type. Returns metadata only — use brapi_get_image to fetch bytes inline. results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).
| Argument | Type | Description |
|---|---|---|
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| images | array | Filter by imageDbIds. |
| studies | array | Filter by studyDbIds. |
| loadLimit | integer | Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row. |
| mimeTypes | array | Filter by MIME type — e.g. "image/jpeg", "image/png". |
Find research stations / field sites by country, abbreviation, type, location ID, or free-text. Countries filter by ISO 3166-1 alpha-3 code via countryCodes, or by free-form English country name via countryNames (resolved client-side to alpha-3 — "Uganda" → "UGA"). Optional bbox parameter restricts rows to a latitude/longitude window. When no first-page row falls inside it under the spec GeoJSON [lon, lat, alt] reading and a row carries a Point geometry, bbox is retried with axes swapped; if that matches, the swapped reading is used (non-conformant servers store [lat, lon, alt]) with a warning and `coordinateAxisOrder: "swapped"`. results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).
| Argument | Type | Description |
|---|---|---|
| bbox | object | Optional post-fetch bounding box. Nonempty boxes require all four bounds with minimum <= maximum; malformed boxes fail. An empty object is omitted. |
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| loadLimit | integer | Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row. |
Pull observation records filtered by study, germplasm, variable, season, or observation unit. Without a studies, trials, observationUnits, or observations anchor, a GET query first runs a one-row count probe and skips the bulk pull (warnings says so) when the probe fails or reports more than 5,000 matches. results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when those bounds cut it short, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).
| Argument | Type | Description |
|---|---|---|
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| trials | array | Filter by trialDbIds. |
| seasons | array | Filter by seasonDbIds (e.g. "2022"). |
| studies | array | Filter by studyDbIds. |
| programs | array | Filter by programDbIds. |
| germplasm | array | Filter by germplasmDbIds. |
| loadLimit |
Locate studies matching crop, trial type, season, location, or program. Enriches results with program/trial/location context in one call. results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).
| Argument | Type | Description |
|---|---|---|
| crop | string | Filter by common crop name (single value). |
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| active | boolean | Restrict to active / inactive studies. |
| trials | array | Filter by trialDbIds. |
| seasons | array | Filter by seasons (e.g. "2022"). |
| programs | array | Filter by programDbIds. |
| loadLimit | integer | Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row. |
Find observation variables (traits) by name, trait class, ontology term, or free-text query. Free-text queries are ranked against every fetched row by PUI, name, synonym, and trait text; a candidate carries the ontology PUI of its row as termId when the row has one. results[] holds the leading rows up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).
| Argument | Type | Description |
|---|---|---|
| crop | string | Filter by common crop name (single value). |
| text | string | Free-text query. Ranks **every row the call fetched** (the whole dataframe walk, not just the first page) via the ontology resolver, then fills results[] — up to loadLimit and the 24,000-byte budget — with matches first and unmatched rows for context. Use exact filters (`variables`, `variableNames`, `variablePUIs`, `traitClasses`, `ontologies`) to actually narrow the upstream pull. Differs from `brapi_find_germplasm.text`, which drops unmatched rows. |
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| scales | array | Filter by scaleDbIds. |
| methods | array |
Find variant records by variant set, reference sequence, or genomic region (start/end, 0-based inclusive / exclusive per the BrAPI spec; servers may differ). results[] holds the leading matches up to loadLimit and a 24,000-byte budget; when it holds fewer rows than matched, the matched set is materialized as a dataframe — read it with brapi_dataframe_describe and brapi_dataframe_query (SQL).
| Argument | Type | Description |
|---|---|---|
| end | integer | Window end, 0-based exclusive. |
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| start | integer | Window start, 0-based inclusive. |
| variants | array | Filter by variantDbIds. |
| loadLimit | integer | Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row. |
Aggregate a single germplasm's observations across studies, returning per-variable statistics (n, mean, median, sd, min, max), contributing studies, seasons, and collection coverage. SGN/Breedbase uses advertised germplasm-scoped observation units with embedded measurements, including zeros. Other servers discover up to 200 studies before pulling per study. Pass studyDbIds to skip discovery and restrict collection to known studies. Per-study observation limits, page limits, failures, and incomplete scans appear in coverage and warnings. For the underlying matrix, use brapi_build_phenotype_matrix.
| Argument | Type | Description |
|---|---|---|
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| variables | array | Optional subset of observationVariableDbIds to aggregate. Omit to include every variable observed for the germplasm. |
| studyDbIds | array | Optional studyDbIds to restrict collection to known studies and skip automatic discovery. Omit to walk germplasm-scoped embedded units on SGN/Breedbase, or discover up to 200 studies on other servers. Find known study IDs with brapi_find_studies; some servers ignore its germplasm filter. |
| germplasmDbId* | string | The germplasmDbId to summarize performance for. |
Fetch a single germplasm by DbId with attributes and direct parents. Response companions report study count, direct parent count, and direct descendant count — signals for pedigree depth and observation coverage.
| Argument | Type | Description |
|---|---|---|
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| germplasmDbId* | string | Germplasm identifier. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"germplasmDbId"
],
"properties": {
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"germplasmDbId": {
"type": "string",
"pattern": "\\S",
"description": "Germplasm identifier."
}
},
"additionalProperties": false
}Fetch image bytes for up to 5 imageDbIds and return them inline as `type: image` content blocks. Falls back to the metadata `imageURL` when the server lacks dedicated image-content delivery or that request fails. No filesystem side-effects.
| Argument | Type | Description |
|---|---|---|
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| imageDbIds* | array | 1–5 image identifiers. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"imageDbIds"
],
"properties": {
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"imageDbIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"maxItems": 5,
"minItems": 1,
"description": "1–5 image identifiers."
}
},
"additionalProperties": false
}Fetch a single study by DbId with its program, trial, and location records resolved where those lookups succeed. Response includes cheap observation/observation-unit/variable counts as drill-down signals.
| Argument | Type | Description |
|---|---|---|
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| studyDbId* | string | Study identifier. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"studyDbId"
],
"properties": {
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"studyDbId": {
"type": "string",
"pattern": "\\S",
"description": "Study identifier."
}
},
"additionalProperties": false
}Passthrough to BrAPI GET /{path} without foreign-key resolution. List results (result array or result.data) return a leading preview within loadLimit and a 24,000-byte budget on each serialized row representation; an oversized first row returns no inline rows. Omitted fetched rows remain in a dataframe readable with brapi_dataframe_describe and brapi_dataframe_query. Explicit params.page/pageSize fetches only that upstream page, staging it if trimmed. Non-list results and envelope siblings are preserved. Emits a suggestion when a curated tool covers the endpoint.
| Argument | Type | Description |
|---|---|---|
| path* | string | Endpoint path — e.g. "/samples", "/methods". Leading "/" is optional. |
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| params | object | Query parameters to append. Arrays are repeated per BrAPI convention. |
| loadLimit | integer | Cap on rows returned inline. Omit for the deployment default. Rows beyond the cap land in a dataframe; query with brapi_dataframe_query (SQL) instead of paging row-by-row. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"path"
],
"properties": {
"path": {
"type": "string",
"pattern": "\\S",
"description": "Endpoint path — e.g. \"/samples\", \"/methods\". Leading \"/\" is optional."
},
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"params": {
"type": "object",
"description": "Query parameters to append. Arrays are repeated per BrAPI convention.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "array",
"items": {
"type": [
"string",
"number"
]
}
}
]
}
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap on rows returned inline. Omit for the deployment default. Rows beyond the cap land in a dataframe; query with brapi_dataframe_query (SQL) instead of paging row-by-row.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}Passthrough to BrAPI POST /search/{noun}, polling async search IDs. Sends loadLimit as the initial pageSize unless body.page/pageSize drives explicit paging. List previews fit loadLimit and a 24,000-byte budget on each serialized row representation; an oversized first row returns no inline rows. Every fetched row omitted inline stays in a dataframe readable with brapi_dataframe_describe and brapi_dataframe_query. Explicit paging fetches only the requested page, staging it if trimmed. Non-list results and envelope siblings are preserved; no distributions or foreign-key resolution.
| Argument | Type | Description |
|---|---|---|
| body* | object | Filter body passed verbatim to POST /search/{noun}. |
| noun* | string | Search noun — e.g. "observations", "calls", "germplasm". |
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| loadLimit | integer | Cap on rows returned inline. Omit for the deployment default. Rows beyond the cap land in a dataframe; query with brapi_dataframe_query (SQL) instead of paging row-by-row. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"noun",
"body"
],
"properties": {
"body": {
"type": "object",
"description": "Filter body passed verbatim to POST /search/{noun}.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"noun": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"minLength": 1,
"description": "Search noun — e.g. \"observations\", \"calls\", \"germplasm\"."
},
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap on rows returned inline. Omit for the deployment default. Rows beyond the cap land in a dataframe; query with brapi_dataframe_query (SQL) instead of paging row-by-row.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}Return the full orientation envelope for a BrAPI connection — server identity, capabilities, content counts, suggested finders, and notes. Pass forceRefresh to refetch the cached capability scan; pass an alias to read a non-default connection.
| Argument | Type | Description |
|---|---|---|
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via `brapi_connect` works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| forceRefresh | boolean | Bypass the cached capability profile and refetch from the server. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via `brapi_connect` works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"forceRefresh": {
"type": "boolean",
"default": false,
"description": "Bypass the cached capability profile and refetch from the server."
}
},
"additionalProperties": false
}Walk germplasm ancestry or descendancy as a deduplicated DAG with cycle detection and depth limits. leafCount counts graph terminals, confirmedLeafCount counts successfully verified leaves, and frontier records unresolved directions. Nodes and edges each fit loadLimit and a 24,000-byte preview budget; trimmed discovered graphs and already-fetched omitted relatives are staged for brapi_dataframe_describe and brapi_dataframe_query (SQL). Diagrams describe only the discovered graph, never unvisited relatives.
| Argument | Type | Description |
|---|---|---|
| alias | string | Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here. |
| diagram | string | Also return the walk as diagram source: `mermaid` (flowchart) or `dot` (Graphviz). Edges point parent → child, roots are bold, loop-closing edges are dashed. Omit for no diagram. |
| maxDepth | integer | Max generations to walk per direction (default 3, cap 10). |
| direction | string | Which direction to walk: ancestors (parents), descendants (progeny), or both — the union of the two walks. Ancestors are walked only upward and descendants only downward, so a descendant's other parent is not included. |
| loadLimit | integer |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"sql"
],
"properties": {
"sql": {
"type": "string",
"minLength": 1,
"description": "SELECT statement against dataframes. Single statement only — writes, DDL, DESCRIBE / SUMMARIZE, file reads, and exports are rejected. Use brapi_dataframe_describe to discover available dataframes. SQL is the primary paging idiom: use `LIMIT/OFFSET` to walk a large dataframe, projection to trim columns, and aggregation (`COUNT`, `GROUP BY`, `AVG`) to summarize without materializing every row."
},
"preview": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap the number of rows returned in this response. A value above `rowLimit` (or, when `rowLimit` is omitted, above the deployment-wide response cap) returns rows up to that ceiling. When omitted, the ceiling applies. Lower this with `registerAs` when you only need a sample to verify the query.",
"exclusiveMinimum": 0
},
"rowLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Hard cap on rows materialized into the response, bounded by the deployment-wide response cap. For larger result sets, use `registerAs` to keep the full result queryable instead of raising this.",
"exclusiveMinimum": 0
},
"registerAs": {
"type": "string",
"pattern": "^[A-Za-z_][A-Za-z0-9_]{0,62}$",
"description": "Persist the full result as a new dataframe under this name. The response is bounded by preview and a 24,000-byte row budget. Conflicts fail — choose a different name, or remove the existing dataframe with brapi_dataframe_drop where this deployment enables it. Identifier rules: letters, digits, and underscores; must start with a letter or underscore; max 63 characters."
}
},
"additionalProperties": false
}| germplasmDbIds | array | Restrict to these germplasm. Omit to pull all germplasm in the variant set (use with caution on large sets). |
| variantSetDbId* | string | Variant set to pull calls for. Required. List variant sets with brapi_raw_get({ path: "/variantsets" }) — add params.studyDbId to narrow to one study or genotyping project — and read variantSetDbId from the rows. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"variantSetDbId",
"format"
],
"properties": {
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"format": {
"enum": [
"plink",
"vcf-lite",
"matrix-json"
],
"type": "string",
"description": "Output format. `matrix-json` registers a wide canvas dataframe only. `vcf-lite` returns VCF-subset text and registers the dataframe. `plink` returns .ped/.map text and registers the dataframe."
},
"maxCalls": {
"type": "integer",
"maximum": 500000,
"description": "Lower the pull cap for this call. Omit to use the deployment ceiling. Cannot raise it: a value above the deployment ceiling is clamped down to it and the effective cap is reported in `warnings`.",
"exclusiveMinimum": 0
},
"maxColumns": {
"type": "integer",
"maximum": 500000,
"description": "Lower the distinct-variant column cap for this call. Omit to use the deployment ceiling. Cannot raise it: a value above the deployment ceiling is clamped down to it. When the variant set resolves more distinct variants than the effective cap, the matrix is capped at that many variant columns, `truncated` is set, and the effective cap is reported in `warnings`. Independent of `maxCalls`, which bounds the row (call) pull.",
"exclusiveMinimum": 0
},
"germplasmDbIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Restrict to these germplasm. Omit to pull all germplasm in the variant set (use with caution on large sets)."
},
"variantSetDbId": {
"type": "string",
"pattern": "\\S",
"description": "Variant set to pull calls for. Required. List variant sets with brapi_raw_get({ path: \"/variantsets\" }) — add params.studyDbId to narrow to one study or genotyping project — and read variantSetDbId from the rows."
}
},
"additionalProperties": false
}| variantDbIds |
| array |
| Restrict to specific variants. |
| germplasmDbIds | array | Restrict to these germplasm (call sets). |
| variantSetDbId | string | Scope calls to a single variant set. Strongly recommended. List variant sets with brapi_raw_get({ path: "/variantsets" }) — add params.studyDbId to narrow to one study or genotyping project — and read variantSetDbId from the rows. |
| variantSetDbIds | array | Alternative: multiple variant sets at once, found the same way. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap on rows returned inline. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any call was collected. When results[] holds fewer rows than were collected, every collected call lands in a dataframe — query it with brapi_dataframe_query (SQL) for the rest. Upstream pageSize is fixed for genotype calls, so this knob only affects the inline preview here (no spillover capacity tradeoff).",
"exclusiveMinimum": 0
},
"callFormat": {
"enum": [
"VCF",
"FLAPJACK",
"DARTSEQ",
"JSON"
],
"type": "string",
"description": "Requested call-encoding format, when the server honors it."
},
"callSetDbIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Restrict to these call sets directly."
},
"variantDbIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Restrict to specific variants."
},
"germplasmDbIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Restrict to these germplasm (call sets)."
},
"variantSetDbId": {
"type": "string",
"pattern": "\\S",
"description": "Scope calls to a single variant set. Strongly recommended. List variant sets with brapi_raw_get({ path: \"/variantsets\" }) — add params.studyDbId to narrow to one study or genotyping project — and read variantSetDbId from the rows."
},
"variantSetDbIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Alternative: multiple variant sets at once, found the same way."
}
},
"additionalProperties": false
}| species |
| string |
| Botanical species. |
| synonyms | array | Match registered synonyms. |
| loadLimit | integer | Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row. |
| collections | array | Filter by germplasm collection names. |
| extraFilters | object | Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict. |
| germplasmPUIs | array | Persistent unique identifiers. |
| germplasmDbIds | array | Filter by DbIds. |
| accessionNumbers | array | Filter by accession numbers (gene-bank catalog codes). |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"text": {
"type": "string",
"pattern": "^$|\\S",
"description": "Free-text query. Applied client-side as a case-insensitive substring match on germplasmName, germplasmPUI, accessionNumber, defaultDisplayName, and registered synonyms — no BrAPI server reliably supports a server-side free-text filter. Every upstream row is scanned when the filtered set fits one dataframe walk; above that, a miss on the first page stops the scan, and the warnings report how many rows were checked. Combine with `crops` / `genus` / etc. to narrow the upstream pull first."
},
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"crops": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by common crop names."
},
"genus": {
"type": "string",
"pattern": "\\S",
"description": "Botanical genus."
},
"names": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by germplasm display names."
},
"species": {
"type": "string",
"pattern": "\\S",
"description": "Botanical species."
},
"synonyms": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Match registered synonyms."
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row.",
"exclusiveMinimum": 0
},
"collections": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by germplasm collection names."
},
"extraFilters": {
"type": "object",
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"germplasmPUIs": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Persistent unique identifiers."
},
"germplasmDbIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by DbIds."
},
"accessionNumbers": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by accession numbers (gene-bank catalog codes)."
}
},
"additionalProperties": false
}| extraFilters |
| object |
| Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict. |
| observations | array | Filter by observationDbIds. |
| imageFileNames | array | Filter by uploaded file name. |
| observationUnits | array | Filter by observationUnitDbIds. |
| descriptiveOntologyTerms | array | Filter by ontology tags (e.g. "CO_334:plot"). |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"images": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by imageDbIds."
},
"studies": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by studyDbIds."
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row.",
"exclusiveMinimum": 0
},
"mimeTypes": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by MIME type — e.g. \"image/jpeg\", \"image/png\"."
},
"extraFilters": {
"type": "object",
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"observations": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by observationDbIds."
},
"imageFileNames": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by uploaded file name."
},
"observationUnits": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by observationUnitDbIds."
},
"descriptiveOntologyTerms": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by ontology tags (e.g. \"CO_334:plot\")."
}
},
"additionalProperties": false
}| locations | array | Filter by locationDbIds. |
| countryCodes | array | Country codes; alphabetic codes are uppercased, numeric upstream codes are preserved. |
| countryNames | array | English country names or aliases (e.g. "Uganda", "United States", "USA") resolved to alpha-3 codes and merged into countryCodes. Unresolved names warn when another effective country restriction remains; otherwise the call fails. Prefer countryCodes when known. |
| extraFilters | object | Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict. |
| abbreviations | array | Short location abbreviations. |
| locationNames | array | Filter by display name. |
| locationTypes | array | Location type — e.g. "Research Station", "Field". |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"bbox": {
"type": "object",
"properties": {
"maxLat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Maximum latitude in WGS84 decimal degrees."
},
"maxLon": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Maximum longitude in WGS84 decimal degrees."
},
"minLat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Minimum latitude in WGS84 decimal degrees."
},
"minLon": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Minimum longitude in WGS84 decimal degrees."
}
},
"description": "Optional post-fetch bounding box. Nonempty boxes require all four bounds with minimum <= maximum; malformed boxes fail. An empty object is omitted."
},
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row.",
"exclusiveMinimum": 0
},
"locations": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by locationDbIds."
},
"countryCodes": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Country codes; alphabetic codes are uppercased, numeric upstream codes are preserved."
},
"countryNames": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "English country names or aliases (e.g. \"Uganda\", \"United States\", \"USA\") resolved to alpha-3 codes and merged into countryCodes. Unresolved names warn when another effective country restriction remains; otherwise the call fails. Prefer countryCodes when known."
},
"extraFilters": {
"type": "object",
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"abbreviations": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Short location abbreviations."
},
"locationNames": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by display name."
},
"locationTypes": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Location type — e.g. \"Research Station\", \"Field\"."
}
},
"additionalProperties": false
}| integer |
| Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row. |
| variables | array | Filter by observationVariableDbIds. |
| timestampTo | string | ISO 8601 end of the observation-time window. |
| extraFilters | object | Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict. |
| observations | array | Filter by observationDbIds. |
| timestampFrom | string | ISO 8601 start of the observation-time window. |
| observationUnits | array | Filter by observationUnitDbIds. |
| observationLevels | array | Observation unit level (plot, plant, field, etc.). |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"trials": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by trialDbIds."
},
"seasons": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by seasonDbIds (e.g. \"2022\")."
},
"studies": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by studyDbIds."
},
"programs": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by programDbIds."
},
"germplasm": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by germplasmDbIds."
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row.",
"exclusiveMinimum": 0
},
"variables": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by observationVariableDbIds."
},
"timestampTo": {
"type": "string",
"pattern": "\\S",
"description": "ISO 8601 end of the observation-time window."
},
"extraFilters": {
"type": "object",
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"observations": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by observationDbIds."
},
"timestampFrom": {
"type": "string",
"pattern": "\\S",
"description": "ISO 8601 start of the observation-time window."
},
"observationUnits": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by observationUnitDbIds."
},
"observationLevels": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Observation unit level (plot, plant, field, etc.)."
}
},
"additionalProperties": false
}| locations | array | Filter by locationDbIds (server-side identifiers, not display names). On servers that ignore this filter on /studies, it is applied client-side over the scanned studies, and a study with no locationDbId never matches. |
| studyNames | array | Filter by study display name. |
| trialTypes | array | Filter by study types. |
| extraFilters | object | Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"crop": {
"type": "string",
"pattern": "\\S",
"description": "Filter by common crop name (single value)."
},
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"active": {
"type": "boolean",
"description": "Restrict to active / inactive studies."
},
"trials": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by trialDbIds."
},
"seasons": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by seasons (e.g. \"2022\")."
},
"programs": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by programDbIds."
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row.",
"exclusiveMinimum": 0
},
"locations": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by locationDbIds (server-side identifiers, not display names). On servers that ignore this filter on /studies, it is applied client-side over the scanned studies, and a study with no locationDbId never matches."
},
"studyNames": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by study display name."
},
"trialTypes": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by study types."
},
"extraFilters": {
"type": "object",
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"additionalProperties": false
}| Filter by methodDbIds. |
| studies | array | Filter by studyDbId. Multiple distinct studies are collected under shared page, row and time budgets and unioned by variable ID with studyDbIds provenance; studyCoverage reports incomplete studies. |
| loadLimit | integer | Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row. |
| variables | array | Filter by observationVariableDbIds. |
| ontologies | array | Filter by ontologyDbIds. |
| extraFilters | object | Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict. |
| traitClasses | array | Filter by trait class. |
| variablePUIs | array | Filter by persistent ontology URIs. |
| variableNames | array | Filter by exact observationVariableNames. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"crop": {
"type": "string",
"pattern": "\\S",
"description": "Filter by common crop name (single value)."
},
"text": {
"type": "string",
"pattern": "^$|\\S",
"description": "Free-text query. Ranks **every row the call fetched** (the whole dataframe walk, not just the first page) via the ontology resolver, then fills results[] — up to loadLimit and the 24,000-byte budget — with matches first and unmatched rows for context. Use exact filters (`variables`, `variableNames`, `variablePUIs`, `traitClasses`, `ontologies`) to actually narrow the upstream pull. Differs from `brapi_find_germplasm.text`, which drops unmatched rows."
},
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"scales": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by scaleDbIds."
},
"methods": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by methodDbIds."
},
"studies": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by studyDbId. Multiple distinct studies are collected under shared page, row and time budgets and unioned by variable ID with studyDbIds provenance; studyCoverage reports incomplete studies."
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row.",
"exclusiveMinimum": 0
},
"variables": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by observationVariableDbIds."
},
"ontologies": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by ontologyDbIds."
},
"extraFilters": {
"type": "object",
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"traitClasses": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by trait class."
},
"variablePUIs": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by persistent ontology URIs."
},
"variableNames": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by exact observationVariableNames."
}
},
"additionalProperties": false
}| references |
| array |
| Filter by referenceDbIds. |
| variantSets | array | Filter by variantSetDbIds. |
| extraFilters | object | Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict. |
| referenceName | string | Reference display name (e.g. "chr01", "chr1"). |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"end": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Window end, 0-based exclusive.",
"exclusiveMinimum": 0
},
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"start": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Window start, 0-based inclusive."
},
"variants": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by variantDbIds."
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Cap on rows returned inline in results[]. Omit for the deployment default. results[] also stops at a 24,000-byte budget, whichever bound comes first, and keeps at least one row when any matched. When results[] holds fewer rows than matched, the matched rows are staged in a dataframe (marked truncated if the upstream walk stopped short); query it with brapi_dataframe_query (SQL) instead of paging row-by-row.",
"exclusiveMinimum": 0
},
"references": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by referenceDbIds."
},
"variantSets": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Filter by variantSetDbIds."
},
"extraFilters": {
"type": "object",
"description": "Extra BrAPI filters forwarded verbatim. Valid keys vary by endpoint; brapi_describe_filters enumerates them. Named params on this tool take precedence on conflict.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"referenceName": {
"type": "string",
"pattern": "\\S",
"description": "Reference display name (e.g. \"chr01\", \"chr1\")."
}
},
"additionalProperties": false
}{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"germplasmDbId"
],
"properties": {
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"variables": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Optional subset of observationVariableDbIds to aggregate. Omit to include every variable observed for the germplasm."
},
"studyDbIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Optional studyDbIds to restrict collection to known studies and skip automatic discovery. Omit to walk germplasm-scoped embedded units on SGN/Breedbase, or discover up to 200 studies on other servers. Find known study IDs with brapi_find_studies; some servers ignore its germplasm filter."
},
"germplasmDbId": {
"type": "string",
"pattern": "\\S",
"description": "The germplasmDbId to summarize performance for."
}
},
"additionalProperties": false
}| Row ceiling for each inline graph/frontier preview, also bounded by a 24,000-byte budget. Omit for the deployment default. A first row exceeding the byte budget yields zero preview rows; retrieve narrower projections from the staged dataframe. |
| germplasmDbIds* | array | Starting germplasm (1–20 roots). All roots are walked concurrently. |
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"germplasmDbIds"
],
"properties": {
"alias": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]+$",
"description": "Connection alias. Omit to use alias `default`. An alias registered via brapi_connect works, and so does one the server has a URL configured for (a built-in alias, an operator-configured alias, or `default` on a deployment with a default server), which connects on first use. Calls that used a non-default alias must pass that same alias here."
},
"diagram": {
"enum": [
"mermaid",
"dot"
],
"type": "string",
"description": "Also return the walk as diagram source: `mermaid` (flowchart) or `dot` (Graphviz). Edges point parent → child, roots are bold, loop-closing edges are dashed. Omit for no diagram."
},
"maxDepth": {
"type": "integer",
"default": 3,
"maximum": 10,
"description": "Max generations to walk per direction (default 3, cap 10).",
"exclusiveMinimum": 0
},
"direction": {
"enum": [
"ancestors",
"descendants",
"both"
],
"type": "string",
"default": "ancestors",
"description": "Which direction to walk: ancestors (parents), descendants (progeny), or both — the union of the two walks. Ancestors are walked only upward and descendants only downward, so a descendant's other parent is not included."
},
"loadLimit": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row ceiling for each inline graph/frontier preview, also bounded by a 24,000-byte budget. Omit for the deployment default. A first row exceeding the byte budget yields zero preview rows; retrieve narrower projections from the staged dataframe.",
"exclusiveMinimum": 0
},
"germplasmDbIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"maxItems": 20,
"minItems": 1,
"description": "Starting germplasm (1–20 roots). All roots are walked concurrently."
}
},
"additionalProperties": false
}