VegBankAPI (2.1.1)
Welcome to the official documentation for the VegBank REST API. You can find out more about VegBank at https://github.com/NCEAS/vegbank2.
Introduction
The VegBank data system provides a community managed data portal for vegetation data, particularly plots, plant taxonomy, and communities. Developed, maintained, and operated by the National Center for Ecological Analysis and Synthesis (NCEAS), VegBank is a product of the Ecological Society of America (ESA) Vegetation Panel, and is affiliated with the National Vegetation Classification (USNVC).
VegBank provides a common storage system and web portal for accessing:
- Plot data
- Plant taxonomy data
- Community data
VegBank is an open source, community project. We welcome contributions in many forms, including code, graphics, documentation, bug reports, testing, etc.
Use the VegBank discussions to ask questions, raise issues, or discuss contributions with us.
Operations related to plot observations. A plot observation is a recording of the physical, biological, and other environmental attributes (and more) of a defined plot at some time and in some place, along with other supporting contextual information. In VegBank, each plot observation is typically linked to details about the plants (taxon observations) that were observed in the plot and interpreted to some plant concept, and it is typically classified to a specific community concept.
Get plot observation
Retrieve a single plot observation using its ob_code.
path Parameters
| ob_code required | string Example: ob.1 |
query Parameters
| detail | string Default: "full" Enum: "geo" "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
| bundle | string If 'csv', return a zip archive of CSVs. When set, the |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||
Array of objects Data records | |||||||||
Array
| |||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "author_obs_code": "YOSE.001",
- "latitude": 42.19,
- "longitude": -104.54
}
]
}Get plot observations by project
Retrieve a paginated and sorted collection of plot observations representing all plot observations associated with the specified project (using its pj_code), or a subset thereof based on a specified search query.
path Parameters
| pj_code required | string Example: pj.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" Status criterion for returned plot observations:
|
| detail | string Default: "full" Enum: "geo" "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "author_obs_code" "+author_obs_code" "-author_obs_code" Example: sort=-author_obs_code Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
| bundle | string If 'csv', return a zip archive of CSVs. When set, the |
| num_taxa | integer >= 0 Default: 5 Number of taxa to return per plot observation. Sort order depends on detail level:
|
| num_comms | integer >= 0 Default: 5 Number of communities to return per plot observation, ordered by commclass_id |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||
Array of objects Data records | |||||||||
Array
| |||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "author_obs_code": "YOSE.001",
- "latitude": 42.19,
- "longitude": -104.54
}
]
}Get plot observations by party
Retrieve a paginated and sorted collection of plot observations representing all plot observations associated with the specified party (using its py_code), or a subset thereof based on a specified search query.
path Parameters
| py_code required | string Example: py.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" Status criterion for returned plot observations:
|
| detail | string Default: "full" Enum: "geo" "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "author_obs_code" "+author_obs_code" "-author_obs_code" Example: sort=-author_obs_code Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
| bundle | string If 'csv', return a zip archive of CSVs. When set, the |
| num_taxa | integer >= 0 Default: 5 Number of taxa to return per plot observation. Sort order depends on detail level:
|
| num_comms | integer >= 0 Default: 5 Number of communities to return per plot observation, ordered by commclass_id |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||
Array of objects Data records | |||||||||
Array
| |||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "author_obs_code": "YOSE.001",
- "latitude": 42.19,
- "longitude": -104.54
}
]
}Get plot observations by named place
Retrieve a paginated and sorted collection of plot observations representing all plot observations associated with the specified named place (using its np_code), or a subset thereof based on a specified search query.
path Parameters
| np_code required | string Example: np.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" Status criterion for returned plot observations:
|
| detail | string Default: "full" Enum: "geo" "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "author_obs_code" "+author_obs_code" "-author_obs_code" Example: sort=-author_obs_code Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
| bundle | string If 'csv', return a zip archive of CSVs. When set, the |
| num_taxa | integer >= 0 Default: 5 Number of taxa to return per plot observation. Sort order depends on detail level:
|
| num_comms | integer >= 0 Default: 5 Number of communities to return per plot observation, ordered by commclass_id |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||
Array of objects Data records | |||||||||
Array
| |||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "author_obs_code": "YOSE.001",
- "latitude": 42.19,
- "longitude": -104.54
}
]
}Get plot observations by plant concept
Retrieve a paginated and sorted collection of plot observations representing all plot observations with taxon observations interpreted to the specified plant concept (using its pc_code), or a subset thereof based on a specified search query.
path Parameters
| pc_code required | string Example: pc.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" Status criterion for returned plot observations:
|
| detail | string Default: "full" Enum: "geo" "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "author_obs_code" "+author_obs_code" "-author_obs_code" Example: sort=-author_obs_code Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
| bundle | string If 'csv', return a zip archive of CSVs. When set, the |
| num_taxa | integer >= 0 Default: 5 Number of taxa to return per plot observation. Sort order depends on detail level:
|
| num_comms | integer >= 0 Default: 5 Number of communities to return per plot observation, ordered by commclass_id |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||
Array of objects Data records | |||||||||
Array
| |||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "author_obs_code": "YOSE.001",
- "latitude": 42.19,
- "longitude": -104.54
}
]
}Get plot observations by community concept
Retrieve a paginated and sorted collection of plot observations representing all plot observations with taxon observations interpreted to the specified community concept (using its cc_code), or a subset thereof based on a specified search query.
path Parameters
| cc_code required | string Example: cc.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" Status criterion for returned plot observations:
|
| detail | string Default: "full" Enum: "geo" "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "author_obs_code" "+author_obs_code" "-author_obs_code" Example: sort=-author_obs_code Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
| bundle | string If 'csv', return a zip archive of CSVs. When set, the |
| num_taxa | integer >= 0 Default: 5 Number of taxa to return per plot observation. Sort order depends on detail level:
|
| num_comms | integer >= 0 Default: 5 Number of communities to return per plot observation, ordered by commclass_id |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||
Array of objects Data records | |||||||||
Array
| |||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "author_obs_code": "YOSE.001",
- "latitude": 42.19,
- "longitude": -104.54
}
]
}Get plot observations by cover method
Retrieve a paginated and sorted collection of plot observations representing all plot observations using the specified cover method (using its cm_code), or a subset thereof based on a specified search query.
path Parameters
| cm_code required | string Example: cm.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" Status criterion for returned plot observations:
|
| detail | string Default: "full" Enum: "geo" "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "author_obs_code" "+author_obs_code" "-author_obs_code" Example: sort=-author_obs_code Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
| bundle | string If 'csv', return a zip archive of CSVs. When set, the |
| num_taxa | integer >= 0 Default: 5 Number of taxa to return per plot observation. Sort order depends on detail level:
|
| num_comms | integer >= 0 Default: 5 Number of communities to return per plot observation, ordered by commclass_id |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||
Array of objects Data records | |||||||||
Array
| |||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "author_obs_code": "YOSE.001",
- "latitude": 42.19,
- "longitude": -104.54
}
]
}Get plot observations by stratum method
Retrieve a paginated and sorted collection of plot observations representing all plot observations using the specified stratum method (using its sm_code), or a subset thereof based on a specified search query.
path Parameters
| sm_code required | string Example: sm.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" Status criterion for returned plot observations:
|
| detail | string Default: "full" Enum: "geo" "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "author_obs_code" "+author_obs_code" "-author_obs_code" Example: sort=-author_obs_code Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
| bundle | string If 'csv', return a zip archive of CSVs. When set, the |
| num_taxa | integer >= 0 Default: 5 Number of taxa to return per plot observation. Sort order depends on detail level:
|
| num_comms | integer >= 0 Default: 5 Number of communities to return per plot observation, ordered by commclass_id |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||
Array of objects Data records | |||||||||
Array
| |||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "author_obs_code": "YOSE.001",
- "latitude": 42.19,
- "longitude": -104.54
}
]
}Get all plot observations included in a user dataset
Retrieve a paginated and sorted collection of all plot observations associated with the specified user dataset (using its ds_code), or a subset thereof based on a specified search query.
path Parameters
| ds_code required | string Example: ds.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" Status criterion for returned plot observations:
|
| detail | string Default: "full" Enum: "geo" "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "author_obs_code" "+author_obs_code" "-author_obs_code" Example: sort=-author_obs_code Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
| bundle | string If 'csv', return a zip archive of CSVs. When set, the |
| num_taxa | integer >= 0 Default: 5 Number of taxa to return per plot observation. Sort order depends on detail level:
|
| num_comms | integer >= 0 Default: 5 Number of communities to return per plot observation, ordered by commclass_id |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||
Array of objects Data records | |||||||||
Array
| |||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "author_obs_code": "YOSE.001",
- "latitude": 42.19,
- "longitude": -104.54
}
]
}Get all plot observations
Retrieve a paginated and sorted collection of plot observations representing all plot observations in VegBank, or a subset thereof based on a specified search query.
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" Status criterion for returned plot observations:
|
| detail | string Default: "full" Enum: "geo" "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "author_obs_code" "+author_obs_code" "-author_obs_code" Example: sort=-author_obs_code Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
| bundle | string If 'csv', return a zip archive of CSVs. When set, the |
| num_taxa | integer >= 0 Default: 5 Number of taxa to return per plot observation. Sort order depends on detail level:
|
| num_comms | integer >= 0 Default: 5 Number of communities to return per plot observation, ordered by commclass_id |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||
Array of objects Data records | |||||||||
Array
| |||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "author_obs_code": "YOSE.001",
- "latitude": 42.19,
- "longitude": -104.54
}
]
}Upload plot observations
Authorizations:
query Parameters
| dry_run | boolean Default: false If true, validates and previews the upload without persisting any data. The response will be wrapped in a |
Request Body schema: multipart/form-datarequired
| plot_observations required | string <binary> Parquet file containing new plot observations (required). |
| projects | string <binary> Parquet file containing new projects (optional). |
| parties | string <binary> Parquet file containing new parties (optional). |
| references | string <binary> Parquet file containing new references (optional). |
| soils | string <binary> Parquet file containing details about observed soils (optional). |
| disturbances | string <binary> Parquet file containing details about observed disturbances (optional). |
| community_classifications | string <binary> Parquet file containing community classifications of observed plots (optional). |
| strata | string <binary> Parquet file containing details about strata defined for plot observations (optional). |
| strata_cover_data | string <binary> Parquet file containing details about plant cover as observed in different strata of a plot (optional). |
| stem_data | string <binary> Parquet file containing details about counts and/or other details about stems observed on a plot (optional). |
| taxon_interpretations | string <binary> Parquet file containing taxon interpretations of plants observed on a plot (optional). |
| contributors | string <binary> Parquet file containing party contributions to the plot observations, projects, and/or community classifications (optional). |
Responses
Response Schema: application/json
object | |||||||||||||
| |||||||||||||
object | |||||||||||||
| |||||||||||||
Response samples
- 200
- 403
- 500
{- "counts": {
- "xx": {
- "inserted": 1
}, - "yy": {
- "inserted": 2
}, - "ds": {
- "inserted": 1
}
}, - "resources": {
- "xx": [
- {
- "action": "INSERT",
- "user_xx_code": "my_xx_code",
- "vb_xx_code": "xx.123"
}
], - "yy": [
- {
- "action": "INSERT",
- "user_yy_code": "my_yy_code_1",
- "vb_yy_code": "yy.123"
}
], - "ds": [
- {
- "action": "INSERT",
- "user_ds_code": "upload_dataset_20260325110254",
- "vb_ds_code": "ds.123"
}
]
}
}Operations related to community concepts. A community concept is the assertion of a specific community type through the combination of a name and an associated reference, augmented by status details, any alternative names, and optional relationships (correlations) with other community concepts.
Get community concept
Retrieve a single community concept using its cc_code.
path Parameters
| cc_code required | string Example: cc.1 |
query Parameters
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cc_code": "cc.1",
- "comm_name": "Muhlenbergia rigens Wet Meadow",
- "comm_code": "CEGL005306",
- "comm_description": "This herbaceous bunchgrass association has been documented in...",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "NatureServe Biotics 2019",
- "status_rf_code": "rf.1",
- "status_rf_label": "NatureServe Biotics 2019",
- "obs_count": 17,
- "comm_level": "Association",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "NatureServe (organization)",
- "comm_party_comments": "This association is the result of...",
- "parent_cc_code": "cc.1",
- "parent_name": "Leymus cinereus - Leymus triticoides Alkaline Wet Meadow Alliance"
}
]
}Get community concepts by cl
Retrieve a paginated and sorted collection of community concepts representing all concepts interpreted under the specified community classification (using its cl_code), or a subset thereof based on a specified search query.
path Parameters
| cl_code required | string Example: cl.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "comm_name" "+comm_name" "-comm_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cc_code": "cc.1",
- "comm_name": "Muhlenbergia rigens Wet Meadow",
- "comm_code": "CEGL005306",
- "comm_description": "This herbaceous bunchgrass association has been documented in...",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "NatureServe Biotics 2019",
- "status_rf_code": "rf.1",
- "status_rf_label": "NatureServe Biotics 2019",
- "obs_count": 17,
- "comm_level": "Association",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "NatureServe (organization)",
- "comm_party_comments": "This association is the result of...",
- "parent_cc_code": "cc.1",
- "parent_name": "Leymus cinereus - Leymus triticoides Alkaline Wet Meadow Alliance"
}
]
}Get community concepts by ob
Retrieve a paginated and sorted collection of community concepts representing all concepts associated with the specified plot observation (using its ob_code), or a subset thereof based on a specified search query.
path Parameters
| ob_code required | string Example: ob.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "comm_name" "+comm_name" "-comm_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cc_code": "cc.1",
- "comm_name": "Muhlenbergia rigens Wet Meadow",
- "comm_code": "CEGL005306",
- "comm_description": "This herbaceous bunchgrass association has been documented in...",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "NatureServe Biotics 2019",
- "status_rf_code": "rf.1",
- "status_rf_label": "NatureServe Biotics 2019",
- "obs_count": 17,
- "comm_level": "Association",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "NatureServe (organization)",
- "comm_party_comments": "This association is the result of...",
- "parent_cc_code": "cc.1",
- "parent_name": "Leymus cinereus - Leymus triticoides Alkaline Wet Meadow Alliance"
}
]
}Get community concepts by py
Retrieve a paginated and sorted collection of the community concepts with a party perspective (i.e. status record) provided by the specified party (using its py_code), or a subset thereof based on a specified search query.
path Parameters
| py_code required | string Example: py.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "comm_name" "+comm_name" "-comm_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cc_code": "cc.1",
- "comm_name": "Muhlenbergia rigens Wet Meadow",
- "comm_code": "CEGL005306",
- "comm_description": "This herbaceous bunchgrass association has been documented in...",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "NatureServe Biotics 2019",
- "status_rf_code": "rf.1",
- "status_rf_label": "NatureServe Biotics 2019",
- "obs_count": 17,
- "comm_level": "Association",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "NatureServe (organization)",
- "comm_party_comments": "This association is the result of...",
- "parent_cc_code": "cc.1",
- "parent_name": "Leymus cinereus - Leymus triticoides Alkaline Wet Meadow Alliance"
}
]
}Get community concepts by rf
Retrieve a paginated and sorted collection of the community concepts associated with a given reference (using its rf_code), or a subset thereof based on a specified search query.
path Parameters
| rf_code required | string Example: rf.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "comm_name" "+comm_name" "-comm_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cc_code": "cc.1",
- "comm_name": "Muhlenbergia rigens Wet Meadow",
- "comm_code": "CEGL005306",
- "comm_description": "This herbaceous bunchgrass association has been documented in...",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "NatureServe Biotics 2019",
- "status_rf_code": "rf.1",
- "status_rf_label": "NatureServe Biotics 2019",
- "obs_count": 17,
- "comm_level": "Association",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "NatureServe (organization)",
- "comm_party_comments": "This association is the result of...",
- "parent_cc_code": "cc.1",
- "parent_name": "Leymus cinereus - Leymus triticoides Alkaline Wet Meadow Alliance"
}
]
}Get all community concepts
Retrieve a paginated and sorted collection of community concepts representing all concepts stored in VegBank, or a subset thereof based on a specified search query.
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "comm_name" "+comm_name" "-comm_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cc_code": "cc.1",
- "comm_name": "Muhlenbergia rigens Wet Meadow",
- "comm_code": "CEGL005306",
- "comm_description": "This herbaceous bunchgrass association has been documented in...",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "NatureServe Biotics 2019",
- "status_rf_code": "rf.1",
- "status_rf_label": "NatureServe Biotics 2019",
- "obs_count": 17,
- "comm_level": "Association",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "NatureServe (organization)",
- "comm_party_comments": "This association is the result of...",
- "parent_cc_code": "cc.1",
- "parent_name": "Leymus cinereus - Leymus triticoides Alkaline Wet Meadow Alliance"
}
]
}Upload community concepts
Authorizations:
query Parameters
| dry_run | boolean Default: false If true, validates and previews the upload without persisting any data. The response will be wrapped in a |
| deactivation | string Default: "none" Enum: "none" "by_party" Which existing concepts to deactivate in VegBank by setting their status stop date to now:
|
Request Body schema: multipart/form-datarequired
| community_concepts required | string <binary> Parquet file containing community concepts as community names associated with references, along with with status details and taxonomic parents (required). |
| community_names | string <binary> Parquet file containing community name usages associated with specific classification systems for new community concepts (optional). |
| community_correlations | string <binary> Parquet file defining correlations between community concepts (optional). |
| parties | string <binary> Parquet file containing new parties (optional). |
| references | string <binary> Parquet file containing new references (optional). |
Responses
Response Schema: application/json
object | |||||||||||||
| |||||||||||||
object | |||||||||||||
| |||||||||||||
Response samples
- 200
- 403
- 500
{- "counts": {
- "xx": {
- "inserted": 1
}, - "yy": {
- "inserted": 2
}, - "ds": {
- "inserted": 1
}
}, - "resources": {
- "xx": [
- {
- "action": "INSERT",
- "user_xx_code": "my_xx_code",
- "vb_xx_code": "xx.123"
}
], - "yy": [
- {
- "action": "INSERT",
- "user_yy_code": "my_yy_code_1",
- "vb_yy_code": "yy.123"
}
], - "ds": [
- {
- "action": "INSERT",
- "user_ds_code": "upload_dataset_20260325110254",
- "vb_ds_code": "ds.123"
}
]
}
}Operations related to community classifications. A community classification is an activity wherein one or more contributors make one or more community interpretations, each of which corresponds to the assignment of a community concept to a plot observation.
Get community classification
Retrieve a single community classification using its cl_code.
path Parameters
| cl_code required | string Example: cl.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cl_code": "cl.1",
- "ob_code": "ob.1",
- "class_start_date": "2006-05-30",
- "class_stop_date": "2006-05-30",
- "inspection": false,
- "table_analysis": false,
- "multivariate_analysis": false,
- "expert_system": "DCA, UPGMA",
- "class_publication_rf_code": "rf.1",
- "class_publication_rf_label": "NVC 2004",
- "class_notes": "Abies Grandis Alliance"
}
]
}Get community classifications by cc
Retrieve a paginated collection of community classifications using the specified community concept (using its cc_code).
path Parameters
| cc_code required | string Example: cc.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "comm_name" "+comm_name" "-comm_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cl_code": "cl.1",
- "ob_code": "ob.1",
- "class_start_date": "2006-05-30",
- "class_stop_date": "2006-05-30",
- "inspection": false,
- "table_analysis": false,
- "multivariate_analysis": false,
- "expert_system": "DCA, UPGMA",
- "class_publication_rf_code": "rf.1",
- "class_publication_rf_label": "NVC 2004",
- "class_notes": "Abies Grandis Alliance"
}
]
}Get community classifications by ob
Retrieve a paginated collection of community classifications associated with the specified plot observation (using its ob_code).
path Parameters
| ob_code required | string Example: ob.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "comm_name" "+comm_name" "-comm_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cl_code": "cl.1",
- "ob_code": "ob.1",
- "class_start_date": "2006-05-30",
- "class_stop_date": "2006-05-30",
- "inspection": false,
- "table_analysis": false,
- "multivariate_analysis": false,
- "expert_system": "DCA, UPGMA",
- "class_publication_rf_code": "rf.1",
- "class_publication_rf_label": "NVC 2004",
- "class_notes": "Abies Grandis Alliance"
}
]
}Get all community classifications
Retrieve a paginated collection of all community classifications recorded in VegBank.
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cl_code": "cl.1",
- "ob_code": "ob.1",
- "class_start_date": "2006-05-30",
- "class_stop_date": "2006-05-30",
- "inspection": false,
- "table_analysis": false,
- "multivariate_analysis": false,
- "expert_system": "DCA, UPGMA",
- "class_publication_rf_code": "rf.1",
- "class_publication_rf_label": "NVC 2004",
- "class_notes": "Abies Grandis Alliance"
}
]
}Upload community classifications
Authorizations:
query Parameters
| dry_run | boolean Default: false If true, validates and previews the upload without persisting any data. The response will be wrapped in a |
Request Body schema: multipart/form-datarequired
| community_classifications required | string <binary> Parquet file containing community classifications of existing observed plots (required). |
| parties | string <binary> Parquet file containing new parties (optional). |
| references | string <binary> Parquet file containing new references (optional). |
| contributors | string <binary> Parquet file containing party contributions to the community classifications (optional). |
Responses
Response Schema: application/json
object | |||||||||||||
| |||||||||||||
object | |||||||||||||
| |||||||||||||
Response samples
- 200
- 403
- 500
{- "counts": {
- "xx": {
- "inserted": 1
}, - "yy": {
- "inserted": 2
}, - "ds": {
- "inserted": 1
}
}, - "resources": {
- "xx": [
- {
- "action": "INSERT",
- "user_xx_code": "my_xx_code",
- "vb_xx_code": "xx.123"
}
], - "yy": [
- {
- "action": "INSERT",
- "user_yy_code": "my_yy_code_1",
- "vb_yy_code": "yy.123"
}
], - "ds": [
- {
- "action": "INSERT",
- "user_ds_code": "upload_dataset_20260325110254",
- "vb_ds_code": "ds.123"
}
]
}
}Operations related to community interpretations. A community interpretation is the specific act of assigning a community concept to a plot observation, perhaps with some asserted fit and confidence level, along with other information. Each community interpretation is done in the context of a specific community classification, and technically a classification activity can yield multiple interpretations (although this is rare in practice).
Get community interpretation
Retrieve a single community interpretation using its ci_code.
path Parameters
| ci_code required | string Example: ci.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||
Array of objects Data records | |||||||||||||||||||
Array
| |||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ci_code": "ci.1",
- "cl_code": "cl.1",
- "cc_code": "cc.1",
- "class_fit": "Reasonable or acceptable answer",
- "class_confidence": "High",
- "comm_authority_rf_code": "rf.1",
- "notes": "no confidence associated with this classification",
- "type": false,
- "nomenclatural_type": false
}
]
}Get community interpretations by cl
Retrieve a paginated collection of community interpretations associated with the specified community classification (using its cl_code).
path Parameters
| cl_code required | string Example: cl.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||
Array of objects Data records | |||||||||||||||||||
Array
| |||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ci_code": "ci.1",
- "cl_code": "cl.1",
- "cc_code": "cc.1",
- "class_fit": "Reasonable or acceptable answer",
- "class_confidence": "High",
- "comm_authority_rf_code": "rf.1",
- "notes": "no confidence associated with this classification",
- "type": false,
- "nomenclatural_type": false
}
]
}Get community interpretations by ob
Retrieve a paginated collection of community interpretations associated with the specified plot observation (using its ob_code).
path Parameters
| ob_code required | string Example: ob.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||
Array of objects Data records | |||||||||||||||||||
Array
| |||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ci_code": "ci.1",
- "cl_code": "cl.1",
- "cc_code": "cc.1",
- "class_fit": "Reasonable or acceptable answer",
- "class_confidence": "High",
- "comm_authority_rf_code": "rf.1",
- "notes": "no confidence associated with this classification",
- "type": false,
- "nomenclatural_type": false
}
]
}Get community interpretations by cc
Retrieve a paginated collection of community interpretations using the specified community concept (using its cc_code).
path Parameters
| cc_code required | string Example: cc.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||
Array of objects Data records | |||||||||||||||||||
Array
| |||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ci_code": "ci.1",
- "cl_code": "cl.1",
- "cc_code": "cc.1",
- "class_fit": "Reasonable or acceptable answer",
- "class_confidence": "High",
- "comm_authority_rf_code": "rf.1",
- "notes": "no confidence associated with this classification",
- "type": false,
- "nomenclatural_type": false
}
]
}Get all community interpretations
Retrieve a paginated collection of all community interpretations recorded in VegBank.
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||
Array of objects Data records | |||||||||||||||||||
Array
| |||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ci_code": "ci.1",
- "cl_code": "cl.1",
- "cc_code": "cc.1",
- "class_fit": "Reasonable or acceptable answer",
- "class_confidence": "High",
- "comm_authority_rf_code": "rf.1",
- "notes": "no confidence associated with this classification",
- "type": false,
- "nomenclatural_type": false
}
]
}Operations related to plant concepts. A plant concept is the assertion of a specific plant taxon through the combination of a name and an associated reference, augmented by status details, any alternative names, and optional relationships (correlations) with other plant concepts.
Get plant concept
Retrieve a single plant concept using its pc_code.
path Parameters
| pc_code required | string Example: pc.1 |
query Parameters
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "pc_code": "pc.1",
- "plant_name": "Acer rubrum",
- "plant_code": "ACRU",
- "plant_description": "Named for the Cahaba River",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "USDA Plants 2002",
- "status_rf_code": "rf.1",
- "status_rf_label": "USDA Plants 2002",
- "obs_count": 17,
- "plant_level": "Genus",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "USDA-NRCS-PLANTS (organization)",
- "plant_party_comments": "present at plants.usda.gov as a higher level taxon",
- "parent_pc_code": "pc.1",
- "parent_name": "Acer"
}
]
}Get plant concepts by py
Retrieve a paginated and sorted collection of the plant concepts with a party perspective (i.e. status record) provided by the specified party (using its py_code), or a subset thereof based on a specified search query.
path Parameters
| py_code required | string Example: py.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "plant_name" "+plant_name" "-plant_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "pc_code": "pc.1",
- "plant_name": "Acer rubrum",
- "plant_code": "ACRU",
- "plant_description": "Named for the Cahaba River",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "USDA Plants 2002",
- "status_rf_code": "rf.1",
- "status_rf_label": "USDA Plants 2002",
- "obs_count": 17,
- "plant_level": "Genus",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "USDA-NRCS-PLANTS (organization)",
- "plant_party_comments": "present at plants.usda.gov as a higher level taxon",
- "parent_pc_code": "pc.1",
- "parent_name": "Acer"
}
]
}Get plant concepts by rf
Retrieve a paginated and sorted collection of the plant concepts associated with a given reference (using its rf_code), or a subset thereof based on a specified search query.
path Parameters
| rf_code required | string Example: rf.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "plant_name" "+plant_name" "-plant_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "pc_code": "pc.1",
- "plant_name": "Acer rubrum",
- "plant_code": "ACRU",
- "plant_description": "Named for the Cahaba River",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "USDA Plants 2002",
- "status_rf_code": "rf.1",
- "status_rf_label": "USDA Plants 2002",
- "obs_count": 17,
- "plant_level": "Genus",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "USDA-NRCS-PLANTS (organization)",
- "plant_party_comments": "present at plants.usda.gov as a higher level taxon",
- "parent_pc_code": "pc.1",
- "parent_name": "Acer"
}
]
}Get plant concepts by to
Retrieve a paginated and sorted collection of the plant concepts applied via interpretation to the specified taxon observation (using its to_code), or a subset thereof based on a specified search query.
path Parameters
| to_code required | string Example: to.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "plant_name" "+plant_name" "-plant_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "pc_code": "pc.1",
- "plant_name": "Acer rubrum",
- "plant_code": "ACRU",
- "plant_description": "Named for the Cahaba River",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "USDA Plants 2002",
- "status_rf_code": "rf.1",
- "status_rf_label": "USDA Plants 2002",
- "obs_count": 17,
- "plant_level": "Genus",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "USDA-NRCS-PLANTS (organization)",
- "plant_party_comments": "present at plants.usda.gov as a higher level taxon",
- "parent_pc_code": "pc.1",
- "parent_name": "Acer"
}
]
}Get plant concepts by ob
Retrieve a paginated and sorted collection of all plant concepts associated with the specified plot observation (using its ob_code), or a subset thereof based on a specified search query.
path Parameters
| ob_code required | string Example: ob.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "plant_name" "+plant_name" "-plant_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "pc_code": "pc.1",
- "plant_name": "Acer rubrum",
- "plant_code": "ACRU",
- "plant_description": "Named for the Cahaba River",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "USDA Plants 2002",
- "status_rf_code": "rf.1",
- "status_rf_label": "USDA Plants 2002",
- "obs_count": 17,
- "plant_level": "Genus",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "USDA-NRCS-PLANTS (organization)",
- "plant_party_comments": "present at plants.usda.gov as a higher level taxon",
- "parent_pc_code": "pc.1",
- "parent_name": "Acer"
}
]
}Get all plant concepts
Retrieve a paginated and sorted collection of plant concepts representing all concepts stored in VegBank, or a subset thereof based on a specified search query.
query Parameters
| search | string Search term used for full-text record retrieval |
| status | string Default: "any" Enum: "any" "current" "accepted" "current_accepted" Status criterion for returned plant concepts and their children:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| sort | string Default: "default" Enum: "default" "+default" "-default" "plant_name" "+plant_name" "-plant_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "pc_code": "pc.1",
- "plant_name": "Acer rubrum",
- "plant_code": "ACRU",
- "plant_description": "Named for the Cahaba River",
- "concept_rf_code": "rf.1",
- "concept_rf_label": "USDA Plants 2002",
- "status_rf_code": "rf.1",
- "status_rf_label": "USDA Plants 2002",
- "obs_count": 17,
- "plant_level": "Genus",
- "status": "accepted",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "current_accepted": true,
- "py_code": "py.1",
- "party_label": "USDA-NRCS-PLANTS (organization)",
- "plant_party_comments": "present at plants.usda.gov as a higher level taxon",
- "parent_pc_code": "pc.1",
- "parent_name": "Acer"
}
]
}Upload plant concepts
Authorizations:
query Parameters
| dry_run | boolean Default: false If true, validates and previews the upload without persisting any data. The response will be wrapped in a |
| deactivation | string Default: "none" Enum: "none" "by_party" Which existing concepts to deactivate in VegBank by setting their status stop date to now:
|
Request Body schema: multipart/form-datarequired
| plant_concepts required | string <binary> Parquet file containing plant concepts as plant names associated with references, along with with status details and taxonomic parents (required). |
| plant_names | string <binary> Parquet file containing plant name usages associated with specific classification systems for new plant concepts (optional). |
| plant_correlations | string <binary> Parquet file defining correlations between plant concepts (optional). |
| parties | string <binary> Parquet file containing new parties (optional). |
| references | string <binary> Parquet file containing new references (optional). |
Responses
Response Schema: application/json
object | |||||||||||||
| |||||||||||||
object | |||||||||||||
| |||||||||||||
Response samples
- 200
- 403
- 500
{- "counts": {
- "xx": {
- "inserted": 1
}, - "yy": {
- "inserted": 2
}, - "ds": {
- "inserted": 1
}
}, - "resources": {
- "xx": [
- {
- "action": "INSERT",
- "user_xx_code": "my_xx_code",
- "vb_xx_code": "xx.123"
}
], - "yy": [
- {
- "action": "INSERT",
- "user_yy_code": "my_yy_code_1",
- "vb_yy_code": "yy.123"
}
], - "ds": [
- {
- "action": "INSERT",
- "user_ds_code": "upload_dataset_20260325110254",
- "vb_ds_code": "ds.123"
}
]
}
}Operations related to taxon observations. A taxon observation is a record of a particular plant taxon in the context of a particular plot observation. Each taxon observation may have additional quantitative details (see Taxon importances) and/or may be interpreted to one or more plant concepts (see Taxon interpretations).
Get taxon observation
Retrieve a single taxon observation using its to_code.
path Parameters
| to_code required | string Example: to.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||
Array of objects Data records | |||||||||||||
Array
| |||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "to_code": "to.1",
- "ob_code": "ob.1",
- "int_curr_pc_code": "pc.1",
- "int_orig_pc_code": "pc.1",
- "taxon_inference_area": 405,
- "rf_code": "rf.1"
}
]
}Get taxon observations by ob
Retrieve a paginated collection of taxon observations associated with the specified plot observation (using its ob_code).
path Parameters
| ob_code required | string Example: ob.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||
Array of objects Data records | |||||||||||||
Array
| |||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "to_code": "to.1",
- "ob_code": "ob.1",
- "int_curr_pc_code": "pc.1",
- "int_orig_pc_code": "pc.1",
- "taxon_inference_area": 405,
- "rf_code": "rf.1"
}
]
}Get taxon observations by pc
Retrieve a paginated collection of taxon observations interpreted to the specified plant concept (using its pc_code).
path Parameters
| pc_code required | string Example: pc.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||
Array of objects Data records | |||||||||||||
Array
| |||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "to_code": "to.1",
- "ob_code": "ob.1",
- "int_curr_pc_code": "pc.1",
- "int_orig_pc_code": "pc.1",
- "taxon_inference_area": 405,
- "rf_code": "rf.1"
}
]
}Get all taxon observations
Retrieve a paginated collection of all taxon observations recorded in VegBank.
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||
Array of objects Data records | |||||||||||||
Array
| |||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "to_code": "to.1",
- "ob_code": "ob.1",
- "int_curr_pc_code": "pc.1",
- "int_orig_pc_code": "pc.1",
- "taxon_inference_area": 405,
- "rf_code": "rf.1"
}
]
}Operations related to strata. A stratum is well-defined partition of a plot in the context of a specific plot observation, following a particular protocol (see Stratum methods). Each taxon importance record may be attached to a specific stratum.
Get stratum
Retrieve a single stratum using its sr_code.
path Parameters
| sr_code required | string Example: sr.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "to_code": "to.1",
- "tm_code": "tm.1",
- "sr_code": "sr.1",
- "sc_code": "sc.1",
- "diameter": 3.75,
- "diameter_accuracy": 1.25,
- "height": 1.185,
- "height_accuracy": 0.185,
- "count": 1,
- "taxon_area": 600
}
]
}Get strata by ob
Retrieve a paginated collection of strata associated with the specified plot observation (using its ob_code).
path Parameters
| ob_code required | string Example: ob.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "to_code": "to.1",
- "tm_code": "tm.1",
- "sr_code": "sr.1",
- "sc_code": "sc.1",
- "diameter": 3.75,
- "diameter_accuracy": 1.25,
- "height": 1.185,
- "height_accuracy": 0.185,
- "count": 1,
- "taxon_area": 600
}
]
}Get strata by to
Retrieve a paginated collection of strata associated with the specified taxon observation (using its to_code).
path Parameters
| to_code required | string Example: to.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "to_code": "to.1",
- "tm_code": "tm.1",
- "sr_code": "sr.1",
- "sc_code": "sc.1",
- "diameter": 3.75,
- "diameter_accuracy": 1.25,
- "height": 1.185,
- "height_accuracy": 0.185,
- "count": 1,
- "taxon_area": 600
}
]
}Get strata by tm
Retrieve a paginated collection of strata associated with the specified taxon importance (using its tm_code).
path Parameters
| tm_code required | string Example: tm.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "to_code": "to.1",
- "tm_code": "tm.1",
- "sr_code": "sr.1",
- "sc_code": "sc.1",
- "diameter": 3.75,
- "diameter_accuracy": 1.25,
- "height": 1.185,
- "height_accuracy": 0.185,
- "count": 1,
- "taxon_area": 600
}
]
}Get all strata
Retrieve a paginated collection of all strata recorded in VegBank.
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "to_code": "to.1",
- "tm_code": "tm.1",
- "sr_code": "sr.1",
- "sc_code": "sc.1",
- "diameter": 3.75,
- "diameter_accuracy": 1.25,
- "height": 1.185,
- "height_accuracy": 0.185,
- "count": 1,
- "taxon_area": 600
}
]
}Operations related to stem counts. A stem count record stores information about the abundance of individual plants (typically tree stems) of a specific size, linked to a Taxon importance record for a given Taxon observation.
Get stem count
Retrieve a single stem count using its sc_code.
path Parameters
| sc_code required | string Example: sc.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "to_code": "to.1",
- "tm_code": "tm.1",
- "sr_code": "sr.1",
- "sc_code": "sc.1",
- "diameter": 3.75,
- "diameter_accuracy": 1.25,
- "height": 1.185,
- "height_accuracy": 0.185,
- "count": 1,
- "taxon_area": 600
}
]
}Get stem counts by ob
Retrieve a paginated collection of stem counts associated with the specified plot observation (using its ob_code).
path Parameters
| ob_code required | string Example: ob.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "to_code": "to.1",
- "tm_code": "tm.1",
- "sr_code": "sr.1",
- "sc_code": "sc.1",
- "diameter": 3.75,
- "diameter_accuracy": 1.25,
- "height": 1.185,
- "height_accuracy": 0.185,
- "count": 1,
- "taxon_area": 600
}
]
}Get stem counts by to
Retrieve a paginated collection of stem counts associated with the specified taxon observation (using its to_code).
path Parameters
| to_code required | string Example: to.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "to_code": "to.1",
- "tm_code": "tm.1",
- "sr_code": "sr.1",
- "sc_code": "sc.1",
- "diameter": 3.75,
- "diameter_accuracy": 1.25,
- "height": 1.185,
- "height_accuracy": 0.185,
- "count": 1,
- "taxon_area": 600
}
]
}Get stem counts by tm
Retrieve a paginated collection of stem counts associated with the specified taxon importance (using its tm_code).
path Parameters
| tm_code required | string Example: tm.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "to_code": "to.1",
- "tm_code": "tm.1",
- "sr_code": "sr.1",
- "sc_code": "sc.1",
- "diameter": 3.75,
- "diameter_accuracy": 1.25,
- "height": 1.185,
- "height_accuracy": 0.185,
- "count": 1,
- "taxon_area": 600
}
]
}Get all stem counts
Retrieve a paginated collection of all stem counts recorded in VegBank.
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ob_code": "ob.1",
- "to_code": "to.1",
- "tm_code": "tm.1",
- "sr_code": "sr.1",
- "sc_code": "sc.1",
- "diameter": 3.75,
- "diameter_accuracy": 1.25,
- "height": 1.185,
- "height_accuracy": 0.185,
- "count": 1,
- "taxon_area": 600
}
]
}Operations related to taxon importances. A taxon importance record quantifies a taxon observation by recording plant cover, basal area, and/or biomass, either within a specific stratum (see Strata) or for the plot observation as a whole.
Get taxon importance
Retrieve a single taxon importance using its tm_code.
path Parameters
| tm_code required | string Example: tm.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "tm_code": "tm.1",
- "to_code": "to.1",
- "ob_code": "ob.1",
- "sr_code": "sr.1",
- "cover": 17.5,
- "cover_code": "6",
- "basal_area": 13.141,
- "biomass": 813,
- "inference_area": 1000,
- "stratum_base": 3,
- "stratum_height": 25
}
]
}Get taxon importances by ob
Retrieve a paginated collection of taxon importances associated with the specified plot observation (using its ob_code).
path Parameters
| ob_code required | string Example: ob.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "tm_code": "tm.1",
- "to_code": "to.1",
- "ob_code": "ob.1",
- "sr_code": "sr.1",
- "cover": 17.5,
- "cover_code": "6",
- "basal_area": 13.141,
- "biomass": 813,
- "inference_area": 1000,
- "stratum_base": 3,
- "stratum_height": 25
}
]
}Get taxon importances by pc
Retrieve a paginated collection of taxon importances interpreted to the specified plant concept (using its pc_code).
path Parameters
| pc_code required | string Example: pc.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "tm_code": "tm.1",
- "to_code": "to.1",
- "ob_code": "ob.1",
- "sr_code": "sr.1",
- "cover": 17.5,
- "cover_code": "6",
- "basal_area": 13.141,
- "biomass": 813,
- "inference_area": 1000,
- "stratum_base": 3,
- "stratum_height": 25
}
]
}Get taxon importances by to
Retrieve a paginated collection of taxon importances associated with the specified taxon observation (using its to_code).
path Parameters
| to_code required | string Example: to.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "tm_code": "tm.1",
- "to_code": "to.1",
- "ob_code": "ob.1",
- "sr_code": "sr.1",
- "cover": 17.5,
- "cover_code": "6",
- "basal_area": 13.141,
- "biomass": 813,
- "inference_area": 1000,
- "stratum_base": 3,
- "stratum_height": 25
}
]
}Get all taxon importances
Retrieve a paginated collection of all taxon importances recorded in VegBank.
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||
Array
| |||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "tm_code": "tm.1",
- "to_code": "to.1",
- "ob_code": "ob.1",
- "sr_code": "sr.1",
- "cover": 17.5,
- "cover_code": "6",
- "basal_area": 13.141,
- "biomass": 813,
- "inference_area": 1000,
- "stratum_base": 3,
- "stratum_height": 25
}
]
}Operations related to taxon interpretations. A taxon interpretation is the specific act of assigning a plant concept to a taxon observation belonging to a plot observation, perhaps with some asserted fit and confidence level, along with other information such as the party who made the interpretation.
Get taxon interpretation
Retrieve a single taxon interpretation using its ti_code.
path Parameters
| ti_code required | string Example: ti.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ti_code": "ti.1",
- "to_code": "to.1",
- "pc_code": "pc.1",
- "interpretation_date": "2006-05-30",
- "interpretation_type": "Author",
- "py_code": "py.1",
- "rf_code": "rf.1",
- "taxon_fit": "Reasonable or acceptable answer",
- "taxon_confidence": "High",
- "collection_number": "091907F",
- "group_type": "union",
- "notes": "Identified from specimen",
- "is_orig": true,
- "is_curr": true
}
]
}Get taxon interpretations by pc
Retrieve a paginated collection of taxon interpretations using the specified plant concept (using its pc_code).
path Parameters
| pc_code required | string Example: pc.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ti_code": "ti.1",
- "to_code": "to.1",
- "pc_code": "pc.1",
- "interpretation_date": "2006-05-30",
- "interpretation_type": "Author",
- "py_code": "py.1",
- "rf_code": "rf.1",
- "taxon_fit": "Reasonable or acceptable answer",
- "taxon_confidence": "High",
- "collection_number": "091907F",
- "group_type": "union",
- "notes": "Identified from specimen",
- "is_orig": true,
- "is_curr": true
}
]
}Get taxon interpretations by ob
Retrieve a paginated collection of taxon interpretations applied to taxa observed in the specified plot observation (using its ob_code).
path Parameters
| ob_code required | string Example: ob.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ti_code": "ti.1",
- "to_code": "to.1",
- "pc_code": "pc.1",
- "interpretation_date": "2006-05-30",
- "interpretation_type": "Author",
- "py_code": "py.1",
- "rf_code": "rf.1",
- "taxon_fit": "Reasonable or acceptable answer",
- "taxon_confidence": "High",
- "collection_number": "091907F",
- "group_type": "union",
- "notes": "Identified from specimen",
- "is_orig": true,
- "is_curr": true
}
]
}Get taxon interpretations by to
Retrieve a paginated collection of taxon interpretations for the specified taxon observation (using its to_code).
path Parameters
| to_code required | string Example: to.1 |
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ti_code": "ti.1",
- "to_code": "to.1",
- "pc_code": "pc.1",
- "interpretation_date": "2006-05-30",
- "interpretation_type": "Author",
- "py_code": "py.1",
- "rf_code": "rf.1",
- "taxon_fit": "Reasonable or acceptable answer",
- "taxon_confidence": "High",
- "collection_number": "091907F",
- "group_type": "union",
- "notes": "Identified from specimen",
- "is_orig": true,
- "is_curr": true
}
]
}Get all taxon interpretations
Retrieve a paginated collection of all taxon interpretations recorded in VegBank.
query Parameters
| detail | string Default: "full" Enum: "minimal" "full" Level of detail for the response:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||||||||||||||||||
Array of objects Data records | |||||||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "ti_code": "ti.1",
- "to_code": "to.1",
- "pc_code": "pc.1",
- "interpretation_date": "2006-05-30",
- "interpretation_type": "Author",
- "py_code": "py.1",
- "rf_code": "rf.1",
- "taxon_fit": "Reasonable or acceptable answer",
- "taxon_confidence": "High",
- "collection_number": "091907F",
- "group_type": "union",
- "notes": "Identified from specimen",
- "is_orig": true,
- "is_curr": true
}
]
}Upload taxon interpretations
Authorizations:
query Parameters
| dry_run | boolean Default: false If true, validates and previews the upload without persisting any data. The response will be wrapped in a |
Request Body schema: multipart/form-datarequired
| taxon_interpretations required | string <binary> Parquet file containing taxon interpretations of plants observed within existing plot observations (required). |
| parties | string <binary> Parquet file containing new parties (optional). |
| references | string <binary> Parquet file containing new references (optional). |
Responses
Response Schema: application/json
object | |||||||||||||
| |||||||||||||
object | |||||||||||||
| |||||||||||||
Response samples
- 200
- 403
- 500
{- "counts": {
- "xx": {
- "inserted": 1
}, - "yy": {
- "inserted": 2
}, - "ds": {
- "inserted": 1
}
}, - "resources": {
- "xx": [
- {
- "action": "INSERT",
- "user_xx_code": "my_xx_code",
- "vb_xx_code": "xx.123"
}
], - "yy": [
- {
- "action": "INSERT",
- "user_yy_code": "my_yy_code_1",
- "vb_yy_code": "yy.123"
}
], - "ds": [
- {
- "action": "INSERT",
- "user_ds_code": "upload_dataset_20260325110254",
- "vb_ds_code": "ds.123"
}
]
}
}Operations related to cover methods. A cover method is a particular protocol for recording the percent cover occupied by a plant taxon observed in a plot, often by specifying and defining one or more ordered categorical cover classes (i.e., cover indexes).
Get cover method
Retrieve a single cover method using its cm_code.
path Parameters
| cm_code required | string Example: cm.1 |
query Parameters
| with_nested | boolean Default: false Whether to include nested fields in the response |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||
Array of objects Data records | |||||||||||
Array
| |||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cm_code": "cm.1",
- "cover_type": "Braun-Blanquet",
- "cover_estimation_method": "Canopy cover",
- "rf_code": "rf.1",
- "rf_label": "TurboVeg1.98a"
}
]
}Get all cover methods
Retrieve a paginated collection of all cover methods recorded in VegBank.
query Parameters
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||
Array of objects Data records | |||||||||||
Array
| |||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "cm_code": "cm.1",
- "cover_type": "Braun-Blanquet",
- "cover_estimation_method": "Canopy cover",
- "rf_code": "rf.1",
- "rf_label": "TurboVeg1.98a"
}
]
}Upload cover methods
Authorizations:
query Parameters
| dry_run | boolean Default: false If true, validates and previews the upload without persisting any data. The response will be wrapped in a |
Request Body schema: multipart/form-datarequired
| cover_methods required | string <binary> Parquet file containing cover methods and their associated component cover indexes (required). |
| references | string <binary> Parquet file containing new references (optional). |
Responses
Response Schema: application/json
object | |||||||||||||
| |||||||||||||
object | |||||||||||||
| |||||||||||||
Response samples
- 200
- 403
- 500
{- "counts": {
- "xx": {
- "inserted": 1
}, - "yy": {
- "inserted": 2
}, - "ds": {
- "inserted": 1
}
}, - "resources": {
- "xx": [
- {
- "action": "INSERT",
- "user_xx_code": "my_xx_code",
- "vb_xx_code": "xx.123"
}
], - "yy": [
- {
- "action": "INSERT",
- "user_yy_code": "my_yy_code_1",
- "vb_yy_code": "yy.123"
}
], - "ds": [
- {
- "action": "INSERT",
- "user_ds_code": "upload_dataset_20260325110254",
- "vb_ds_code": "ds.123"
}
]
}
}Operations related to stratum methods. A stratum method forms a sampling protocol by defining one or more strata, each of which is a logical subspace of a plot, often (but not always) associated with a vertical partitioning of space aligned with a plant growth forms.
Get stratum method
Retrieve a single stratum method using its sm_code.
path Parameters
| sm_code required | string Example: sm.1 |
query Parameters
| with_nested | boolean Default: false Whether to include nested fields in the response |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||
Array of objects Data records | |||||||||||||
Array
| |||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "sm_code": "sm.1",
- "stratum_method_name": "TurboVeg",
- "stratum_method_description": "Standard strata used in the TurboVeg application",
- "stratum_assignment": "predominant stratum",
- "rf_code": "rf.1",
- "rf_label": "TurboVeg1.98a"
}
]
}Get all stratum methods
Retrieve a paginated collection of all stratum methods recorded in VegBank.
query Parameters
| with_nested | boolean Default: false Whether to include nested fields in the response |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| count | integer Total matching record count | ||||||||||||
Array of objects Data records | |||||||||||||
Array
| |||||||||||||
Response samples
- 200
- 400
{- "count": 115000,
- "data": [
- {
- "sm_code": "sm.1",
- "stratum_method_name": "TurboVeg",
- "stratum_method_description": "Standard strata used in the TurboVeg application",
- "stratum_assignment": "predominant stratum",
- "rf_code": "rf.1",
- "rf_label": "TurboVeg1.98a"
}
]
}Upload stratum methods
Authorizations:
query Parameters
| dry_run | boolean Default: false If true, validates and previews the upload without persisting any data. The response will be wrapped in a |
Request Body schema: multipart/form-datarequired
| stratum_methods required | string <binary> Parquet file containing stratum methods and their associated component stratum types (required). |
| references | string <binary> Parquet file containing new references (optional). |
Responses
Response Schema: application/json
object | |||||||||||||
| |||||||||||||
object | |||||||||||||
| |||||||||||||
Response samples
- 200
- 403
- 500
{- "counts": {
- "xx": {
- "inserted": 1
}, - "yy": {
- "inserted": 2
}, - "ds": {
- "inserted": 1
}
}, - "resources": {
- "xx": [
- {
- "action": "INSERT",
- "user_xx_code": "my_xx_code",
- "vb_xx_code": "xx.123"
}
], - "yy": [
- {
- "action": "INSERT",
- "user_yy_code": "my_yy_code_1",
- "vb_yy_code": "yy.123"
}
], - "ds": [
- {
- "action": "INSERT",
- "user_ds_code": "upload_dataset_20260325110254",
- "vb_ds_code": "ds.123"
}
]
}
}Operations related to parties. A party is a person or organization connected in some way to resources stored in VegBank, such as contributing to data collection or the interpretation of a plot.
Get party
Retrieve a single party using its py_code.
path Parameters
| py_code required | string Example: py.1 |
query Parameters
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| py_code | string VegBank party identifier |
| party_label | string Name/label for the party |
| salutation | string Salutation used in addressing an individual with a particular title |
| given_name | string All names, except the surname, of the individual associated with the resource. Possible usages include: first name and middle name, first name and middle initials, first name, etc. |
| middle_name | string Middle name or initial, if any |
| surname | string Name shared in common to identify the members of a family, as distinguished the given name |
| organization_name | string Full name of the organization, which may be the party itself if this is an organization-type party record, or else is the organization that the party is associated with if this is a person-type party record |
| contact_instructions | string Instructions for contacting a party |
| obs_count | integer Number of plot observations associated with this entity |
Response samples
- 200
- 400
{- "py_code": "py.1",
- "party_label": "NatureServe (organization)",
- "salutation": "Dr.",
- "given_name": "Jo R.",
- "middle_name": "R.",
- "surname": "Smith",
- "organization_name": "NatureServe",
- "contact_instructions": "contact the contributor at specified email",
- "obs_count": 17
}Get parties by ob
Retrieve a paginated and sorted collection of parties associated with the specified plot observation (using its ob_code), or a subset thereof based on a specified search query.
path Parameters
| ob_code required | string Example: ob.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| sort | string Default: "default" Enum: "default" "+default" "-default" "surname" "+surname" "-surname" "organization_name" "+organization_name" "-organization_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| py_code | string VegBank party identifier |
| party_label | string Name/label for the party |
| salutation | string Salutation used in addressing an individual with a particular title |
| given_name | string All names, except the surname, of the individual associated with the resource. Possible usages include: first name and middle name, first name and middle initials, first name, etc. |
| middle_name | string Middle name or initial, if any |
| surname | string Name shared in common to identify the members of a family, as distinguished the given name |
| organization_name | string Full name of the organization, which may be the party itself if this is an organization-type party record, or else is the organization that the party is associated with if this is a person-type party record |
| contact_instructions | string Instructions for contacting a party |
| obs_count | integer Number of plot observations associated with this entity |
Response samples
- 200
- 400
{- "py_code": "py.1",
- "party_label": "NatureServe (organization)",
- "salutation": "Dr.",
- "given_name": "Jo R.",
- "middle_name": "R.",
- "surname": "Smith",
- "organization_name": "NatureServe",
- "contact_instructions": "contact the contributor at specified email",
- "obs_count": 17
}Get parties by cl
Retrieve a paginated and sorted collection of parties associated with the specified community classification (using its cl_code), or a subset thereof based on a specified search query.
path Parameters
| cl_code required | string Example: cl.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| sort | string Default: "default" Enum: "default" "+default" "-default" "surname" "+surname" "-surname" "organization_name" "+organization_name" "-organization_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| py_code | string VegBank party identifier |
| party_label | string Name/label for the party |
| salutation | string Salutation used in addressing an individual with a particular title |
| given_name | string All names, except the surname, of the individual associated with the resource. Possible usages include: first name and middle name, first name and middle initials, first name, etc. |
| middle_name | string Middle name or initial, if any |
| surname | string Name shared in common to identify the members of a family, as distinguished the given name |
| organization_name | string Full name of the organization, which may be the party itself if this is an organization-type party record, or else is the organization that the party is associated with if this is a person-type party record |
| contact_instructions | string Instructions for contacting a party |
| obs_count | integer Number of plot observations associated with this entity |
Response samples
- 200
- 400
{- "py_code": "py.1",
- "party_label": "NatureServe (organization)",
- "salutation": "Dr.",
- "given_name": "Jo R.",
- "middle_name": "R.",
- "surname": "Smith",
- "organization_name": "NatureServe",
- "contact_instructions": "contact the contributor at specified email",
- "obs_count": 17
}Get parties by pj
Retrieve a paginated and sorted collection of parties associated with the specified project (using its pj_code), or a subset thereof based on a specified search query.
path Parameters
| pj_code required | string Example: pj.1 |
query Parameters
| search | string Search term used for full-text record retrieval |
| sort | string Default: "default" Enum: "default" "+default" "-default" "surname" "+surname" "-surname" "organization_name" "+organization_name" "-organization_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| py_code | string VegBank party identifier |
| party_label | string Name/label for the party |
| salutation | string Salutation used in addressing an individual with a particular title |
| given_name | string All names, except the surname, of the individual associated with the resource. Possible usages include: first name and middle name, first name and middle initials, first name, etc. |
| middle_name | string Middle name or initial, if any |
| surname | string Name shared in common to identify the members of a family, as distinguished the given name |
| organization_name | string Full name of the organization, which may be the party itself if this is an organization-type party record, or else is the organization that the party is associated with if this is a person-type party record |
| contact_instructions | string Instructions for contacting a party |
| obs_count | integer Number of plot observations associated with this entity |
Response samples
- 200
- 400
{- "py_code": "py.1",
- "party_label": "NatureServe (organization)",
- "salutation": "Dr.",
- "given_name": "Jo R.",
- "middle_name": "R.",
- "surname": "Smith",
- "organization_name": "NatureServe",
- "contact_instructions": "contact the contributor at specified email",
- "obs_count": 17
}Get all parties
Retrieve a paginated collection of all parties recorded in VegBank.
query Parameters
| search | string Search term used for full-text record retrieval |
| sort | string Default: "default" Enum: "default" "+default" "-default" "surname" "+surname" "-surname" "organization_name" "+organization_name" "-organization_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| py_code | string VegBank party identifier |
| party_label | string Name/label for the party |
| salutation | string Salutation used in addressing an individual with a particular title |
| given_name | string All names, except the surname, of the individual associated with the resource. Possible usages include: first name and middle name, first name and middle initials, first name, etc. |
| middle_name | string Middle name or initial, if any |
| surname | string Name shared in common to identify the members of a family, as distinguished the given name |
| organization_name | string Full name of the organization, which may be the party itself if this is an organization-type party record, or else is the organization that the party is associated with if this is a person-type party record |
| contact_instructions | string Instructions for contacting a party |
| obs_count | integer Number of plot observations associated with this entity |
Response samples
- 200
- 400
{- "py_code": "py.1",
- "party_label": "NatureServe (organization)",
- "salutation": "Dr.",
- "given_name": "Jo R.",
- "middle_name": "R.",
- "surname": "Smith",
- "organization_name": "NatureServe",
- "contact_instructions": "contact the contributor at specified email",
- "obs_count": 17
}Get role
Retrieve a single role using its ar_code.
path Parameters
| ar_code required | string Example: ar.1 |
query Parameters
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| ar_code | string VegBank role identifier |
| name | string Role name/label |
| description | string Role description |
Response samples
- 200
- 400
{- "ar_code": "ar.56",
- "name": "Data aggregator",
- "description": "Person who aggregates and directs data from one place or platform to another"
}Get all roles
Retrieve a paginated collection of all roles recorded in VegBank.
query Parameters
| search | string Search term used for full-text record retrieval |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| ar_code | string VegBank role identifier |
| name | string Role name/label |
| description | string Role description |
Response samples
- 200
- 400
{- "ar_code": "ar.56",
- "name": "Data aggregator",
- "description": "Person who aggregates and directs data from one place or platform to another"
}Operations related to projects. A project is a named activity established to collect vegetation plot data. Every plot observation belongs to exactly one project.
Get project
Retrieve a single project using its pj_code.
path Parameters
| pj_code required | string Example: pj.1 |
query Parameters
| with_nested | boolean Default: false Whether to include nested fields in the response |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| pj_code | string VegBank project identifier |
| project_name | string Project name as defined by the principal investigator |
| project_description | string Short description of the project including the original purpose for conducting the project |
| start_date | string <date> Project start date |
| stop_date | string <date> Project stop date |
| obs_count | integer Number of plot observations associated with this entity |
| last_plot_added_date | string <date> Date a plot observation was last added to this project |
Response samples
- 200
- 400
{- "pj_code": "pj.1",
- "project_name": "Pawnee Grassland Classification",
- "project_description": "Classification of the Pawnee National Grassland",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "obs_count": 17,
- "last_plot_added_date": "2006-05-30"
}Get all projects
Retrieve a paginated collection of all projects recorded in VegBank.
query Parameters
| search | string Search term used for full-text record retrieval |
| sort | string Default: "default" Enum: "default" "+default" "-default" "project_name" "+project_name" "-project_name" "obs_count" "+obs_count" "-obs_count" Example: sort=-obs_count Sort order for results. Prefix with Available sort fields:
Examples:
|
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| pj_code | string VegBank project identifier |
| project_name | string Project name as defined by the principal investigator |
| project_description | string Short description of the project including the original purpose for conducting the project |
| start_date | string <date> Project start date |
| stop_date | string <date> Project stop date |
| obs_count | integer Number of plot observations associated with this entity |
| last_plot_added_date | string <date> Date a plot observation was last added to this project |
Response samples
- 200
- 400
{- "pj_code": "pj.1",
- "project_name": "Pawnee Grassland Classification",
- "project_description": "Classification of the Pawnee National Grassland",
- "start_date": "2006-05-30",
- "stop_date": "2006-05-30",
- "obs_count": 17,
- "last_plot_added_date": "2006-05-30"
}Operations related to references. A reference is a specific information source (e.g., publication, book, website, etc) cited with respect to some resource or activity in VegBank.
Get reference
Retrieve a single reference using its rf_code.
path Parameters
| rf_code required | string Example: rf.1 |
query Parameters
| with_nested | boolean Default: false Whether to include nested fields in the response |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| rf_code | string VegBank reference identifier |
| rf_label | string Label for the reference |
| short_name | string Concise or abbreviated name that describes the resource being documented |
| full_citation | string Full text of the reference citation |
| reference_type | string Type of reference |
| title | string Formal title given to the work by its author or publisher, providing a description of the resource sufficient to differentiate it from other similar resources |
| publication_date | string <date> Date that the resource was published |
| total_pages | integer Total number of pages in the resource being described |
| publisher | string Organization that physically put together the report and publishes it |
| publication_place | string Location where the work was published |
| degree | string Name or degree level for which the thesis was completed |
| isbn | string The ISBN, or International Standard Book Number that has been assigned to this literature resource |
| url | string URL (Uniform Resource Locator) identifying where the resource and/or additional information about it is (or was) available |
| doi | string DOI (Digital Object Identifier) serving as the persistent identifier for the resource |
| journal | string Name of the journal, magazine, etc. in which the article was published |
Response samples
- 200
- 400
{- "rf_code": "rf.1",
- "rf_label": "Peet Dissertation (1975)",
- "short_name": "Anderson, L. et al. 1990.",
- "full_citation": "Anderson, L. et al. 1990. Bryologist 93: 448-499.",
- "reference_type": "Report",
- "title": "The Biology of Lichens",
- "publication_date": "2011-08-25",
- "total_pages": 17,
- "publisher": "NCU Herbarium",
- "publication_place": "Chapel Hill, NC, USA",
- "degree": "PhD",
- "isbn": "978-1-889878-38-6",
- "doi": "10.1000/182",
- "journal": "Regnum Vegetabile"
}Get all references
Retrieve a paginated collection of all references recorded in VegBank.
query Parameters
| search | string Search term used for full-text record retrieval |
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| rf_code | string VegBank reference identifier |
| rf_label | string Label for the reference |
| short_name | string Concise or abbreviated name that describes the resource being documented |
| full_citation | string Full text of the reference citation |
| reference_type | string Type of reference |
| title | string Formal title given to the work by its author or publisher, providing a description of the resource sufficient to differentiate it from other similar resources |
| publication_date | string <date> Date that the resource was published |
| total_pages | integer Total number of pages in the resource being described |
| publisher | string Organization that physically put together the report and publishes it |
| publication_place | string Location where the work was published |
| degree | string Name or degree level for which the thesis was completed |
| isbn | string The ISBN, or International Standard Book Number that has been assigned to this literature resource |
| url | string URL (Uniform Resource Locator) identifying where the resource and/or additional information about it is (or was) available |
| doi | string DOI (Digital Object Identifier) serving as the persistent identifier for the resource |
| journal | string Name of the journal, magazine, etc. in which the article was published |
Response samples
- 200
- 400
{- "rf_code": "rf.1",
- "rf_label": "Peet Dissertation (1975)",
- "short_name": "Anderson, L. et al. 1990.",
- "full_citation": "Anderson, L. et al. 1990. Bryologist 93: 448-499.",
- "reference_type": "Report",
- "title": "The Biology of Lichens",
- "publication_date": "2011-08-25",
- "total_pages": 17,
- "publisher": "NCU Herbarium",
- "publication_place": "Chapel Hill, NC, USA",
- "degree": "PhD",
- "isbn": "978-1-889878-38-6",
- "doi": "10.1000/182",
- "journal": "Regnum Vegetabile"
}Operations related to named places. A named place is a specific geographic location or feature stored in VegBank. Although not currently used for new data, older plots in VegBank can be associated with one or more named places.
Get named place
Retrieve a single named place using its np_code.
path Parameters
| np_code required | string Example: np.1 |
query Parameters
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| np_code | string VegBank named place identifier |
| system | string Name of the system of names. The system 'Geographic Name' is an open list, whereas the other systems are generally closed lists defined by a known system with an external authority (e.g., USGSQuad, Continent, Country, State, County, HUC, and Ecoregion) |
| name | string The name of a place in or at which a plot is located. |
| description | string Description of a named place. For US county names, this field identifies the containing state. |
| code | string Optional code for location identification |
| owner | string Designated location owner |
| rf_label | string Label for the observation reference |
| obs_count | integer Number of plot observations associated with this named place |
Response samples
- 200
- 400
{- "np_code": "np.1",
- "system": "county",
- "name": "Zion NP",
- "description": "Zion National Park",
- "code": "ZION",
- "owner": "US NPS",
- "rf_label": "US NPS place names",
- "obs_count": 8
}Get all named places
Retrieve a paginated collection of all named places recorded in VegBank.
query Parameters
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| np_code | string VegBank named place identifier |
| system | string Name of the system of names. The system 'Geographic Name' is an open list, whereas the other systems are generally closed lists defined by a known system with an external authority (e.g., USGSQuad, Continent, Country, State, County, HUC, and Ecoregion) |
| name | string The name of a place in or at which a plot is located. |
| description | string Description of a named place. For US county names, this field identifies the containing state. |
| code | string Optional code for location identification |
| owner | string Designated location owner |
| rf_label | string Label for the observation reference |
| obs_count | integer Number of plot observations associated with this named place |
Response samples
- 200
- 400
{- "np_code": "np.1",
- "system": "county",
- "name": "Zion NP",
- "description": "Zion National Park",
- "code": "ZION",
- "owner": "US NPS",
- "rf_label": "US NPS place names",
- "obs_count": 8
}Operations related to VegBank datasets. A dataset is an arbitrary user-defined collection of plot observations, typically defined for some specific analysis or similar activity, and registered in VegBank with a stable identifier that can be used for citing and sharing this defined collection.
Get a user-defined dataset entry
Retrieve the catalog entry for a single public user-defined dataset using its ds_code.
path Parameters
| ds_code required | string Example: ds.1 |
query Parameters
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| ds_code | string VegBank dataset identifier |
| accession_code | string Accession code identifying older VegBank datasets |
| start | string <date> Dataset creation date |
| stop | string <date> User-defined dataset expiration date |
| name | string Dataset name |
| description | string Dataset description |
| type | string Dataset type |
| owner_label | string Name of the dataset creator/owner |
| owner_email | string Email address of dataset creator/owner |
| py_code | string VegBank party identifier for the dataset creator/owner |
| obs_count | integer Number of plot observations associated with this dataset |
Response samples
- 200
- 400
{- "ds_code": "ds.1",
- "accession_code": "VB.ds.196904.27074B058D5FD45",
- "start": "2006-05-30",
- "stop": "2006-05-30",
- "name": "Example dataset 1",
- "description": "Some plots in North Carolina",
- "type": "normal",
- "owner_label": "Mary Smith",
- "owner_email": "msmith@university.edu",
- "py_code": "py.1",
- "obs_count": 17
}Get all user-defined datasets entries
Retrieve a paginated catalog of all public user-defined datasets registered in VegBank.
query Parameters
| limit | integer >= 0 Default: 1000 Maximum number of records to return |
| offset | integer >= 0 Default: 0 Number of records to skip before starting to return records |
| create_parquet | boolean Default: false If true, return data payload in binary Parquet format |
Responses
Response Schema:
| ds_code | string VegBank dataset identifier |
| accession_code | string Accession code identifying older VegBank datasets |
| start | string <date> Dataset creation date |
| stop | string <date> User-defined dataset expiration date |
| name | string Dataset name |
| description | string Dataset description |
| type | string Dataset type |
| owner_label | string Name of the dataset creator/owner |
| owner_email | string Email address of dataset creator/owner |
| py_code | string VegBank party identifier for the dataset creator/owner |
| obs_count | integer Number of plot observations associated with this dataset |
Response samples
- 200
- 400
{- "ds_code": "ds.1",
- "accession_code": "VB.ds.196904.27074B058D5FD45",
- "start": "2006-05-30",
- "stop": "2006-05-30",
- "name": "Example dataset 1",
- "description": "Some plots in North Carolina",
- "type": "normal",
- "owner_label": "Mary Smith",
- "owner_email": "msmith@university.edu",
- "py_code": "py.1",
- "obs_count": 17
}Create a user dataset
Authorizations:
query Parameters
| dry_run | boolean Default: false If true, validates and previews the upload without persisting any data. The response will be wrapped in a |
Request Body schema: application/jsonrequired
| name required | string Display name for the dataset. | ||
| description | string Optional human-readable description of the dataset. | ||
required | object | ||
| |||
Responses
Response Schema: application/json
object | |||||||||||||
| |||||||||||||
object | |||||||||||||
| |||||||||||||
Request samples
- Payload
{- "name": "Test Dataset 001",
- "description": "A test dataset containing 3 observations.",
- "data": {
- "observation": [
- "ob.2948",
- "ob.2949",
- "ob.2950"
]
}
}Response samples
- 200
- 403
- 500
{- "counts": {
- "xx": {
- "inserted": 1
}, - "yy": {
- "inserted": 2
}, - "ds": {
- "inserted": 1
}
}, - "resources": {
- "xx": [
- {
- "action": "INSERT",
- "user_xx_code": "my_xx_code",
- "vb_xx_code": "xx.123"
}
], - "yy": [
- {
- "action": "INSERT",
- "user_yy_code": "my_yy_code_1",
- "vb_yy_code": "yy.123"
}
], - "ds": [
- {
- "action": "INSERT",
- "user_ds_code": "upload_dataset_20260325110254",
- "vb_ds_code": "ds.123"
}
]
}
}Get basic VegBank database stats
Retrieve an assortment of count statistics indicating what's in VegBank.
query Parameters
| limit | integer >= 0 Default: 5 Maximum number of records to return in Top N counts |
Responses
Response Schema: application/json
Array of objects Database-wide count metrics | |||||||||
Array
| |||||||||
Array of objects Most recent N projects by plot upload date | |||||||||
Array
| |||||||||
Array of objects Top N community concepts by observation count | |||||||||
Array
| |||||||||
Array of objects Top N plant concepts by observation count | |||||||||
Array
| |||||||||
Array of objects Top N projects by observation count | |||||||||
Array
| |||||||||
Array of objects Top N contributors by observation count | |||||||||
Array
| |||||||||
Array of objects Top N named places by observation count | |||||||||
Array
| |||||||||
Response samples
- 200
- 400
{- "core_counts": [
- {
- "name": "observations",
- "count": 115246
}
], - "latest_n_projects": [
- {
- "name": "California Vegetation Survey",
- "pj_code": "pj.1",
- "last_date_added": "2026-03-30",
- "count": 3400
}
], - "top_n_community_concepts": [
- {
- "name": "California Annual Grassland",
- "cc_code": "cc.1",
- "count": 670
}
], - "top_n_plant_concepts": [
- {
- "name": "Quercus agrifolia",
- "pc_code": "pc.1",
- "count": 890
}
], - "top_n_projects": [
- {
- "name": "California Vegetation Survey",
- "pj_code": "pj.1",
- "count": 3400
}
], - "top_n_contributors": [
- {
- "name": "John Smith",
- "py_code": "py.1",
- "count": 1250
}
], - "top_n_named_places": [
- {
- "name": "California",
- "np_code": "np.1",
- "count": 5432
}
]
}