brapi-mcp-server
An open-source MCP server that provides a collaborative workspace for accessing BrAPI v2.1 compliant plant breeding data. It enables agents to search studies, germplasm, genotypes, and observations across multiple databases like Breedbase and T3, build phenotype matrices, and walk pedigrees.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://brapi.caseyjhand.com/mcpWhat its tools do
22 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.
Read-only (20)
brapi_build_phenotype_matrixbrapi_server_infobrapi_describe_filtersbrapi_find_studiesbrapi_get_studybrapi_find_germplasmbrapi_get_germplasmbrapi_walk_pedigreebrapi_germplasm_performancebrapi_find_variablesbrapi_find_observationsbrapi_find_imagesbrapi_get_imagebrapi_find_locationsbrapi_find_variantsbrapi_find_genotype_callsbrapi_export_genotype_matrixbrapi_dataframe_describebrapi_raw_getbrapi_raw_search
Can change data (2)
Checks and signals
Each line is separate evidence, not a trust score.
- Passed Endpoint answered the live check ·
- Availability 1 of 1 checks passed in 30 days
What you can do with it
- Search studies, germplasm, and genotypes across multiple BrAPI v2-compliant servers
- Build phenotype and genotype matrices from observation data
- Walk plant pedigrees to trace ancestry or descendancy
- Authenticate to BrAPI servers and retrieve orientation envelopes
Source and maintenance
Community listingRegistry 0.10.1
- Maintenance checked
Protocol and capabilities
- Server
- brapi-mcp-server 0.10.1
- MCP protocol negotiated in check
- 2025-11-25
- Tools
- 22 advertised
- Resources
- 9 advertised
- Resource templates
- 4 advertised
- Prompts
- 2 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"logging": {},
"prompts": {
"listChanged": true
},
"resources": {
"subscribe": true,
"listChanged": true
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
22 advertised
brapi_connect — Brapi Connect
Open-world
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.
brapi_connect input schema
{
"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
}brapi_connect output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"baseUrl",
"server",
"auth",
"capabilities",
"dialect",
"content",
"nextToolSuggestions",
"notes",
"fetchedAt"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"auth": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"enum": [
"none",
"sgn",
"oauth2",
"api_key",
"bearer"
],
"type": "string",
"description": "Auth mode of the active connection."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 token-expiry timestamp, when known."
},
"headerName": {
"type": "string",
"description": "HTTP header carrying credentials."
}
},
"description": "Auth summary for the active connection.",
"additionalProperties": false
},
"alias": {
"type": "string",
"description": "Connection alias."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"auth_session_required",
"auth_base_url_mismatch",
"alias_base_url_unset",
"alias_base_url_invalid",
"private_address_blocked",
"auth_token_exchange_failed",
"auth_no_access_token",
"upstream_unauthorized",
"upstream_forbidden",
"capability_discovery_unavailable"
],
"description": "Machine-readable failure mode. Declared by this tool: `auth_session_required`: Caller-supplied credentials on an HTTP deployment without per-user auth, from a request that carries no MCP session. `auth_base_url_mismatch`: The alias has server-configured credentials and the supplied baseUrl differs from the server configured for it. `alias_base_url_unset`: The alias has server-configured credentials but no base URL of its own (no BRAPI_<ALIAS>_BASE_URL and no enabled built-in), so they pair with no server. `alias_base_url_invalid`: With no `baseUrl` passed, the base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL, or the OAuth token URL, is on a private or reserved address this server may not reach. `auth_token_exchange_failed`: SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Token endpoint responded but did not return an access_token. `upstream_unauthorized`: The server answered HTTP 401 on /serverinfo or /calls — it requires login for capability discovery. `upstream_forbidden`: The server answered HTTP 403 on /serverinfo or /calls — the request (anonymous or credentialed) lacks read access. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notes": {
"type": "array",
"items": {
"type": "string",
"description": "Server-specific quirk or degradation note."
},
"description": "Server-specific quirks or degradation notes."
},
"server": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Server display name from /serverinfo."
},
"description": {
"type": "string",
"description": "Free-form server description."
},
"brapiVersion": {
"type": "string",
"description": "Highest BrAPI version the server reports."
},
"contactEmail": {
"type": "string",
"description": "Contact email for the operator."
},
"organizationURL": {
"type": "string",
"description": "Organization website."
},
"documentationURL": {
"type": "string",
"description": "Documentation URL for this server."
},
"organizationName": {
"type": "string",
"description": "Hosting organization."
}
},
"description": "Normalized server identity block.",
"additionalProperties": false
},
"baseUrl": {
"type": "string",
"description": "BrAPI v2 base URL for this connection."
},
"content": {
"type": "object",
"required": [
"crops"
],
"properties": {
"crops": {
"type": "array",
"items": {
"type": "string",
"description": "Common crop name as returned by /commoncropnames."
},
"description": "Crops the server declares via /commoncropnames."
},
"studyCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total studies hosted, when the server exposes a cheap count."
},
"programCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total programs hosted, when the server exposes a cheap count."
},
"locationCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total locations hosted, when the server exposes a cheap count."
},
"germplasmCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total germplasm hosted, when the server exposes a cheap count."
}
},
"description": "Content summary (crops + optional totals).",
"additionalProperties": false
},
"dialect": {
"type": "object",
"required": [
"id",
"source",
"envVar",
"disabledSearchEndpoints",
"notes"
],
"properties": {
"id": {
"type": "string",
"description": "Active dialect id (e.g. \"spec\", \"cassavabase\")."
},
"notes": {
"type": "array",
"items": {
"type": "string",
"description": "Verified compatibility note exposed by the active dialect."
},
"description": "Dialect-level compatibility notes for this server family."
},
"envVar": {
"type": "string",
"description": "Env var that pins the dialect for this alias (e.g. BRAPI_DEFAULT_DIALECT) when detection misfires."
},
"source": {
"enum": [
"env-override",
"url-pattern",
"server-name",
"organization-name",
"fallback"
],
"type": "string",
"description": "Where the dialect id came from: env-var override, URL host match, /serverinfo serverName, organizationName, or the spec passthrough fallback."
},
"inferredMappingCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Filter translations inferred from naming conventions, unverified; when non-zero, some narrowing on this server may not fire."
},
"verifiedMappingCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Filter translations verified against a live server. Absent when the dialect publishes no mapping summary."
},
"disabledSearchEndpoints": {
"type": "array",
"items": {
"type": "string",
"description": "A POST /search/{noun} route the dialect routes around."
},
"description": "POST /search nouns the active dialect treats as known-dead. Tools using these routes will refuse with a recovery hint."
}
},
"description": "Active dialect adapter — translates outbound filters and declares known-dead routes for this server.",
"additionalProperties": false
},
"fetchedAt": {
"type": "string",
"description": "ISO 8601 timestamp of when this envelope was composed."
},
"attribution": {
"type": "object",
"required": [
"homepage",
"license",
"citation"
],
"properties": {
"isDemo": {
"type": "boolean",
"description": "True when this server hosts demo / sample data, not production records."
},
"license": {
"type": "string",
"description": "License under which the upstream dataset is published (e.g. \"CC-BY\")."
},
"citation": {
"type": "string",
"description": "Citation requested by the upstream when data is reused in publications."
},
"homepage": {
"type": "string",
"description": "Public homepage of the upstream dataset."
}
},
"description": "Attribution metadata for built-in known-server connections. Absent when the alias is not built-in or points away from its built-in base URL.",
"additionalProperties": false
},
"capabilities": {
"type": "object",
"required": [
"supportedCount",
"supported",
"notableGaps"
],
"properties": {
"supported": {
"type": "array",
"items": {
"type": "string",
"description": "BrAPI service name (e.g. \"studies\", \"search/germplasm\")."
},
"description": "Sorted list of supported service names."
},
"notableGaps": {
"type": "array",
"items": {
"type": "string",
"description": "Common-floor service the server does not expose."
},
"description": "Common-floor services this server does NOT expose."
},
"supportedCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total distinct services the server advertises in /serverinfo or /calls."
}
},
"description": "Capability profile derived from /serverinfo or /calls.",
"additionalProperties": false
},
"nextToolSuggestions": {
"type": "array",
"items": {
"type": "object",
"required": [
"toolName",
"reason",
"args"
],
"properties": {
"args": {
"type": "object",
"required": [
"alias"
],
"properties": {
"alias": {
"type": "string",
"description": "Connection alias to pass to the suggested tool."
}
},
"description": "Arguments to start the tool with (alias only).",
"additionalProperties": false
},
"reason": {
"type": "string",
"description": "Why this tool applies to the connected server."
},
"toolName": {
"enum": [
"brapi_find_studies",
"brapi_find_germplasm",
"brapi_find_variables",
"brapi_find_locations"
],
"type": "string",
"description": "Entry-point finder tool this server can serve."
}
},
"description": "A finder the connected server supports, with the arguments to start it.",
"additionalProperties": false
},
"description": "Entry-point finders (studies, germplasm, variables, locations — in that order) whose GET or POST /search route this server exposes under the active dialect. Empty when none apply."
}
},
"additionalProperties": false
}brapi_connect annotations
{
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": true
}brapi_build_phenotype_matrix — Brapi Build Phenotype Matrix
Advertised read-onlyOpen-world
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.
brapi_build_phenotype_matrix input schema
{
"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
}brapi_build_phenotype_matrix output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"studies",
"coverage",
"shape",
"aggregate",
"observationCount",
"germplasmCount",
"variableCount",
"variableLegend",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Per-study cap on matching observations that was applied.",
"exclusiveMinimum": 0
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"dialect_all_filters_dropped",
"no_observation_path"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `dialect_all_filters_dropped`: For every requested study, the active dialect dropped the study filter on /observationunits, so the pull would have widened to unfiltered rows. `no_observation_path`: Neither /observations nor /observationunits returned data for any requested study after probing both paths. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shape": {
"enum": [
"wide",
"long"
],
"type": "string",
"description": "Matrix shape — wide (one row per germplasm, one column per variable) or long (one row per observation)."
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Observations collected across all studies after filtering."
},
"notice": {
"type": "string",
"description": "Guidance for reaching the observations this call left out, then the matrix dataframe and the tools that read it."
},
"studies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Requested studyDbIds; coverage records collection outcomes."
},
"coverage": {
"type": "object",
"required": [
"partial",
"studies"
],
"properties": {
"scan": {
"type": "object",
"required": [
"complete",
"scannedUnits",
"pagesFetched"
],
"properties": {
"reason": {
"type": "string",
"description": "Bound or failure that stopped the unit walk."
},
"complete": {
"type": "boolean",
"description": "Whether the scoped unit walk exhausted its authoritative total."
},
"totalUnits": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream raw unit total, when reported."
},
"pagesFetched": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Unit pages returned before stopping."
},
"scannedUnits": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Raw upstream units examined, including repeated IDs."
}
},
"description": "Scoped-unit scan coverage; unseen studies are unknown after an incomplete walk.",
"additionalProperties": false
},
"partial": {
"type": "boolean",
"description": "True when failed, truncated, or unprocessed work leaves coverage incomplete."
},
"studies": {
"type": "array",
"items": {
"type": "object",
"required": [
"studyDbId",
"status",
"observationCount"
],
"properties": {
"reason": {
"type": "string",
"description": "Why collection failed or remained incomplete."
},
"status": {
"enum": [
"contributed",
"empty",
"failed",
"partial",
"unprocessed"
],
"type": "string",
"description": "Outcome of collecting this study; partial may contain observations."
},
"studyDbId": {
"type": "string",
"description": "Requested study, or a study encountered in scoped units."
},
"observationCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Matching observations collected for this study."
}
},
"description": "One study collection outcome.",
"additionalProperties": false
},
"description": "Per-study outcomes in requested or encounter order."
},
"discoveryLimited": {
"type": "boolean",
"description": "True when generic study discovery reached its bound; additional studies may exist."
}
},
"description": "Collection coverage, independent of the number of contributing studies.",
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (empty or failed studies, partial study scans, extraFilters the rows contradict or cannot verify, non-numeric aggregation skips, fallback paths)."
},
"aggregate": {
"enum": [
"mean",
"median",
"first",
"all"
],
"type": "string",
"description": "Aggregation applied to replicate observations (wide shape only). `all` keeps one row per replicate."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "The matrix, staged; absent when no observations were found. Long-form columns: germplasmDbId, observationVariableDbId, studyDbId, value, replicateIndex. Wide-form columns: germplasmDbId, germplasmName, then one per variable (see variableLegend).",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when failed, truncated, or unprocessed studies leave matrix coverage incomplete."
},
"variableCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of distinct observation variables in the matrix."
},
"germplasmCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of distinct germplasm in the matrix."
},
"variableLegend": {
"type": "object",
"description": "Wide-matrix column name (SQL-safe, derived from observationVariableDbId) → observationVariableName.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"observationCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total raw observations collected before pivoting."
}
},
"additionalProperties": false
}brapi_build_phenotype_matrix annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_server_info — Brapi Server Info
Advertised read-only
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.
brapi_server_info input schema
{
"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
}brapi_server_info output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"baseUrl",
"server",
"auth",
"capabilities",
"dialect",
"content",
"nextToolSuggestions",
"notes",
"fetchedAt"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"auth": {
"type": "object",
"required": [
"mode"
],
"properties": {
"mode": {
"enum": [
"none",
"sgn",
"oauth2",
"api_key",
"bearer"
],
"type": "string",
"description": "Auth mode of the active connection."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 token-expiry timestamp, when known."
},
"headerName": {
"type": "string",
"description": "HTTP header carrying credentials."
}
},
"description": "Auth summary for the active connection.",
"additionalProperties": false
},
"alias": {
"type": "string",
"description": "Connection alias."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked"
],
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"notes": {
"type": "array",
"items": {
"type": "string",
"description": "Server-specific quirk or degradation note."
},
"description": "Server-specific quirks or degradation notes."
},
"server": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Server display name from /serverinfo."
},
"description": {
"type": "string",
"description": "Free-form server description."
},
"brapiVersion": {
"type": "string",
"description": "Highest BrAPI version the server reports."
},
"contactEmail": {
"type": "string",
"description": "Contact email for the operator."
},
"organizationURL": {
"type": "string",
"description": "Organization website."
},
"documentationURL": {
"type": "string",
"description": "Documentation URL for this server."
},
"organizationName": {
"type": "string",
"description": "Hosting organization."
}
},
"description": "Normalized server identity block.",
"additionalProperties": false
},
"baseUrl": {
"type": "string",
"description": "BrAPI v2 base URL for this connection."
},
"content": {
"type": "object",
"required": [
"crops"
],
"properties": {
"crops": {
"type": "array",
"items": {
"type": "string",
"description": "Common crop name as returned by /commoncropnames."
},
"description": "Crops the server declares via /commoncropnames."
},
"studyCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total studies hosted, when the server exposes a cheap count."
},
"programCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total programs hosted, when the server exposes a cheap count."
},
"locationCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total locations hosted, when the server exposes a cheap count."
},
"germplasmCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total germplasm hosted, when the server exposes a cheap count."
}
},
"description": "Content summary (crops + optional totals).",
"additionalProperties": false
},
"dialect": {
"type": "object",
"required": [
"id",
"source",
"envVar",
"disabledSearchEndpoints",
"notes"
],
"properties": {
"id": {
"type": "string",
"description": "Active dialect id (e.g. \"spec\", \"cassavabase\")."
},
"notes": {
"type": "array",
"items": {
"type": "string",
"description": "Verified compatibility note exposed by the active dialect."
},
"description": "Dialect-level compatibility notes for this server family."
},
"envVar": {
"type": "string",
"description": "Env var that pins the dialect for this alias (e.g. BRAPI_DEFAULT_DIALECT) when detection misfires."
},
"source": {
"enum": [
"env-override",
"url-pattern",
"server-name",
"organization-name",
"fallback"
],
"type": "string",
"description": "Where the dialect id came from: env-var override, URL host match, /serverinfo serverName, organizationName, or the spec passthrough fallback."
},
"inferredMappingCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Filter translations inferred from naming conventions, unverified; when non-zero, some narrowing on this server may not fire."
},
"verifiedMappingCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Filter translations verified against a live server. Absent when the dialect publishes no mapping summary."
},
"disabledSearchEndpoints": {
"type": "array",
"items": {
"type": "string",
"description": "A POST /search/{noun} route the dialect routes around."
},
"description": "POST /search nouns the active dialect treats as known-dead. Tools using these routes will refuse with a recovery hint."
}
},
"description": "Active dialect adapter — translates outbound filters and declares known-dead routes for this server.",
"additionalProperties": false
},
"fetchedAt": {
"type": "string",
"description": "ISO 8601 timestamp of when this envelope was composed."
},
"attribution": {
"type": "object",
"required": [
"homepage",
"license",
"citation"
],
"properties": {
"isDemo": {
"type": "boolean",
"description": "True when this server hosts demo / sample data, not production records."
},
"license": {
"type": "string",
"description": "License under which the upstream dataset is published (e.g. \"CC-BY\")."
},
"citation": {
"type": "string",
"description": "Citation requested by the upstream when data is reused in publications."
},
"homepage": {
"type": "string",
"description": "Public homepage of the upstream dataset."
}
},
"description": "Attribution metadata for built-in known-server connections. Absent when the alias is not built-in or points away from its built-in base URL.",
"additionalProperties": false
},
"capabilities": {
"type": "object",
"required": [
"supportedCount",
"supported",
"notableGaps"
],
"properties": {
"supported": {
"type": "array",
"items": {
"type": "string",
"description": "BrAPI service name (e.g. \"studies\", \"search/germplasm\")."
},
"description": "Sorted list of supported service names."
},
"notableGaps": {
"type": "array",
"items": {
"type": "string",
"description": "Common-floor service the server does not expose."
},
"description": "Common-floor services this server does NOT expose."
},
"supportedCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total distinct services the server advertises in /serverinfo or /calls."
}
},
"description": "Capability profile derived from /serverinfo or /calls.",
"additionalProperties": false
},
"nextToolSuggestions": {
"type": "array",
"items": {
"type": "object",
"required": [
"toolName",
"reason",
"args"
],
"properties": {
"args": {
"type": "object",
"required": [
"alias"
],
"properties": {
"alias": {
"type": "string",
"description": "Connection alias to pass to the suggested tool."
}
},
"description": "Arguments to start the tool with (alias only).",
"additionalProperties": false
},
"reason": {
"type": "string",
"description": "Why this tool applies to the connected server."
},
"toolName": {
"enum": [
"brapi_find_studies",
"brapi_find_germplasm",
"brapi_find_variables",
"brapi_find_locations"
],
"type": "string",
"description": "Entry-point finder tool this server can serve."
}
},
"description": "A finder the connected server supports, with the arguments to start it.",
"additionalProperties": false
},
"description": "Entry-point finders (studies, germplasm, variables, locations — in that order) whose GET or POST /search route this server exposes under the active dialect. Empty when none apply."
}
},
"additionalProperties": false
}brapi_server_info annotations
{
"readOnlyHint": true,
"idempotentHint": true
}brapi_describe_filters — Brapi Describe Filters
Advertised read-only
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.
brapi_describe_filters input schema
{
"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
}brapi_describe_filters output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"endpoint",
"filterCount",
"filters",
"availableEndpoints"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"unknown_endpoint"
],
"description": "Machine-readable failure mode. Declared by this tool: `unknown_endpoint`: No filter catalog is registered for the requested endpoint. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"filters": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type",
"description",
"example"
],
"properties": {
"name": {
"type": "string",
"description": "Filter parameter name (as accepted by the BrAPI endpoint)."
},
"type": {
"enum": [
"string",
"integer",
"number",
"boolean",
"date",
"string[]",
"integer[]"
],
"type": "string",
"description": "Expected value type."
},
"example": {
"type": "string",
"description": "Example value (stringified)."
},
"description": {
"type": "string",
"description": "Short description of what the filter does."
}
},
"description": "One filter entry — name, type, description, and an example value.",
"additionalProperties": false
},
"description": "Filter catalog entries."
},
"endpoint": {
"type": "string",
"description": "The endpoint the filters apply to."
},
"filterCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of filters in the catalog."
},
"specReference": {
"type": "string",
"description": "Pointer to the BrAPI v2 spec section for this endpoint."
},
"availableEndpoints": {
"type": "array",
"items": {
"type": "string"
},
"description": "Every endpoint this tool can describe — useful for discovery."
}
},
"additionalProperties": false
}brapi_describe_filters annotations
{
"readOnlyHint": true,
"idempotentHint": true
}brapi_find_studies — Brapi Find Studies
Advertised read-onlyOpen-world
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).
brapi_find_studies input schema
{
"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
}brapi_find_studies output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "The effective loadLimit when truncated; shown is below it when the 24,000-byte inline budget bound first (notice says which).",
"exclusiveMinimum": 0
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"missing_find_route",
"search_endpoint_disabled",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"all_filters_dropped"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `missing_find_route`: Neither the GET list nor a usable POST search route is advertised. `search_endpoint_disabled`: Only a POST search route marked unusable by the active dialect is advertised. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Length of results[] when truncated.",
"exclusiveMinimum": 0
},
"notice": {
"type": "string",
"description": "Why results[] is empty, or which bound cut it short and the dataframe holding the matched rows."
},
"hasMore": {
"type": "boolean",
"description": "True when more rows exist beyond the returned set."
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"studyDbId"
],
"properties": {
"active": {
"type": [
"boolean",
"null"
],
"description": "True while the study is open for data capture."
},
"endDate": {
"type": [
"string",
"null"
],
"description": "ISO 8601 end date."
},
"seasons": {
"anyOf": [
{
"type": "array",
"items": {
"type": [
"string",
"null"
],
"description": "Season identifier — typically a year like \"2022\". Nullable: some Breedbase deployments emit a null entry when the study is missing a season."
}
},
{
"type": "null"
}
],
"description": "Season identifiers this study spans."
},
"studyPUI": {
"type": [
"string",
"null"
],
"description": "Persistent unique identifier (URI)."
},
"startDate": {
"type": [
"string",
"null"
],
"description": "ISO 8601 start date."
},
"studyCode": {
"type": [
"string",
"null"
],
"description": "Short code or alias for the study."
},
"studyDbId": {
"type": "string",
"description": "Server-side identifier for the study."
},
"studyName": {
"type": [
"string",
"null"
],
"description": "Display name."
},
"studyType": {
"type": [
"string",
"null"
],
"description": "E.g. \"Yield Trial\", \"Phenotyping\"."
},
"trialDbId": {
"type": [
"string",
"null"
],
"description": "FK to trial; resolve via `brapi_get_study`."
},
"trialName": {
"type": [
"string",
"null"
],
"description": "Display name of the owning trial."
},
"programDbId": {
"type": [
"string",
"null"
],
"description": "FK to program; resolve via `brapi_get_study`."
},
"programName": {
"type": [
"string",
"null"
],
"description": "Display name of the owning program."
},
"locationDbId": {
"type": [
"string",
"null"
],
"description": "FK to location; resolve via `brapi_get_study`."
},
"locationName": {
"type": [
"string",
"null"
],
"description": "Display name of the study site."
},
"commonCropName": {
"type": [
"string",
"null"
],
"description": "Common crop name (e.g. \"Maize\", \"Wheat\")."
},
"studyDescription": {
"type": [
"string",
"null"
],
"description": "Free-form description."
}
},
"description": "One BrAPI study record.",
"additionalProperties": {}
},
"description": "Leading matched rows, up to loadLimit and a 24,000-byte budget, whichever binds first."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (filter overrides, partial data)."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "The matched rows, staged as a dataframe when results[] holds fewer.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when results[] holds fewer rows than matched because loadLimit or the inline byte budget bound."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total rows reported by the server, else the rows scanned; with `locations` applied client-side, the matched rows fetched."
},
"distributions": {
"type": "object",
"required": [
"programName",
"studyType",
"seasons",
"locationName",
"commonCropName"
],
"properties": {
"seasons": {
"type": "object",
"description": "Season identifier → count of rows in that season.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"studyType": {
"type": "object",
"description": "Study type → count of rows with that type.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"programName": {
"type": "object",
"description": "Program name → count of rows with that program.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"locationName": {
"type": "object",
"description": "Location name → count of rows at that site.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"commonCropName": {
"type": "object",
"description": "Common crop name → count of rows for that crop.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"description": "Value frequency per field across every matched row fetched.",
"additionalProperties": false
},
"returnedCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Length of results[]."
},
"appliedFilters": {
"type": "object",
"description": "Filter map sent upstream (named filters plus extraFilters).",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"refinementHint": {
"type": "string",
"description": "Suggested refinement when the result set is large."
},
"clientSideFilters": {
"type": "object",
"description": "Filters this server ignores on /studies, applied to the scanned rows instead of sent upstream, keyed by input name.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"additionalProperties": false
}brapi_find_studies annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_get_study — Brapi Get Study
Advertised read-only
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.
brapi_get_study input schema
{
"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
}brapi_get_study output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"study",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_rate_limited",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"study_not_found"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `study_not_found`: Upstream returned no study record for the requested DbId. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"study": {
"type": "object",
"required": [
"studyDbId"
],
"properties": {
"active": {
"type": [
"boolean",
"null"
],
"description": "True while the study is open for data capture."
},
"endDate": {
"type": [
"string",
"null"
],
"description": "ISO 8601 end date."
},
"seasons": {
"anyOf": [
{
"type": "array",
"items": {
"type": [
"string",
"null"
],
"description": "Season identifier — typically a year like \"2022\". Nullable: some Breedbase deployments emit a null entry when the study is missing a season."
}
},
{
"type": "null"
}
],
"description": "Season identifiers this study spans."
},
"studyPUI": {
"type": [
"string",
"null"
],
"description": "Persistent unique identifier (URI)."
},
"startDate": {
"type": [
"string",
"null"
],
"description": "ISO 8601 start date."
},
"studyCode": {
"type": [
"string",
"null"
],
"description": "Short code or alias for the study."
},
"studyDbId": {
"type": "string",
"description": "Server-side identifier for the study."
},
"studyName": {
"type": [
"string",
"null"
],
"description": "Display name."
},
"studyType": {
"type": [
"string",
"null"
],
"description": "E.g. \"Yield Trial\", \"Phenotyping\"."
},
"trialDbId": {
"type": [
"string",
"null"
],
"description": "FK to the owning trial."
},
"trialName": {
"type": [
"string",
"null"
],
"description": "Display name of the owning trial."
},
"programDbId": {
"type": [
"string",
"null"
],
"description": "FK to the owning program."
},
"programName": {
"type": [
"string",
"null"
],
"description": "Display name of the owning program."
},
"locationDbId": {
"type": [
"string",
"null"
],
"description": "FK to the study site."
},
"locationName": {
"type": [
"string",
"null"
],
"description": "Display name of the study site."
},
"commonCropName": {
"type": [
"string",
"null"
],
"description": "Common crop name (e.g. \"Maize\", \"Wheat\")."
},
"studyDescription": {
"type": [
"string",
"null"
],
"description": "Free-form description."
}
},
"description": "Canonical study record as returned by `/studies/{id}`.",
"additionalProperties": {}
},
"trial": {
"type": "object",
"required": [
"trialDbId"
],
"properties": {
"active": {
"type": [
"boolean",
"null"
],
"description": "True while the trial is ongoing."
},
"endDate": {
"type": [
"string",
"null"
],
"description": "ISO 8601 end date."
},
"startDate": {
"type": [
"string",
"null"
],
"description": "ISO 8601 start date."
},
"trialDbId": {
"type": "string",
"description": "Server-side identifier for the trial."
},
"trialName": {
"type": [
"string",
"null"
],
"description": "Display name."
},
"programDbId": {
"type": [
"string",
"null"
],
"description": "FK to the owning program."
},
"programName": {
"type": [
"string",
"null"
],
"description": "Display name of the owning program."
},
"commonCropName": {
"type": [
"string",
"null"
],
"description": "Common crop name."
},
"trialDescription": {
"type": [
"string",
"null"
],
"description": "Free-form description."
}
},
"description": "Resolved trial record (when the study has a trialDbId and the FK lookup succeeded).",
"additionalProperties": {}
},
"program": {
"type": "object",
"required": [
"programDbId"
],
"properties": {
"programDbId": {
"type": "string",
"description": "Server-side identifier for the program."
},
"programName": {
"type": [
"string",
"null"
],
"description": "Display name."
},
"abbreviation": {
"type": [
"string",
"null"
],
"description": "Short abbreviation."
},
"commonCropName": {
"type": [
"string",
"null"
],
"description": "Common crop name this program targets."
},
"leadPersonName": {
"type": [
"string",
"null"
],
"description": "Name of the program lead."
},
"documentationURL": {
"type": [
"string",
"null"
],
"description": "URL pointing at program documentation."
}
},
"description": "Resolved program record (when the study or parent trial identifies a program and the FK lookup succeeded).",
"additionalProperties": {}
},
"location": {
"type": "object",
"required": [
"locationDbId"
],
"properties": {
"altitude": {
"type": [
"number",
"null"
],
"description": "Altitude in meters above sea level."
},
"latitude": {
"type": [
"number",
"null"
],
"description": "WGS84 latitude in decimal degrees (legacy field; modern servers use coordinates)."
},
"longitude": {
"type": [
"number",
"null"
],
"description": "WGS84 longitude in decimal degrees (legacy field; modern servers use coordinates)."
},
"coordinates": {
"anyOf": [
{
"type": "object",
"properties": {},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "BrAPI v2 GeoJSON Feature carrying [lon, lat, alt?] in geometry.coordinates."
},
"countryCode": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-3 country code."
},
"countryName": {
"type": [
"string",
"null"
],
"description": "Display name of the country."
},
"abbreviation": {
"type": [
"string",
"null"
],
"description": "Short abbreviation."
},
"locationDbId": {
"type": "string",
"description": "Server-side identifier for the location."
},
"locationName": {
"type": [
"string",
"null"
],
"description": "Display name."
},
"locationType": {
"type": [
"string",
"null"
],
"description": "Type of location (e.g. \"Research Station\", \"Field\")."
}
},
"description": "Resolved location record (when the study has a locationDbId and the FK lookup succeeded).",
"additionalProperties": {}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages — failed FK lookups, missing counts."
},
"variableCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total observation variables (traits) measured in this study. Omitted (with a warning) when the upstream server cannot scope the count to the study — never reported as the server-wide total."
},
"observationCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total observations recorded against this study. Omitted (with a warning) when the upstream server cannot scope the count to the study — never reported as the server-wide total."
},
"observationUnitCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total observation units (plots, plants, samples) in this study."
}
},
"additionalProperties": false
}brapi_get_study annotations
{
"readOnlyHint": true,
"idempotentHint": true
}brapi_find_germplasm — Brapi Find Germplasm
Advertised read-onlyOpen-world
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.
brapi_find_germplasm input schema
{
"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
}brapi_find_germplasm output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "The effective loadLimit when truncated; shown is below it when the 24,000-byte inline budget bound first (notice says which).",
"exclusiveMinimum": 0
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"missing_find_route",
"search_endpoint_disabled",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"all_filters_dropped"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `missing_find_route`: Neither the GET list nor a usable POST search route is advertised. `search_endpoint_disabled`: Only a POST search route marked unusable by the active dialect is advertised. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Length of results[] when truncated.",
"exclusiveMinimum": 0
},
"notice": {
"type": "string",
"description": "Why results[] is empty, or which bound cut it short and the dataframe holding the matched rows."
},
"hasMore": {
"type": "boolean",
"description": "True when more rows exist beyond the returned set."
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"germplasmDbId"
],
"properties": {
"genus": {
"type": [
"string",
"null"
],
"description": "Botanical genus."
},
"species": {
"type": [
"string",
"null"
],
"description": "Botanical species."
},
"subtaxa": {
"type": [
"string",
"null"
],
"description": "Botanical subtaxa (subspecies, variety, etc.)."
},
"pedigree": {
"type": [
"string",
"null"
],
"description": "Pedigree as a free-text string (e.g. \"A/B//C\")."
},
"synonyms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "Synonym type (e.g. \"COMMON\", \"SYNONYM\")."
},
"synonym": {
"type": [
"string",
"null"
],
"description": "Synonym value."
}
},
"description": "Registered synonym for this germplasm.",
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "All registered synonyms (alternative names)."
},
"collection": {
"type": [
"string",
"null"
],
"description": "Collection name this accession belongs to."
},
"germplasmPUI": {
"type": [
"string",
"null"
],
"description": "Persistent unique identifier (URI)."
},
"germplasmDbId": {
"type": "string",
"description": "Server-side identifier for the germplasm."
},
"germplasmName": {
"type": [
"string",
"null"
],
"description": "Display name."
},
"instituteCode": {
"type": [
"string",
"null"
],
"description": "FAO WIEWS institute code of the holding institute."
},
"instituteName": {
"type": [
"string",
"null"
],
"description": "Display name of the holding institute."
},
"commonCropName": {
"type": [
"string",
"null"
],
"description": "Common crop name (e.g. \"Maize\", \"Wheat\")."
},
"accessionNumber": {
"type": [
"string",
"null"
],
"description": "Gene-bank catalog number."
},
"germplasmOrigin": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {},
"description": "One origin record (collection coordinates and uncertainty per BrAPI v2).",
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Origin records — array of collection-site objects per BrAPI v2."
},
"defaultDisplayName": {
"type": [
"string",
"null"
],
"description": "Preferred display label."
},
"countryOfOriginCode": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-3 country code."
},
"biologicalStatusOfAccessionDescription": {
"type": [
"string",
"null"
],
"description": "MCPD biological-status label (wild / landrace / breeding / cultivar, etc.)."
}
},
"description": "One BrAPI germplasm record.",
"additionalProperties": {}
},
"description": "Leading matched germplasm rows, up to loadLimit and a 24,000-byte budget, whichever binds first."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (filter overrides, partial data, capability gaps)."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "The matched rows, staged as a dataframe when results[] holds fewer.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when results[] holds fewer rows than matched because loadLimit or the inline byte budget bound."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total rows reported by the server, else the rows scanned."
},
"distributions": {
"type": "object",
"required": [
"commonCropName",
"genus",
"species",
"collection",
"countryOfOriginCode"
],
"properties": {
"genus": {
"type": "object",
"description": "Genus → count of rows with that genus.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"species": {
"type": "object",
"description": "Species → count of rows with that species.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"collection": {
"type": "object",
"description": "Collection name → count of rows in that collection.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"commonCropName": {
"type": "object",
"description": "Common crop name → count of rows for that crop.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"countryOfOriginCode": {
"type": "object",
"description": "ISO country code → count of rows from that country.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"description": "Value frequency per field across every matched row fetched.",
"additionalProperties": false
},
"returnedCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Length of results[]."
},
"appliedFilters": {
"type": "object",
"description": "Filter map sent upstream (named filters plus extraFilters).",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"refinementHint": {
"type": "string",
"description": "Suggested refinement when the result set is large."
}
},
"additionalProperties": false
}brapi_find_germplasm annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_get_germplasm — Brapi Get Germplasm
Advertised read-only
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.
brapi_get_germplasm input schema
{
"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
}brapi_get_germplasm output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"germplasm",
"parents",
"attributes",
"directParentCount",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_rate_limited",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"germplasm_not_found"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `germplasm_not_found`: Upstream returned no germplasm record for the requested DbId. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"parents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"parentType": {
"type": [
"string",
"null"
],
"description": "E.g. \"MALE\", \"FEMALE\", \"SELF\"."
},
"germplasmDbId": {
"type": [
"string",
"null"
],
"description": "FK to the parent germplasm."
},
"germplasmName": {
"type": [
"string",
"null"
],
"description": "Display name of the parent germplasm."
}
},
"description": "One direct parent of the germplasm.",
"additionalProperties": {}
},
"description": "Direct parents from /germplasm/{id}/pedigree."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages — failed sub-endpoint lookups, missing counts."
},
"germplasm": {
"type": "object",
"required": [
"germplasmDbId"
],
"properties": {
"genus": {
"type": [
"string",
"null"
],
"description": "Botanical genus."
},
"species": {
"type": [
"string",
"null"
],
"description": "Botanical species."
},
"subtaxa": {
"type": [
"string",
"null"
],
"description": "Botanical subtaxa."
},
"pedigree": {
"type": [
"string",
"null"
],
"description": "Pedigree as a free-text string."
},
"synonyms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "Synonym type (e.g. \"COMMON\", \"SYNONYM\")."
},
"synonym": {
"type": [
"string",
"null"
],
"description": "Synonym value."
}
},
"description": "Registered synonym for this germplasm.",
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "All registered synonyms."
},
"collection": {
"type": [
"string",
"null"
],
"description": "Collection name."
},
"germplasmPUI": {
"type": [
"string",
"null"
],
"description": "Persistent unique identifier (URI)."
},
"germplasmDbId": {
"type": "string",
"description": "Server-side identifier for the germplasm."
},
"germplasmName": {
"type": [
"string",
"null"
],
"description": "Display name."
},
"instituteCode": {
"type": [
"string",
"null"
],
"description": "FAO WIEWS institute code."
},
"instituteName": {
"type": [
"string",
"null"
],
"description": "Display name of the holding institute."
},
"commonCropName": {
"type": [
"string",
"null"
],
"description": "Common crop name."
},
"accessionNumber": {
"type": [
"string",
"null"
],
"description": "Gene-bank catalog number."
},
"germplasmOrigin": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {},
"description": "One origin record (collection coordinates and uncertainty per BrAPI v2).",
"additionalProperties": {}
}
},
{
"type": "null"
}
],
"description": "Origin records — array of collection-site objects per BrAPI v2."
},
"defaultDisplayName": {
"type": [
"string",
"null"
],
"description": "Preferred display label."
},
"countryOfOriginCode": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-3 country code."
},
"biologicalStatusOfAccessionDescription": {
"type": [
"string",
"null"
],
"description": "MCPD biological-status label."
}
},
"description": "Canonical germplasm record as returned by `/germplasm/{id}`.",
"additionalProperties": {}
},
"attributes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"attributeDbId": {
"type": [
"string",
"null"
],
"description": "Attribute identifier."
},
"attributeName": {
"type": [
"string",
"null"
],
"description": "Attribute display name."
},
"attributeValue": {
"type": [
"string",
"null"
],
"description": "Recorded value (stringified)."
},
"determinedDate": {
"type": [
"string",
"null"
],
"description": "ISO 8601 date the attribute was determined."
}
},
"description": "One germplasm attribute record.",
"additionalProperties": {}
},
"description": "Germplasm attributes from /germplasm/{id}/attributes."
},
"studyCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "How many studies this germplasm has appeared in."
},
"directParentCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Length of parents[]; 0 also when the pedigree lookup is unsupported or failed."
},
"directDescendantCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Count of direct descendants from /germplasm/{id}/progeny."
}
},
"additionalProperties": false
}brapi_get_germplasm annotations
{
"readOnlyHint": true,
"idempotentHint": true
}brapi_walk_pedigree — Brapi Walk Pedigree
Advertised read-onlyOpen-world
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.
brapi_walk_pedigree input schema
{
"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
}brapi_walk_pedigree output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"direction",
"maxDepth",
"nodes",
"edges",
"depthReached",
"rootCount",
"leafCount",
"confirmedLeafCount",
"frontierCount",
"frontier",
"knownOmittedRelativeCount",
"cycleCount",
"deadEndCount",
"truncated",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"edges": {
"type": "array",
"items": {
"type": "object",
"required": [
"from",
"to",
"relationship"
],
"properties": {
"to": {
"type": "string",
"description": "germplasmDbId of the target."
},
"from": {
"type": "string",
"description": "germplasmDbId of the source of the relationship."
},
"isCycle": {
"type": "boolean",
"description": "True when this edge closes a loop (the parent is already a descendant of the child); the walk does not continue past it. Absent on other edges."
},
"parentType": {
"type": "string",
"description": "The parent's role in the cross (e.g. MALE, FEMALE, SELF), when the upstream response supplies it."
},
"relationship": {
"enum": [
"parent",
"child"
],
"type": "string",
"description": "Which lookup found the pair. parent = from is a parent of to (found via /pedigree); child = from is a child of to (found via /progeny). A pair found both ways is listed once, as parent."
}
},
"description": "One parent–child pair, recorded once whichever side found it.",
"additionalProperties": false
},
"description": "One edge per discovered pair. Preview independently fits loadLimit and 24,000 bytes for array JSON and serialized row text; edgesDataframe retains omitted rows."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked"
],
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"nodes": {
"type": "array",
"items": {
"type": "object",
"required": [
"germplasmDbId",
"depth",
"isRoot",
"direction"
],
"properties": {
"depth": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Min distance from any root germplasm (0 for roots)."
},
"isRoot": {
"type": "boolean",
"description": "True when this node is one of the starting germplasm."
},
"direction": {
"enum": [
"root",
"ancestor",
"descendant",
"both"
],
"type": "string",
"description": "`root` = a starting germplasm; `ancestor` = reached upward via /pedigree; `descendant` = reached downward via /progeny; `both` = reached from both sides (a descendant of one root and an ancestor of another, or a node on a pedigree loop)."
},
"germplasmDbId": {
"type": "string",
"description": "Server-side identifier for the germplasm."
},
"germplasmName": {
"type": "string",
"description": "Display name of the germplasm."
}
},
"description": "One germplasm reached during the walk.",
"additionalProperties": false
},
"description": "Discovered nodes sorted by depth/DbId. Preview fits loadLimit and 24,000 bytes for array JSON and serialized row text; nodesDataframe retains omitted rows."
},
"notice": {
"type": "string",
"description": "Staged graph, frontier or omitted-relative tables and how to read them."
},
"diagram": {
"type": "string",
"description": "Requested Mermaid or DOT for the discovered graph, beyond previews; partial when capped. Omitted with a warning past 50,000 characters, or 500 edges for Mermaid."
},
"frontier": {
"type": "array",
"items": {
"type": "object",
"required": [
"germplasmDbId",
"side",
"outcome"
],
"properties": {
"side": {
"enum": [
"ancestor",
"descendant"
],
"type": "string",
"description": "Direction not fully expanded."
},
"error": {
"type": "string",
"description": "Failure message for a failed expansion."
},
"outcome": {
"enum": [
"depth_limited",
"safety_skipped",
"failed",
"unsupported"
],
"type": "string",
"description": "Why this direction remains unresolved."
},
"germplasmDbId": {
"type": "string",
"description": "Expansion node identifier."
},
"knownOmittedRelativeCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Already-fetched relatives omitted from the discovered graph; absent when not requested or failed."
}
},
"description": "One unresolved expansion direction, distinct from a confirmed empty lookup.",
"additionalProperties": false
},
"description": "Bounded preview of unresolved directions; frontierDataframe retains omitted entries."
},
"maxDepth": {
"type": "integer",
"maximum": 9007199254740991,
"description": "The maximum depth the walk was allowed to reach (echoed from the input).",
"exclusiveMinimum": 0
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (capability gaps, per-node expansion failures, an omitted diagram)."
},
"direction": {
"enum": [
"ancestors",
"descendants",
"both"
],
"type": "string",
"description": "The direction the walk expanded (echoed from the input)."
},
"leafCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Non-root nodes with nothing recorded beyond them: ancestors with no parents, descendants with no progeny (a node on both sides needs neither). Includes nodes the depth limit stopped at."
},
"rootCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of starting germplasm roots."
},
"truncated": {
"type": "boolean",
"description": "True when the walk hit its safety cap (1000 nodes or 10000 edges) before exhausting depth."
},
"cycleCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of edges with isCycle: true. Paths that reconverge on one germplasm (shared ancestors, siblings, a parent shared by two roots) are not cycles."
},
"deadEndCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Nodes whose upstream pedigree/progeny lookup failed."
},
"depthReached": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Deepest BFS level that produced at least one new edge (0 if only roots were walked)."
},
"frontierCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Unresolved node/side expansions across the full walk."
},
"edgesDataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "Discovered edges when either preview is trimmed; truncated marks partial traversal. SQL renames from to from_; see columnLegend.",
"additionalProperties": false
},
"nodesDataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "Discovered nodes when either preview is trimmed; truncated marks partial traversal. No unvisited relatives. JOIN germplasmDbId to the edge table on from_ or to.",
"additionalProperties": false
},
"frontierDataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "Every unresolved node/side expansion, with ordinal ordering.",
"additionalProperties": false
},
"confirmedLeafCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Non-root nodes with successful empty lookups on every reached side; unresolved directions never confirm leaves."
},
"knownOmittedRelativeCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Distinct fetched relative IDs per expansion node/side omitted by safety limits; unrequested counts remain unknown."
},
"omittedRelativesDataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "Fetched omitted relatives with ordinal, germplasmDbId, expansionNodeDbId and side; not an unvisited graph or resumable walk.",
"additionalProperties": false
}
},
"additionalProperties": false
}brapi_walk_pedigree annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_germplasm_performance — Brapi Germplasm Performance
Advertised read-onlyOpen-world
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.
brapi_germplasm_performance input schema
{
"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
}brapi_germplasm_performance output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"germplasmDbId",
"studyCount",
"studyDbIds",
"coverage",
"perVariable",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"germplasm_not_found"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `germplasm_not_found`: Upstream returned no germplasm record for the requested germplasmDbId. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"coverage": {
"type": "object",
"required": [
"partial",
"studies"
],
"properties": {
"scan": {
"type": "object",
"required": [
"complete",
"scannedUnits",
"pagesFetched"
],
"properties": {
"reason": {
"type": "string",
"description": "Bound or failure that stopped the unit walk."
},
"complete": {
"type": "boolean",
"description": "Whether the scoped unit walk exhausted its authoritative total."
},
"totalUnits": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream raw unit total, when reported."
},
"pagesFetched": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Unit pages returned before stopping."
},
"scannedUnits": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Raw upstream units examined, including repeated IDs."
}
},
"description": "Scoped-unit scan coverage; unseen studies are unknown after an incomplete walk.",
"additionalProperties": false
},
"partial": {
"type": "boolean",
"description": "True when failed, truncated, or unprocessed work leaves coverage incomplete."
},
"studies": {
"type": "array",
"items": {
"type": "object",
"required": [
"studyDbId",
"status",
"observationCount"
],
"properties": {
"reason": {
"type": "string",
"description": "Why collection failed or remained incomplete."
},
"status": {
"enum": [
"contributed",
"empty",
"failed",
"partial",
"unprocessed"
],
"type": "string",
"description": "Outcome of collecting this study; partial may contain observations."
},
"studyDbId": {
"type": "string",
"description": "Requested study, or a study encountered in scoped units."
},
"observationCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Matching observations collected for this study."
}
},
"description": "One study collection outcome.",
"additionalProperties": false
},
"description": "Per-study outcomes in requested or encounter order."
},
"discoveryLimited": {
"type": "boolean",
"description": "True when generic study discovery reached its bound; additional studies may exist."
}
},
"description": "Collection coverage, independent of the number of contributing studies.",
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (study-discovery limits, dropped filters, fallback paths, per-study failures, partial study scans)."
},
"studyCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of distinct studies that contributed any observation."
},
"studyDbIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Distinct studyDbIds that contributed observations."
},
"perVariable": {
"type": "array",
"items": {
"type": "object",
"required": [
"observationVariableDbId",
"n",
"studyCount",
"studyDbIds",
"seasons"
],
"properties": {
"n": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of observations of this variable for the germplasm."
},
"sd": {
"type": "number",
"description": "Sample standard deviation (n−1) of numeric values; omitted when n < 2 or non-numeric."
},
"max": {
"type": "string",
"description": "Maximum value — numeric max when numeric, else lexical max."
},
"min": {
"type": "string",
"description": "Minimum value — numeric min when numeric, else lexical min."
},
"mean": {
"type": "number",
"description": "Arithmetic mean of numeric values (omitted for non-numeric traits)."
},
"median": {
"type": "number",
"description": "Median of numeric values (omitted for non-numeric traits)."
},
"seasons": {
"type": "array",
"items": {
"type": "string"
},
"description": "Distinct season labels across the observations (empty when the server carries no season)."
},
"studyCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of distinct studies contributing observations of this variable."
},
"studyDbIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Distinct studyDbIds contributing observations of this variable."
},
"observationVariableDbId": {
"type": "string",
"description": "Observation variable identifier."
},
"observationVariableName": {
"type": "string",
"description": "Display name of the variable."
}
},
"description": "Aggregated statistics for one observation variable across the studies the germplasm appears in.",
"additionalProperties": false
},
"description": "Per-variable aggregates, sorted by observationVariableDbId."
},
"germplasmDbId": {
"type": "string",
"description": "The germplasm that was analyzed."
},
"germplasmName": {
"type": "string",
"description": "Display name of the germplasm, when the server provides one."
}
},
"additionalProperties": false
}brapi_germplasm_performance annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_find_variables — Brapi Find Variables
Advertised read-onlyOpen-world
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).
brapi_find_variables input schema
{
"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
}brapi_find_variables output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"ontologyCandidates",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "The effective loadLimit when truncated; shown is below it when the 24,000-byte inline budget bound first (notice says which).",
"exclusiveMinimum": 0
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"missing_find_route",
"search_endpoint_disabled",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"all_filters_dropped"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `missing_find_route`: Neither the GET list nor a usable POST search route is advertised. `search_endpoint_disabled`: Only a POST search route marked unusable by the active dialect is advertised. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Length of results[] when truncated.",
"exclusiveMinimum": 0
},
"notice": {
"type": "string",
"description": "Why results[] is empty, or which bound cut it short and the dataframe holding the matched rows."
},
"hasMore": {
"type": "boolean",
"description": "True when more rows exist beyond the returned set."
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"observationVariableDbId"
],
"properties": {
"scale": {
"anyOf": [
{
"type": "object",
"properties": {
"dataType": {
"type": [
"string",
"null"
],
"description": "Scale data type (e.g. \"Numerical\", \"Categorical\", \"Date\", \"Text\")."
},
"scaleDbId": {
"type": [
"string",
"null"
],
"description": "FK to the scale."
},
"scaleName": {
"type": [
"string",
"null"
],
"description": "Display name of the scale."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Scale used to record this variable (units / type / range)."
},
"trait": {
"anyOf": [
{
"type": "object",
"properties": {
"synonyms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"description": "Trait synonym value."
}
},
{
"type": "null"
}
],
"description": "Registered trait synonyms."
},
"traitDbId": {
"type": [
"string",
"null"
],
"description": "FK to the trait."
},
"traitName": {
"type": [
"string",
"null"
],
"description": "Display name of the trait."
},
"traitClass": {
"type": [
"string",
"null"
],
"description": "High-level trait grouping (e.g. \"agronomic\", \"morphological\")."
},
"description": {
"type": [
"string",
"null"
],
"description": "Free-text trait description."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "The biological trait this variable measures."
},
"method": {
"anyOf": [
{
"type": "object",
"properties": {
"methodDbId": {
"type": [
"string",
"null"
],
"description": "FK to the method."
},
"methodName": {
"type": [
"string",
"null"
],
"description": "Display name of the method."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Measurement method or protocol used to collect this variable."
},
"studyDbIds": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"description": "Study ID."
}
},
{
"type": "null"
}
],
"description": "Requested studies containing this union row."
},
"ontologyDbId": {
"type": [
"string",
"null"
],
"description": "FK to the owning ontology."
},
"ontologyName": {
"type": [
"string",
"null"
],
"description": "Display name of the owning ontology."
},
"commonCropName": {
"type": [
"string",
"null"
],
"description": "Common crop name this variable is scoped to."
},
"observationVariablePUI": {
"type": [
"string",
"null"
],
"description": "Persistent unique identifier — typically an ontology term URI."
},
"observationVariableDbId": {
"type": "string",
"description": "Server-side identifier for the observation variable."
},
"observationVariableName": {
"type": [
"string",
"null"
],
"description": "Display name."
}
},
"description": "One BrAPI observation variable record.",
"additionalProperties": {}
},
"description": "Leading variables, capped by loadLimit and 24,000 bytes. Text candidates lead; nested objects with no non-empty field are omitted."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (filter overrides, partial data, capability gaps)."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "Matched rows, staged when results[] holds fewer.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when results[] holds fewer rows than matched because loadLimit or the inline byte budget bound."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total rows reported by the server, else the rows scanned."
},
"distributions": {
"type": "object",
"required": [
"ontologyDbId",
"traitClass",
"scaleName"
],
"properties": {
"scaleName": {
"type": "object",
"description": "Scale name → count of variables using that scale.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"traitClass": {
"type": "object",
"description": "Trait class → count of variables in that class.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"ontologyDbId": {
"type": "object",
"description": "Ontology ID → count of variables in that ontology.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"description": "Value frequency per field across every matched row fetched.",
"additionalProperties": false
},
"returnedCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Length of results[]."
},
"studyCoverage": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"status",
"rowsScanned",
"pagesFetched"
],
"properties": {
"id": {
"type": "string",
"description": "Requested study ID."
},
"reason": {
"type": "string",
"description": "Stop/failure reason."
},
"status": {
"enum": [
"complete",
"partial",
"failed",
"unprocessed"
],
"type": "string",
"description": "Scan outcome."
},
"rowsScanned": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows examined."
},
"pagesFetched": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Successful pages."
}
},
"description": "One study.",
"additionalProperties": false
},
"description": "Multi-study coverage; incomplete studies may omit variables."
},
"appliedFilters": {
"type": "object",
"description": "Filter map sent upstream (named filters plus extraFilters).",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"refinementHint": {
"type": "string",
"description": "Suggested refinement when the result set is large."
},
"ontologyCandidates": {
"type": "array",
"items": {
"type": "object",
"required": [
"source"
],
"properties": {
"name": {
"type": "string",
"description": "Display name of the candidate."
},
"source": {
"enum": [
"puiMatch",
"nameMatch",
"synonymMatch",
"traitClassMatch"
],
"type": "string",
"description": "How the candidate was ranked — PUI exact / name / synonym / trait-class."
},
"termId": {
"type": "string",
"description": "Ontology term ID / PUI when available (e.g. \"CO_334:0000013\")."
},
"synonyms": {
"type": "array",
"items": {
"type": "string",
"description": "Registered synonym."
},
"description": "Combined variable + trait synonyms."
},
"description": {
"type": "string",
"description": "Trait description, when available."
},
"ontologyDbId": {
"type": "string",
"description": "Owning ontology ID."
},
"observationVariableDbId": {
"type": "string",
"description": "Server-side variable DbId of the source row, when present."
}
},
"description": "One ranked ontology candidate from a free-text query.",
"additionalProperties": false
},
"description": "Ranked free-text candidates; empty without text."
}
},
"additionalProperties": false
}brapi_find_variables annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_find_observations — Brapi Find Observations
Advertised read-onlyOpen-world
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).
brapi_find_observations input schema
{
"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
}brapi_find_observations output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "The effective loadLimit when truncated; shown is below it when the 24,000-byte inline budget bound first (notice says which).",
"exclusiveMinimum": 0
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"missing_find_route",
"search_endpoint_disabled",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"all_filters_dropped"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `missing_find_route`: Neither the GET list nor a usable POST search route is advertised. `search_endpoint_disabled`: Only a POST search route marked unusable by the active dialect is advertised. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Length of results[] when truncated.",
"exclusiveMinimum": 0
},
"notice": {
"type": "string",
"description": "Why results[] is empty, or which bound cut it short and the dataframe holding the matched rows."
},
"hasMore": {
"type": "boolean",
"description": "True when more rows exist beyond the returned set."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"string",
"null"
],
"description": "Recorded measurement value (stringified per BrAPI spec)."
},
"season": {
"anyOf": [
{
"type": "string",
"description": "Season identifier as a flat string (older BrAPI servers)."
},
{
"type": "object",
"properties": {},
"description": "BrAPI v2.1 season object — seasonDbId, year, season, or seasonName; fields vary by server.",
"additionalProperties": {}
},
{
"type": "null",
"description": "Field present but null on the upstream."
}
],
"description": "Season as a flat string or a structured object, depending on the server."
},
"collector": {
"type": [
"string",
"null"
],
"description": "Name or ID of the person who collected the value."
},
"studyDbId": {
"type": [
"string",
"null"
],
"description": "FK to the study the observation belongs to."
},
"studyName": {
"type": [
"string",
"null"
],
"description": "Display name of the study."
},
"uploadedBy": {
"type": [
"string",
"null"
],
"description": "Name or ID of the user who uploaded the record."
},
"germplasmDbId": {
"type": [
"string",
"null"
],
"description": "FK to the germplasm the observation was taken on."
},
"germplasmName": {
"type": [
"string",
"null"
],
"description": "Display name of the germplasm."
},
"observationDbId": {
"type": [
"string",
"null"
],
"description": "Server-side identifier for the observation."
},
"observationLevel": {
"type": [
"string",
"null"
],
"description": "Unit level — e.g. \"plot\", \"plant\", \"field\"."
},
"observationUnitDbId": {
"type": [
"string",
"null"
],
"description": "FK to the observation unit (plot / plant / sample) that carries the measurement."
},
"observationUnitName": {
"type": [
"string",
"null"
],
"description": "Display name of the observation unit."
},
"observationTimeStamp": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp of the observation."
},
"observationVariableDbId": {
"type": [
"string",
"null"
],
"description": "FK to the observation variable (trait) measured."
},
"observationVariableName": {
"type": [
"string",
"null"
],
"description": "Display name of the observation variable."
}
},
"description": "One BrAPI observation record.",
"additionalProperties": {}
},
"description": "Leading matched observation rows, up to loadLimit and a 24,000-byte budget, whichever binds first."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (filter overrides, partial data, capability gaps)."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "The matched rows, staged as a dataframe when results[] holds fewer.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when results[] holds fewer rows than matched because loadLimit or the inline byte budget bound."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream observation total, or the matched observations collected on the embedded-unit route; warnings disclose incomplete scans."
},
"distributions": {
"type": "object",
"required": [
"observationVariableName",
"studyName",
"germplasmName",
"observationLevel",
"season"
],
"properties": {
"season": {
"type": "object",
"description": "Season identifier → count of observations in that season.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"studyName": {
"type": "object",
"description": "Study name → count of observations in that study.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"germplasmName": {
"type": "object",
"description": "Germplasm name → count of observations on that germplasm.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"observationLevel": {
"type": "object",
"description": "Unit level (plot / plant / field) → count of observations at that level.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"observationVariableName": {
"type": "object",
"description": "Variable name → count of observations for that trait.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"description": "Value frequency per field across every matched row fetched.",
"additionalProperties": false
},
"returnedCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Length of results[]."
},
"appliedFilters": {
"type": "object",
"description": "Upstream filter map, or separate upstreamRequests and clientSide criteria for embedded-unit collection.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"refinementHint": {
"type": "string",
"description": "Suggested refinement when the result set is large."
}
},
"additionalProperties": false
}brapi_find_observations annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_find_images — Brapi Find Images
Advertised read-onlyOpen-world
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).
brapi_find_images input schema
{
"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
}brapi_find_images output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "The effective loadLimit when truncated; shown is below it when the 24,000-byte inline budget bound first (notice says which).",
"exclusiveMinimum": 0
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"missing_find_route",
"search_endpoint_disabled",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"all_filters_dropped"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `missing_find_route`: Neither the GET list nor a usable POST search route is advertised. `search_endpoint_disabled`: Only a POST search route marked unusable by the active dialect is advertised. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Length of results[] when truncated.",
"exclusiveMinimum": 0
},
"notice": {
"type": "string",
"description": "Why results[] is empty, or which bound cut it short and the dataframe holding the matched rows."
},
"hasMore": {
"type": "boolean",
"description": "True when more rows exist beyond the returned set."
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"imageDbId"
],
"properties": {
"imageURL": {
"type": [
"string",
"null"
],
"description": "URL where the bytes live (may be relative to baseUrl or absolute)."
},
"mimeType": {
"type": [
"string",
"null"
],
"description": "MIME type (e.g. \"image/jpeg\")."
},
"copyright": {
"type": [
"string",
"null"
],
"description": "Copyright or rights notice."
},
"imageDbId": {
"type": "string",
"description": "Server-side identifier for the image."
},
"imageName": {
"type": [
"string",
"null"
],
"description": "Display name."
},
"studyDbId": {
"type": [
"string",
"null"
],
"description": "FK to the study the image belongs to."
},
"studyName": {
"type": [
"string",
"null"
],
"description": "Display name of the study."
},
"imageWidth": {
"type": [
"number",
"null"
],
"description": "Pixel width. Coerced from string when the upstream emits a numeric string."
},
"description": {
"type": [
"string",
"null"
],
"description": "Free-text description."
},
"imageHeight": {
"type": [
"number",
"null"
],
"description": "Pixel height. Coerced from string when the upstream emits a numeric string."
},
"imageFileName": {
"type": [
"string",
"null"
],
"description": "Original uploaded filename."
},
"imageFileSize": {
"type": [
"number",
"null"
],
"description": "File size in bytes. Coerced from string when the upstream emits a numeric string."
},
"imageTimeStamp": {
"type": [
"string",
"null"
],
"description": "ISO 8601 capture timestamp."
},
"observationDbIds": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"description": "Observation identifier."
}
},
{
"type": "null"
}
],
"description": "FKs to observations this image is evidence for."
},
"observationUnitDbId": {
"type": [
"string",
"null"
],
"description": "FK to the observation unit this image depicts."
},
"observationUnitName": {
"type": [
"string",
"null"
],
"description": "Display name of the observation unit."
},
"descriptiveOntologyTerms": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"description": "Ontology term ID or label."
}
},
{
"type": "null"
}
],
"description": "Descriptive ontology tags (e.g. \"CO_334:plot\")."
}
},
"description": "One BrAPI image metadata record.",
"additionalProperties": {}
},
"description": "Leading matched image metadata rows, up to loadLimit and a 24,000-byte budget, whichever binds first."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (filter overrides, partial data, capability gaps)."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "The matched rows, staged as a dataframe when results[] holds fewer.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when results[] holds fewer rows than matched because loadLimit or the inline byte budget bound."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total rows reported by the server, else the rows scanned."
},
"distributions": {
"type": "object",
"required": [
"mimeType",
"studyName",
"observationUnitName",
"descriptiveOntologyTerms"
],
"properties": {
"mimeType": {
"type": "object",
"description": "MIME type → count of images with that type.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"studyName": {
"type": "object",
"description": "Study name → count of images in that study.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"observationUnitName": {
"type": "object",
"description": "Observation unit name → count of images tied to that unit.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"descriptiveOntologyTerms": {
"type": "object",
"description": "Ontology term → count of images tagged with that term.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"description": "Value frequency per field across every matched row fetched.",
"additionalProperties": false
},
"returnedCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Length of results[]."
},
"appliedFilters": {
"type": "object",
"description": "Filter map sent upstream (named filters plus extraFilters).",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"refinementHint": {
"type": "string",
"description": "Suggested refinement when the result set is large."
}
},
"additionalProperties": false
}brapi_find_images annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_get_image — Brapi Get Image
Advertised read-onlyOpen-world
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.
brapi_get_image input schema
{
"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
}brapi_get_image output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"images",
"errors",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"images_unsupported"
],
"description": "Machine-readable failure mode. Declared by this tool: `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `images_unsupported`: The BrAPI server does not advertise /images. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"errors": {
"type": "array",
"items": {
"type": "object",
"required": [
"imageDbId",
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Reason the image could not be loaded."
},
"imageDbId": {
"type": "string",
"description": "Image identifier the error applies to."
}
},
"description": "Per-image error entry returned when a fetch fails.",
"additionalProperties": false
},
"description": "Images that could not be loaded, one entry per id."
},
"images": {
"type": "array",
"items": {
"type": "object",
"required": [
"imageDbId",
"mimeType",
"sizeBytes",
"source",
"metadata"
],
"properties": {
"source": {
"enum": [
"imagecontent",
"imageURL"
],
"type": "string",
"description": "How the bytes were fetched."
},
"metadata": {
"type": "object",
"required": [
"imageDbId"
],
"properties": {
"imageURL": {
"type": "string",
"description": "URL where the bytes live."
},
"mimeType": {
"type": "string",
"description": "MIME type (e.g. \"image/jpeg\")."
},
"copyright": {
"type": "string",
"description": "Copyright or rights notice."
},
"imageDbId": {
"type": "string",
"description": "Server-side identifier for the image."
},
"imageName": {
"type": "string",
"description": "Display name."
},
"studyDbId": {
"type": "string",
"description": "FK to the study the image belongs to."
},
"studyName": {
"type": "string",
"description": "Display name of the study."
},
"imageWidth": {
"type": "number",
"description": "Pixel width. Coerced from string when the upstream emits a numeric string."
},
"description": {
"type": "string",
"description": "Free-text description."
},
"imageHeight": {
"type": "number",
"description": "Pixel height. Coerced from string when the upstream emits a numeric string."
},
"imageFileName": {
"type": "string",
"description": "Original uploaded filename."
},
"imageTimeStamp": {
"type": "string",
"description": "ISO 8601 capture timestamp."
},
"observationUnitDbId": {
"type": "string",
"description": "FK to the observation unit this image depicts."
},
"observationUnitName": {
"type": "string",
"description": "Display name of the observation unit."
}
},
"description": "Upstream metadata for this image.",
"additionalProperties": {}
},
"mimeType": {
"type": "string",
"description": "Validated image MIME from the response header, or metadata when absent; lowercase without parameters."
},
"imageDbId": {
"type": "string",
"description": "Server-side identifier for the image."
},
"sizeBytes": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Size of the returned byte payload."
}
},
"description": "Metadata for a successfully loaded image; bytes appear once in content[] image blocks.",
"additionalProperties": false
},
"description": "Successfully loaded images."
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"required": [
"imageDbId",
"warning"
],
"properties": {
"warning": {
"type": "string",
"description": "Advisory — bytes loaded but something is suspect."
},
"imageDbId": {
"type": "string",
"description": "Image identifier the warning applies to."
}
},
"description": "Per-image advisory for successfully loaded images.",
"additionalProperties": false
},
"description": "Per-image advisories; non-image MIME responses are errors, not successful images."
}
},
"additionalProperties": false
}brapi_get_image annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}brapi_find_locations — Brapi Find Locations
Advertised read-onlyOpen-world
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).
brapi_find_locations input schema
{
"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
}brapi_find_locations output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"coordinateAxisOrder",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "The effective loadLimit when truncated; shown is below it when the 24,000-byte inline budget bound first (notice says which).",
"exclusiveMinimum": 0
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"missing_find_route",
"search_endpoint_disabled",
"invalid_bbox",
"unresolved_country_names",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"all_filters_dropped"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `missing_find_route`: Neither the GET list nor a usable POST search route is advertised. `search_endpoint_disabled`: Only a POST search route marked unusable by the active dialect is advertised. `invalid_bbox`: A nonempty bbox is incomplete or has reversed latitude or longitude bounds. `unresolved_country_names`: No countryNames resolve and no effective countryCodes restriction remains. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Length of results[] when truncated.",
"exclusiveMinimum": 0
},
"notice": {
"type": "string",
"description": "Why results[] is empty, or which bound cut it short and the dataframe holding the matched rows."
},
"hasMore": {
"type": "boolean",
"description": "True when more rows exist beyond the returned set."
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"locationDbId"
],
"properties": {
"altitude": {
"type": [
"number",
"null"
],
"description": "Altitude in meters above sea level."
},
"latitude": {
"type": [
"number",
"null"
],
"description": "WGS84 latitude in decimal degrees (legacy field; modern servers use coordinates)."
},
"longitude": {
"type": [
"number",
"null"
],
"description": "WGS84 longitude in decimal degrees (legacy field; modern servers use coordinates)."
},
"coordinates": {
"anyOf": [
{
"type": "object",
"properties": {},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "BrAPI v2 GeoJSON Feature carrying [lon, lat, alt?] in geometry.coordinates."
},
"countryCode": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-3 country code."
},
"countryName": {
"type": [
"string",
"null"
],
"description": "Display name of the country."
},
"abbreviation": {
"type": [
"string",
"null"
],
"description": "Short abbreviation."
},
"locationDbId": {
"type": "string",
"description": "Server-side identifier for the location."
},
"locationName": {
"type": [
"string",
"null"
],
"description": "Display name."
},
"locationType": {
"type": [
"string",
"null"
],
"description": "Type of location (e.g. \"Research Station\", \"Field\", \"Greenhouse\")."
},
"instituteName": {
"type": [
"string",
"null"
],
"description": "Owning institute display name."
},
"documentationURL": {
"type": [
"string",
"null"
],
"description": "URL pointing at extra documentation."
},
"instituteAddress": {
"type": [
"string",
"null"
],
"description": "Postal address of the institute."
}
},
"description": "One BrAPI location record.",
"additionalProperties": {}
},
"description": "Leading matched location rows, up to loadLimit and a 24,000-byte budget, whichever binds first. A bbox filter applies before the cut, across every page scanned."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (unresolved country names, filter overrides, capability gaps)."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "The matched rows, staged as a dataframe when results[] holds fewer.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when results[] holds fewer rows than matched because loadLimit or the inline byte budget bound."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total rows reported by the server, else the rows scanned; with an active bbox, the scanned rows inside it."
},
"distributions": {
"type": "object",
"required": [
"countryCode",
"locationType"
],
"properties": {
"countryCode": {
"type": "object",
"description": "ISO country code → count of locations in that country.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"locationType": {
"type": "object",
"description": "Location type → count of locations of that type.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"description": "Value frequency per field across every matched row fetched.",
"additionalProperties": false
},
"returnedCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Length of results[] after any bbox filtering."
},
"appliedFilters": {
"type": "object",
"description": "Filter map sent upstream (named filters plus extraFilters).",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"refinementHint": {
"type": "string",
"description": "Suggested refinement when the result set is large."
},
"coordinateAxisOrder": {
"enum": [
"spec",
"swapped"
],
"type": "string",
"description": "Axis order used to read GeoJSON Point coordinates: \"spec\" is RFC 7946 [lon, lat, alt?]; \"swapped\" means the upstream stores [lat, lon, alt?] and bbox and rendered coordinates used that order."
}
},
"additionalProperties": false
}brapi_find_locations annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_find_variants — Brapi Find Variants
Advertised read-onlyOpen-world
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).
brapi_find_variants input schema
{
"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
}brapi_find_variants output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"distributions",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "The effective loadLimit when truncated; shown is below it when the 24,000-byte inline budget bound first (notice says which).",
"exclusiveMinimum": 0
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"missing_find_route",
"search_endpoint_disabled",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"all_filters_dropped"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `missing_find_route`: Neither the GET list nor a usable POST search route is advertised. `search_endpoint_disabled`: Only a POST search route marked unusable by the active dialect is advertised. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `all_filters_dropped`: The active dialect dropped every filter the agent supplied — the upstream server does not honor any of the requested scope filters on this endpoint, so the call would silently widen to the unfiltered baseline. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Length of results[] when truncated.",
"exclusiveMinimum": 0
},
"notice": {
"type": "string",
"description": "Why results[] is empty, or which bound cut it short and the dataframe holding the matched rows."
},
"hasMore": {
"type": "boolean",
"description": "True when more rows exist beyond the returned set."
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"variantDbId"
],
"properties": {
"end": {
"type": [
"number",
"null"
],
"description": "End position, 0-based exclusive per BrAPI."
},
"start": {
"type": [
"number",
"null"
],
"description": "Start position, 0-based inclusive per BrAPI."
},
"variantDbId": {
"type": "string",
"description": "Server-side identifier for the variant."
},
"variantType": {
"type": [
"string",
"null"
],
"description": "Variant type (e.g. \"SNP\", \"INDEL\", \"DUP\")."
},
"variantNames": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"description": "Variant name or alias."
}
},
{
"type": "null"
}
],
"description": "Known names / aliases for this variant."
},
"filtersFailed": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"description": "Filter ID that failed."
}
},
{
"type": "null"
}
],
"description": "IDs of QC filters this variant failed, when any."
},
"filtersPassed": {
"type": [
"boolean",
"null"
],
"description": "True when the variant passed all QC filters."
},
"referenceName": {
"type": [
"string",
"null"
],
"description": "Reference sequence name (e.g. \"chr01\")."
},
"alternateBases": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"description": "Alternate allele sequence."
}
},
{
"type": "null"
}
],
"description": "Alternate alleles observed at this position."
},
"filtersApplied": {
"type": [
"boolean",
"null"
],
"description": "True when QC filters were evaluated on this variant."
},
"referenceBases": {
"type": [
"string",
"null"
],
"description": "Reference allele sequence at the variant position."
},
"variantSetDbId": {
"anyOf": [
{
"type": "string",
"description": "Single variant-set FK (older BrAPI servers)."
},
{
"type": "array",
"items": {
"type": "string",
"description": "One variant-set FK."
},
"description": "Variant-set FK array — a variant may belong to multiple sets."
},
{
"type": "null",
"description": "Field present but null on the upstream."
}
],
"description": "FK to the variant set(s) this variant belongs to. May be a string or string[] depending on server."
},
"variantSetDbIds": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"description": "Variant-set FK."
}
},
{
"type": "null"
}
],
"description": "Plural-form FK array per BrAPI v2.1 spec, when the server uses it."
}
},
"description": "One BrAPI variant record.",
"additionalProperties": {}
},
"description": "Leading matched variant rows, up to loadLimit and a 24,000-byte budget, whichever binds first."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (filter overrides, partial data, capability gaps)."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "The matched rows, staged as a dataframe when results[] holds fewer.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when results[] holds fewer rows than matched because loadLimit or the inline byte budget bound."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total rows reported by the server, else the rows scanned."
},
"distributions": {
"type": "object",
"required": [
"variantType",
"referenceName",
"variantSetDbId"
],
"properties": {
"variantType": {
"type": "object",
"description": "Variant type → count of variants of that type.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"referenceName": {
"type": "object",
"description": "Reference sequence name → count of variants on that reference.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"variantSetDbId": {
"type": "object",
"description": "Variant set ID → count of variants in that set.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"description": "Value frequency per field across every matched row fetched.",
"additionalProperties": false
},
"returnedCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Length of results[]."
},
"appliedFilters": {
"type": "object",
"description": "Filter map sent upstream (named filters plus extraFilters).",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"refinementHint": {
"type": "string",
"description": "Suggested refinement when the result set is large."
}
},
"additionalProperties": false
}brapi_find_variants annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_find_genotype_calls — Brapi Find Genotype Calls
Advertised read-onlyOpen-world
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.
brapi_find_genotype_calls input schema
{
"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
}brapi_find_genotype_calls output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"results",
"hasMore",
"callFormatting",
"distributions",
"truncated",
"totalCount",
"returnedCount",
"appliedFilters",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "The effective loadLimit when results[] was cut short; shown is below it when the 24,000-byte inline budget bound first (notice says which).",
"exclusiveMinimum": 0
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"no_filters",
"search_endpoint_disabled"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `no_filters`: No variant set, germplasm, call set, or variant filter was provided. `search_endpoint_disabled`: The active dialect declares POST /search/calls as known-dead on this server. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Length of results[] when loadLimit or the inline byte budget cut it short of the collected calls.",
"exclusiveMinimum": 0
},
"notice": {
"type": "string",
"description": "Why no calls were returned, or which bound cut results[] short and the dataframe holding every collected call."
},
"hasMore": {
"type": "boolean",
"description": "True when the pull stopped early: the deployment pull limit fired (`truncated`), or time for upstream requests ran out before the last page (`warnings` says so). Unlike the filter finders, it ignores the inline cut — shown and cap report that."
},
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"genotype": {
"anyOf": [
{
"type": "object",
"properties": {
"values": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"description": "Per-allele value string."
}
},
{
"type": "null"
}
],
"description": "Encoded allele values — interpret using top-level `callFormatting`."
}
},
"additionalProperties": {}
},
{
"type": "null"
}
],
"description": "Structured genotype payload (array of allele values plus server-specific fields)."
},
"phaseSet": {
"type": [
"string",
"null"
],
"description": "Phase-set identifier linking calls that share a haplotype phase."
},
"callSetDbId": {
"type": [
"string",
"null"
],
"description": "FK to the call set (one germplasm × one variant set = one call set)."
},
"callSetName": {
"type": [
"string",
"null"
],
"description": "Display name of the call set."
},
"variantDbId": {
"type": [
"string",
"null"
],
"description": "FK to the variant being called."
},
"variantName": {
"type": [
"string",
"null"
],
"description": "Display name / alias of the variant."
},
"genotypeValue": {
"type": [
"string",
"null"
],
"description": "Legacy flat string form of the call (provided by some servers instead of `genotype`)."
},
"variantSetDbId": {
"type": [
"string",
"null"
],
"description": "FK to the variant set the call belongs to."
}
},
"description": "One genotype call row.",
"additionalProperties": {}
},
"description": "Leading collected call rows, up to loadLimit and a 24,000-byte budget, whichever binds first."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (truncation, capability gaps, partial pulls)."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "Every collected call, staged when results[] holds fewer rows than were collected.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when the deployment-wide pull limit was reached and more calls exist upstream. Narrow the filters and re-pull."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total calls collected across all pages (below the upstream total when `hasMore` is true: the deployment-wide pull limit fired, or the upstream deadline ended the pull)."
},
"distributions": {
"type": "object",
"required": [
"callSetName",
"variantName",
"variantSetDbId"
],
"properties": {
"callSetName": {
"type": "object",
"description": "Call set name → count of calls from that set.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"variantName": {
"type": "object",
"description": "Variant name → count of calls for that variant.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"variantSetDbId": {
"type": "object",
"description": "Variant set ID → count of calls from that set.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"description": "Value frequency per field across the full collected call set.",
"additionalProperties": false
},
"returnedCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Length of results[]."
},
"appliedFilters": {
"type": "object",
"description": "The body sent to POST /search/calls (variant/germplasm/call-set scope plus pageSize).",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"callFormatting": {
"type": "object",
"properties": {
"sepPhased": {
"type": [
"string",
"null"
],
"description": "Separator between phased allele values (typically \"|\")."
},
"sepUnphased": {
"type": [
"string",
"null"
],
"description": "Separator between unphased allele values (typically \"/\")."
},
"unknownString": {
"type": [
"string",
"null"
],
"description": "String used for unknown / missing calls (often \".\" or \"N\")."
},
"expandHomozygotes": {
"type": [
"boolean",
"null"
],
"description": "When true, homozygous calls are expanded to both alleles."
}
},
"description": "Genotype-encoding hints echoed by the server.",
"additionalProperties": false
}
},
"additionalProperties": false
}brapi_find_genotype_calls annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_export_genotype_matrix — Brapi Export Genotype Matrix
Advertised read-onlyOpen-world
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.
brapi_export_genotype_matrix input schema
{
"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
}brapi_export_genotype_matrix output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"format",
"rowCount",
"columnCount",
"variantColumnLegend",
"callFormatting",
"dataframe",
"truncated",
"warnings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"map": {
"type": "string",
"description": "PLINK .map text — chromosome, variant ID, genetic-distance placeholder 0, and one-based position (BrAPI start + 1). Missing/invalid coordinates use `0`. Present for format=\"plink\"."
},
"ped": {
"type": "string",
"description": "PLINK .ped text — FID IID PAT MAT SEX PHENO placeholders (all 0) followed by biallelic genotype pairs per variant, one row per sample. Present only when format=\"plink\". Alleles are passed through verbatim; PLINK missing is `0`."
},
"vcf": {
"type": "string",
"description": "VCF-lite text — header `#CHROM POS ID REF ALT` plus genotype columns. One-based POS is BrAPI start + 1; missing/invalid coordinates use \".\". Present for format=\"vcf-lite\"."
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"no_filters",
"search_endpoint_disabled"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `no_filters`: No variantSetDbId was provided. `search_endpoint_disabled`: The active dialect declares POST /search/calls as known-dead on this server. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"format": {
"enum": [
"plink",
"vcf-lite",
"matrix-json"
],
"type": "string",
"description": "The output format that was produced."
},
"notice": {
"type": "string",
"description": "The matrix dataframe and the tools that read it."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of call-set (germplasm) rows in the matrix."
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages (truncation, missing fields, etc.)."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "The wide germplasm × variant matrix, staged for every format; brapi_dataframe_export writes it to a file where that tool is listed. vcf, ped, and map serialize the same data.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when the matrix is not the complete upstream result: the call pull reached the effective maxCalls cap or ran out of time before the last page, or more distinct variants came back than the effective maxColumns cap. `warnings` names which."
},
"columnCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Number of variant columns in the matrix (excluding the germplasm ID column)."
},
"callFormatting": {
"type": "object",
"properties": {
"sepPhased": {
"type": [
"string",
"null"
],
"description": "Phased allele separator."
},
"sepUnphased": {
"type": [
"string",
"null"
],
"description": "Unphased allele separator."
},
"unknownString": {
"type": [
"string",
"null"
],
"description": "String used for unknown/missing calls."
},
"expandHomozygotes": {
"type": [
"boolean",
"null"
],
"description": "Homozygous allele expansion flag."
}
},
"description": "Genotype-encoding hints echoed by the server.",
"additionalProperties": false
},
"variantColumnLegend": {
"type": "object",
"description": "SQL-safe dataframe column name → original variantDbId.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"additionalProperties": false
}brapi_export_genotype_matrix annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_dataframe_describe — Brapi Dataframe Describe
Advertised read-only
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.
brapi_dataframe_describe input schema
{
"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
}brapi_dataframe_describe output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"tables"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"list_all_disabled_on_shared_http"
],
"description": "Machine-readable failure mode. Declared by this tool: `list_all_disabled_on_shared_http`: Listing was requested on a shared HTTP endpoint without per-caller auth, from a request with no session-scoped workspace — the listing would expose other clients' dataframes, since those requests all share one tenant workspace. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"tables": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"rowCount",
"columns"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe name. Use this in SQL queries."
},
"columns": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"description": "Column name."
},
"type": {
"type": "string",
"description": "SQL column type (VARCHAR, INTEGER, DOUBLE, BOOLEAN, etc.)."
},
"nullable": {
"type": "boolean",
"description": "True when NULL values are allowed."
}
},
"description": "Column declaration.",
"additionalProperties": false
},
"description": "Schema in declaration order."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows currently registered."
},
"provenance": {
"type": "object",
"required": [
"source",
"baseUrl",
"query",
"createdAt",
"expiresAt"
],
"properties": {
"query": {
"description": "Original filter map / search body."
},
"source": {
"type": "string",
"description": "Tool/operation that produced the dataframe (e.g. find_observations)."
},
"baseUrl": {
"type": "string",
"description": "BrAPI base URL the rows were pulled from."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 dataframe creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 expiry — when the dataframe metadata will be evicted."
}
},
"description": "Originating-source provenance — present only for auto-registered dataframes (`df_*`).",
"additionalProperties": false
},
"approxSizeBytes": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Approximate size in bytes."
}
},
"description": "Dataframe description.",
"additionalProperties": false
},
"description": "All described dataframes."
}
},
"additionalProperties": false
}brapi_dataframe_describe annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}brapi_dataframe_query — Brapi Dataframe Query
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.
brapi_dataframe_query input schema
{
"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
}brapi_dataframe_query output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"rowCount",
"columns",
"rows"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row ceiling that bound the response: the smallest of preview, rowLimit, and the deployment-wide response cap.",
"exclusiveMinimum": 0
},
"rows": {
"type": "array",
"items": {
"type": "object",
"description": "One result row. Columns are projected from the SQL SELECT clause; call brapi_dataframe_describe to inspect source dataframe schemas.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "Leading rows bounded by preview/rowLimit and 24,000 bytes on each serialized row representation. May be empty when the first row is oversized."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"sql_rejected",
"sql_execution_error",
"missing_table",
"register_as_clash"
],
"description": "Machine-readable failure mode. Declared by this tool: `sql_rejected`: SQL broke the read-only rules: more than one statement, a non-SELECT, a disallowed operation or function, a file or URL named as a table, a system-catalog read, or a DESCRIBE, SUMMARIZE, or SHOW statement. `sql_execution_error`: The SELECT passed the read-only rules but failed while running on the staged data, such as a cast of a value that does not convert. `missing_table`: The SQL names a dataframe this workspace does not hold, because it expired, was dropped, or the name is mistyped. `register_as_clash`: The registerAs name is already taken by a dataframe in this workspace. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows materialized into `rows`."
},
"notice": {
"type": "string",
"description": "Guidance for reaching the rows this response left out."
},
"columns": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"description": "Column name in projection order."
},
"type": {
"type": "string",
"description": "DuckDB column type (e.g. VARCHAR, BIGINT, DOUBLE, BOOLEAN, JSON), the same with or without `registerAs`."
}
},
"description": "One column descriptor — name and SQL/DuckDB type.",
"additionalProperties": false
},
"description": "Column names and types in projection order, enough to write a follow-up query."
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Total rows the query produced (may exceed `rows.length` when capped)."
},
"dataframe": {
"type": "string",
"description": "Name of the dataframe holding the full result, populated when `registerAs` was supplied. Reference this name in follow-up queries."
},
"truncated": {
"type": "boolean",
"description": "True when the response carries fewer rows than the query produced."
}
},
"additionalProperties": false
}brapi_dataframe_query annotations
{
"readOnlyHint": false,
"openWorldHint": false,
"idempotentHint": false
}brapi_raw_get — Brapi Raw Get
Advertised read-onlyOpen-world
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.
brapi_raw_get input schema
{
"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
}brapi_raw_get output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"url",
"path",
"metadata"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Effective loadLimit row ceiling, even when the byte budget binds first.",
"exclusiveMinimum": 0
},
"url": {
"type": "string",
"description": "Fully resolved URL that was fetched (baseUrl + path + query string)."
},
"path": {
"type": "string",
"description": "Normalized path (leading `/` preserved) that was appended to the baseUrl."
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"cross_origin_path"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `cross_origin_path`: path argument was a full URL instead of a relative BrAPI route. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Actual list rows returned inline."
},
"notice": {
"type": "string",
"description": "When a dataframe was staged, its name and the tools that read it."
},
"result": {
"description": "Raw BrAPI `result` value — whatever shape the endpoint returns."
},
"metadata": {
"type": "object",
"properties": {
"pagination": {
"type": "object",
"properties": {
"pageSize": {
"type": "number",
"description": "Rows per page, when reported."
},
"totalCount": {
"type": "number",
"description": "Total matching rows, when reported."
},
"totalPages": {
"type": "number",
"description": "Total pages, when reported."
},
"currentPage": {
"type": "number",
"description": "0-indexed page number, when reported."
}
},
"description": "BrAPI pagination block. Absent when the endpoint does not paginate.",
"additionalProperties": {}
}
},
"description": "BrAPI envelope metadata (pagination and any additional upstream fields).",
"additionalProperties": {}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages — present when the dataframe walk stopped before the upstream total."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "Every fetched row of a list result, staged when the inline preview omits rows. Explicit paging stages only the requested page.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when the inline list leaves fetched or matching rows out."
},
"suggestion": {
"type": "string",
"description": "Emitted when a curated goal-shaped tool covers this endpoint, or takes the IDs it lists."
}
},
"additionalProperties": false
}brapi_raw_get annotations
{
"readOnlyHint": true,
"openWorldHint": true
}brapi_raw_search — Brapi Raw Search
Advertised read-onlyOpen-world
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.
brapi_raw_search input schema
{
"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
}brapi_raw_search output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"alias",
"noun",
"kind",
"metadata"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Effective loadLimit row ceiling, even when the byte budget binds first.",
"exclusiveMinimum": 0
},
"kind": {
"enum": [
"sync",
"async"
],
"type": "string",
"description": "Whether the server returned inline results or we polled an async search."
},
"noun": {
"type": "string",
"description": "The `/search/{noun}` segment the body was posted to."
},
"alias": {
"type": "string",
"description": "Connection alias the call used."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"upstream_not_found",
"upstream_rate_limited",
"unknown_alias",
"auth_token_exchange_failed",
"auth_no_access_token",
"capability_discovery_unavailable",
"upstream_unauthorized",
"upstream_forbidden",
"alias_base_url_invalid",
"private_address_blocked",
"search_endpoint_disabled"
],
"description": "Machine-readable failure mode. Declared by this tool: `upstream_not_found`: An uncaught BrAPI data request answered HTTP 404. `upstream_rate_limited`: An uncaught BrAPI data request exhausted retries after HTTP 429. `unknown_alias`: No connection is registered under the requested alias, and the server has no base URL configured for it to connect on first use. `auth_token_exchange_failed`: Connecting the alias on first use, the SGN or OAuth token exchange against the BrAPI /token endpoint failed. `auth_no_access_token`: Connecting the alias on first use, the token endpoint answered without returning an access token. `capability_discovery_unavailable`: Neither /serverinfo nor /calls listed any call, and at least one of them timed out, was unreachable, or answered 429 or a 5xx other than 501, so nothing was cached. `upstream_unauthorized`: The BrAPI server answered HTTP 401: it requires credentials, or rejected the ones sent. `upstream_forbidden`: The BrAPI server answered HTTP 403: the credentials sent, or their absence, lack access. `alias_base_url_invalid`: The base URL configured on the server for this alias is not an absolute http(s) URL, or carries credentials. `private_address_blocked`: The base URL configured for this alias, or its token URL, is on a private or reserved address this server may not reach. `search_endpoint_disabled`: The active dialect declares this POST /search/{noun} route as known-dead on this server. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Actual list rows returned inline."
},
"notice": {
"type": "string",
"description": "When a dataframe was staged, its name and the tools that read it."
},
"result": {
"description": "Raw BrAPI `result` value — whatever shape the endpoint returns."
},
"metadata": {
"type": "object",
"properties": {
"pagination": {
"type": "object",
"properties": {
"pageSize": {
"type": "number",
"description": "Rows per page, when reported."
},
"totalCount": {
"type": "number",
"description": "Total matching rows, when reported."
},
"totalPages": {
"type": "number",
"description": "Total pages, when reported."
},
"currentPage": {
"type": "number",
"description": "0-indexed page number, when reported."
}
},
"description": "BrAPI pagination block. Absent when the endpoint does not paginate.",
"additionalProperties": {}
}
},
"description": "BrAPI envelope metadata (pagination and any additional upstream fields).",
"additionalProperties": {}
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Advisory messages — present when the dataframe walk stopped before the upstream total."
},
"dataframe": {
"type": "object",
"required": [
"tableName",
"rowCount",
"columns",
"createdAt",
"expiresAt"
],
"properties": {
"columns": {
"type": "array",
"items": {
"type": "string",
"description": "Column name."
},
"description": "Every column name."
},
"maxRows": {
"type": "integer",
"maximum": 9007199254740991,
"description": "Row cap that ended the pull, present only when that cap fired.",
"exclusiveMinimum": 0
},
"rowCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rows in the dataframe."
},
"createdAt": {
"type": "string",
"description": "ISO 8601 creation time."
},
"expiresAt": {
"type": "string",
"description": "ISO 8601 time the dataframe metadata is purged; copy rows out before, or re-run the producing tool."
},
"tableName": {
"type": "string",
"description": "Table name for brapi_dataframe_describe and brapi_dataframe_query."
},
"truncated": {
"type": "boolean",
"description": "True when the dataframe holds less than the upstream reports: a cap, failed page, deadline, or short upstream ended the pull, or it was skipped. warnings says which. Absent otherwise."
},
"totalCount": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0,
"description": "Upstream-reported row total, when known; can exceed rowCount."
},
"columnLegend": {
"type": "object",
"description": "Sanitized column name → original upstream key, present only when a column was renamed to be SQL-safe (e.g. `end` → `end_`). SQL uses the sanitized names.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"description": "Every fetched row of a list result, staged when the inline preview omits rows. Explicit paging stages only the requested page.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when the inline list leaves fetched or matching rows out."
},
"suggestion": {
"type": "string",
"description": "Emitted when a curated goal-shaped tool covers this search, or takes the IDs it lists."
},
"searchResultsDbId": {
"type": "string",
"description": "Populated when the server returned an async searchResultsDbId."
}
},
"additionalProperties": false
}brapi_raw_search annotations
{
"readOnlyHint": true,
"openWorldHint": true
}Prompts
2 advertised
brapi_eda_study
Run an exploratory-data-analysis pass over a single BrAPI study — structure, variables, coverage, outliers, missing data — using the curated brapi_* tools.
- studyDbId
- Target studyDbId. Locate via brapi_find_studies if unknown. (required)
- alias
- Connection alias: one registered via brapi_connect, or a built-in or operator-configured alias. Omit to use the default connection.
brapi_meta_analysis
Run a cross-study meta-analysis on a germplasm × trait combination — resolve trait, find studies, pull observations, harmonize scales, summarize across studies.
- germplasmDbIds
- Comma-separated germplasmDbIds (e.g. "germplasm-1,germplasm-2"). The meta-analysis will collect every observation of the target trait on these germplasm across all reachable studies. (required)
- traitName
- Target trait name or free-text query — e.g. "dry matter content", "Plant height". Resolved to one or more observation variables via brapi_find_variables. (required)
- alias
- Connection alias: one registered via brapi_connect, or a built-in or operator-configured alias. Omit to use the default connection. For multi-server meta-analyses, run this prompt once per alias and merge.
Resources
9 advertised
brapi-server-info — BrAPI server orientation envelope
Orientation envelope for the default BrAPI connection — identity, capabilities, content counts, suggested finders, notes. Same payload as the brapi_server_info tool.
brapi-server-info URI
brapi://server/infobrapi-calls — BrAPI capability profile
Capability profile for the default BrAPI connection — supported services, their HTTP methods, declared versions, and crops list. Mirrors what /serverinfo + /calls returned at the last load.
brapi-calls URI
brapi://callsBrAPI filter catalog · germplasm — BrAPI filter catalog
Filter names accepted by /germplasm on a BrAPI v2.1 server.
BrAPI filter catalog · germplasm URI
brapi://filters/germplasmBrAPI filter catalog · images — BrAPI filter catalog
Filter names accepted by /images on a BrAPI v2.1 server.
BrAPI filter catalog · images URI
brapi://filters/imagesBrAPI filter catalog · locations — BrAPI filter catalog
Filter names accepted by /locations on a BrAPI v2.1 server.
BrAPI filter catalog · locations URI
brapi://filters/locationsBrAPI filter catalog · observations — BrAPI filter catalog
Filter names accepted by /observations on a BrAPI v2.1 server.
BrAPI filter catalog · observations URI
brapi://filters/observationsBrAPI filter catalog · studies — BrAPI filter catalog
Filter names accepted by /studies on a BrAPI v2.1 server.
BrAPI filter catalog · studies URI
brapi://filters/studiesBrAPI filter catalog · variables — BrAPI filter catalog
Filter names accepted by /variables on a BrAPI v2.1 server.
BrAPI filter catalog · variables URI
brapi://filters/variablesBrAPI filter catalog · variants — BrAPI filter catalog
Filter names accepted by /variants on a BrAPI v2.1 server.
BrAPI filter catalog · variants URI
brapi://filters/variantsbrapi-study — BrAPI study record
Single-study resource on the default BrAPI connection — same payload as the brapi_get_study tool, addressable by URI.
brapi-study URI template
brapi://study/{studyDbId}brapi-germplasm — BrAPI germplasm record
Single-germplasm resource on the default BrAPI connection — same payload as the brapi_get_germplasm tool, addressable by URI.
brapi-germplasm URI template
brapi://germplasm/{germplasmDbId}brapi-variable — BrAPI observation variable record
Single observation-variable resource on the default BrAPI connection — the canonical /variables/{id} record (trait, scale, method, ontology), addressable by URI. The single-record equivalent of brapi_find_variables.
brapi-variable URI template
brapi://variable/{observationVariableDbId}brapi-filters — BrAPI filter catalog
BrAPI filter catalog for a single endpoint (name, type, description, example per filter). Mirrors the brapi_describe_filters tool.
brapi-filters URI template
brapi://filters/{endpoint}30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 989 ms
- 95th percentile latency
- 989 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 989 ms · metadata changed · 22 tool(s), 9 resource(s), 4 resource template(s), 2 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http brapi-mcp-server-caseyjhand https://brapi.caseyjhand.com/mcpCodex
Codex configuration
codex mcp add brapi-mcp-server-caseyjhand --url https://brapi.caseyjhand.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"brapi-mcp-server-caseyjhand": {
"url": "https://brapi.caseyjhand.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"brapi-mcp-server-caseyjhand": {
"type": "streamableHttp",
"url": "https://brapi.caseyjhand.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"brapi-mcp-server-caseyjhand": {
"type": "http",
"url": "https://brapi.caseyjhand.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http brapi-mcp-server-caseyjhand https://brapi.caseyjhand.com/mcpClaude Desktop
Claude Desktop configuration
https://brapi.caseyjhand.com/mcpWindsurf
Windsurf configuration
{
"mcpServers": {
"brapi-mcp-server-caseyjhand": {
"serverUrl": "https://brapi.caseyjhand.com/mcp"
}
}
}Let your agent find its tools
Find servers like brapi-mcp-server from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.