Sample Endpoints

Note

The examples below use API endpoints from the live COPO website.

To use the demo website instead, replace https://copo-project.org/api/ with https://demo.copo-project.org/api/ in the URLs.

Tip

• To view details of the endpoint, click the Show endpoint details button.

• Then, inside that section, click the Show API query parameters button to see input parameter details.

• By default, the API returns results in JSON format and uses the Tree of Life (ToL) standard. You do not need to specify these unless you want to override them.

  To explicitly include them in the API URL:

  • Use ?return_type=json or ?standard=tol if there are no other query parameters.

  • Use &return_type=json or &standard=tol if the URL already includes other parameters.

---

Fetch Sample Records by Project

Show endpoint details

Show API query parameters

Tip

Filters are applied by appending them as query parameters in the API URL. See the Usage and Example sections for details.

• project (required): The name of the project [1]. Multiple projects can be provided as a comma (,) separated list in this endpoint. Commas (,) are represented as %2C URL-encoded values in the API URL.

• return_type (optional): Output format for the results. Options include json (default) and csv

Usage

• Please include at least the project parameter value in the API URL to retrieve a list of copo_id [5] values for sample records within that project. Replace {project} with the desired project name.

• To apply filters, append them to the API URL as follows: sample/{project}?return_type=<return_type>. Replace {project} and <return_type> with the desired values. See the example section below for full usage with optional filters.

• After having retrieved the copo_id values, you can use them to retrieve full sample information using the Fetch Sample Records by COPO ID endpoint.

Web Browser

https://copo-project.org/api/sample/{project}

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/{project}" -H "accept: application/json"

Example

To retrieve a list of copo_id values for sample records in the ASG, DTOL and ERGA projects in JSON format, use the following URL.

Web Browser

https://copo-project.org/api/sample/asg%2Cdtol%2Cerga

Command Line (curl)

$ curl -X GET "https://copo-
project.org/api/sample/asg%2Cdtol%2Cerga" -H  "accept:
application/json"

Fetch Sample Records by Associated Project Type

Show endpoint details

Show API query parameters

Tip

Filters are applied by appending them as query parameters in the API URL. See the Usage and Example sections for details.

• values (required): The subproject or secondary project to filter the results. [4]

• standard (optional): The standard to query the endpoint. Options include: tol (default), dwc, ena and mixs

• return_type (optional): Output format for the results. Options include json (default) and csv

Usage

• Please include at least the values parameter value in the API URL to retrieve sample records given associated project type(s) in COPO.

• To apply filters, append them to the API URL as follows: sample/associated_tol_project?values=<values>&standard=<standard>&retur n_type=<return_type>.

Web Browser

https://copo-project.org/api/sample/associated_tol_project

Command Line (curl)

$ curl -X GET "https://copo-
project.org/api/sample/associated_tol_project" -H  "accept:
application/json"

Example

To retrieve the profile titles and associated tube or well IDs for the ASG profile type and ERGA_COMMUNITY associated profile type between 1st January, 2025 and 1st May, 2025 in CSV format, use the following URL.

The browser method will prompt a download of the CSV while the curl method is helpful if you are scripting or working in a terminal environment.

Web Browser

https://copo-project.org/api/?profile_type=ASG&associated_profile_
type=ERGA_COMMUNITY&d_from=2025-01-01T00:00:00+00:0&d_to=2025-05-
01T00:00:00+00:0&return_type=csv

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/?profile_type=ASG&asso
ciated_profile_type=ERGA_COMMUNITY&d_from=2025-01-
01T00:00:00+00:0&d_to=2025-05-01T00:00:00+00:0&return_type=csv" -H
"accept: application/json"

Fetch Sample Project Fields by Manifest Version

Show endpoint details

Show API query parameters

Tip

Filters are applied by appending them as query parameters in the API URL. See the Usage and Example sections for details.

• manifest_type (optional): The type of the manifest [1]. If no type is provided, all manifest types are used.

• return_type (optional): Output format for the results. Options include json (default) and csv

Usage

Web Browser

https://copo-project.org/api/manifest/current_version

Command Line (curl)

$ curl -X GET "https://copo-
project.org/api/manifest/current_version" -H  "accept:
application/json"

Example

To retrieve sample fields for the ASG project using the latest manifest version in CSV format, use the URL below.

The browser method will prompt a download of the CSV while the curl method is helpful if you are scripting or working in a terminal environment.

Web Browser

https://copo-project.org/api/manifest/current_version?manifest_typ
e=ASG&return_type=csv

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/manifest/current_versi
on?manifest_type=ASG&return_type=csv" -H  "accept: */*"

Fetch Profile Titles & Associated Tube or Well IDs

Show endpoint details

Show API query parameters

• profile_type (required): The type of profile to be created. [1]

• associated_profile_type (optional): The subproject or secondary profile type to filter the results. [2]

• d_from (optional): Start date for filtering (format: YYYY-MM- DDTHH:MM:SS+00:00)

• d_to (optional): End date for filtering (format: YYYY-MM- DDTHH:MM:SS+00:00)

• return_type (optional): Output format for the results. Options include json (default) and csv

To apply filters, append them to the API URL as follows:

profile/tube_or_well_ids?
profile_type=<profile_type>&associated_profile
_type=<associated_profile_type>&
d_from=<d_from>&d_to=<d_to>&
return_type=<return_type>

Replace <profile_type>, <associated_profile_type>, <d_from>, <d_to> and <return_type> with the desired values. See the example below.

Usage

Please include at least the profile_type parameter value in the API URL to retrieve a list of profile titles and associated tube or well IDs for the specified profile type. Replace <profile_type> with the desired value.

Web Browser

https://copo-project.org/api/profile/tube_or_well_ids?profile_type=<profile_type>

Command Line (curl)

$ curl -X POST "https://copo-project.org/api/profile/tube_or_well_ids?profile_type=<profile_type>" -H  "accept: */*" -d ""

Example

To retrieve the profile titles and associated tube or well IDs for the ERGA profile type and ERGA_COMMUNITY associated profile type between 1st January, 2025 and 1st May, 2025 in CSV format, use the following URL.

The browser method will prompt a download of the CSV while the curl method is helpful if you are scripting or working in a terminal environment.

Web Browser

https://copo-project.org/api/?profile_type=ERGA&associated_profile
_type=ERGA_COMMUNITY&d_from=2025-01-01T00:00:00+00:0&d_to=2025-05-
01T00:00:00+00:0&return_type=csv

Command Line (curl)

$ curl -X POST "https://copo-project.org/api/profile/tube_or_well_
ids?profile_type=ERGA&associated_profile_type=ERGA_COMMUNITY&d_fro
m=2025-01-01T00:00:00+00:0&d_to=2025-05-
01T00:00:00+00:0&return_type=csv" -H  "accept: */*" -d ""

Fetch Sample Records between Dates

Show endpoint details

Show API query parameters

Tip

Filters are applied by appending them as query parameters in the API URL. See the Usage and Example sections for details.

• from (required): Start date for filtering (format: YYYY-MM- DDTHH:MM:SS+00:00)

• to (required): End date for filtering (format: YYYY-MM- DDTHH:MM:SS+00:00)

• standard (optional): The standard to query the endpoint. Options include: tol (default), dwc, ena and mixs

• return_type (optional): Output format for the results. Options include json (default) and csv

Usage

Please include at least the from and to parameter values in the API URL to retrieve sample records. Replace {from} and {to} with the desired start and end dates respectively.

Web Browser

https://copo-project.org/api/sample/{from}/{to}

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/{from}/{to}" -H "accept: application/json"

Example

To retrieve sample records submitted between 1st January, 2025 and 1st May, 2025 in the default JSON format, use the following URL.

Web Browser

https://copo-project.org/api/sample/2025-01-01T00:00:00+00:0/2025-05-01T00:00:00+00:0

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/2025-01-
01T00:00:00+00:0/2025-05-01T00:00:00+00:0" -H  "accept:
application/json"

Fetch Updatable Fields by Project

Show endpoint details

Show API query parameters

Tip

Filters are applied by appending them as query parameters in the API URL. See the Usage and Example sections for details.

• project (required): The name of the project [1]. Multiple projects can be provided as a comma (,) separated list in this endpoint. Commas (,) are represented as %2C URL-encoded values in the API URL.

• standard (optional): The standard to query the endpoint. Options include: tol (default), dwc, ena and mixs

• return_type (optional): Output format for the results. Options include json (default) and csv

Usage

• Please include at least the project parameter value in the API URL to retrieve list of fields that can be updated when a manifest is reuploaded/resubmitted in COPO based on that project. Replace <project> with the desired project name.

• To apply filters, append them to the API URL as follows: sample/updatable_fields?project=<project>&standard=<standard>&return_ty pe=<return_type>. Replace <project>, <standard> and <return_type> with the desired values. See the example section below for full usage with optional filters.

Web Browser

https://copo-project.org/api/sample/updatable_fields?project=<project>

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/updatable_fields?project=<project>" -H "accept: */*"

Example

To retrieve the updatable fields for the DTOL project using the dwc standard in CSV format, use the following URL.

The browser method will prompt a download of the CSV while the curl method is helpful if you are scripting or working in a terminal environment.

Web Browser

https://copo-project.org/api/sample/updatable_fields?project=DTOL&
standard=dwc&return_type=csv

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/updatable_fiel
ds?project=DTOL&standard=dwc&return_type=csv" -H  "accept: */*"

Fetch Sample Records by COPO ID

Show endpoint details

Show API query parameters

Tip

Filters are applied by appending them as query parameters in the API URL. See the Usage and Example sections for details.

• copo_ids (required): The unique identifier of the sample record [5]. Multiple copo IDs can be provided as a comma (,) separated list in this endpoint. Commas (,) are represented as %2C URL-encoded values in the API URL.

• standard (optional): The standard to query the endpoint. Options include: tol (default), dwc, ena and mixs

• return_type (optional): Output format for the results. Options include json (default) and csv

Usage

Please include the {copo_ids} parameter in the API URL to retrieve full sample information for the specified copo_id [5] values. Replace {copo_ids} with one or more sample IDs, separated by commas.

Web Browser

https://copo-project.org/api/sample/copo_id/{copo_ids}

Command Line (curl)

$ curl -X GET "https://copo-
project.org/api/sample/copo_id/{copo_ids}" -H  "accept:
application/json"

Example

To retrieve sample metadata for sample records matching the copo_id values - 67e14bbf5b9e8a38259f95eb, 67e14bbf5b9e8a38259f95ec, 67e14bbf5b9e8a38259f95ed, 67e14bbf5b9e8a38259f95ee, 67e14bbf5b9e8a38259f95ef, 67e14bbf5b9e8a38259f95f0 and 67e14bbf5b9e8a38259f95f1 in the default JSON format, use the URL below.

Web Browser

https://copo-project.org/api/sample/copo_id/67e14bbf5b9e8a38259f95
eb%2C67e14bbf5b9e8a38259f95ec%2C67e14bbf5b9e8a38259f95ed%2C67e14bb
f5b9e8a38259f95ee%2C67e14bbf5b9e8a38259f95ef%2C67e14bbf5b9e8a38259
f95f0%2C67e14bbf5b9e8a38259f95f1

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/copo_id/67e14bb
f5b9e8a38259f95eb%2C67e14bbf5b9e8a38259f95ec%2C67e14bbf5b9e8a38259
f95ed%2C67e14bbf5b9e8a38259f95ee%2C67e14bbf5b9e8a38259f95ef%2C67e1
4bbf5b9e8a38259f95f0%2C67e14bbf5b9e8a38259f95f1" -H  "accept:
application/json"

Fetch Sample Records by Biosample Accession

Show endpoint details

Show API query parameters

Tip

Filters are applied by appending them as query parameters in the API URL. See the Usage and Example sections for details.

• biosampleAccessions (required): The accession number (s) assigned by ENA [2] after sample submission accession(s) of the sample records to be retrieved. Multiple biosample accessions [6] can be provided as a comma (,) separated list in this endpoint. Commas (,) are represented as %2C URL-encoded values in the API URL.

• standard (optional): The standard to query the endpoint. Options include: tol (default), dwc, ena and mixs

• return_type (optional): Output format for the results. Options include json (default) and csv

Usage

• Please include at least the biosampleAccessions parameter value in the API URL to retrieve sample records by biosample accession. Replace {biosampleAccessions} with the desired biosample accession(s).

• To apply filters, append them to the API URL as follows: sample/biosampleAccession/{biosampleAccessions}?standard=<standard>&ret urn_type=<return_type>. Replace {biosampleAccessions}, <standard> and <return_type> with the desired values. See the example section below for full usage with optional filters.

This results in full sample information for the sample record returned from the given {biosampleAccessions}.

Web Browser

https://copo-
project.org/api/sample/biosampleAccessions/{biosampleAccessions}

Command Line (curl)

$ curl -X GET "https://copo-
project.org/api/sample/biosampleAccessions/{biosampleAccessions}"
-H  "accept: application/json"

Example

To retrieve sample records with the biosample accessions - SAMEA12816320, SAMEA115502883, SAMEA112168601 and SAMEA112168603 in the mixs standard and return the results in JSON format, use the following.

Web Browser

https://copo-project.org/api/sample/biosampleAccessions/SAMEA12816
320%2CSAMEA115502883%2CSAMEA112168601%2CSAMEA112168603?standard=mi
xs&return_type=json

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/biosampleAccess
ions/SAMEA12816320%2CSAMEA115502883%2CSAMEA112168601%2CSAMEA112168
603?standard=mixs&return_type=json" -H  "accept: application/json"

Fetch Sample Records by Field and Values

Show endpoint details

Show API query parameters

Tip

Filters are applied by appending them as query parameters in the API URL. See the Usage and Example sections for details.

• field (required): The field to filter the sample records by. Choose from the list of available fields in this endpoint.

• values (required): The value(s) of the field to filter the sample records by. Multiple values can be provided as a comma (,) separated list in this endpoint. Commas (,) are represented as %2C URL-encoded values in the API URL.

• standard (optional): The standard to query the endpoint. Options include: tol (default), dwc, ena and mixs

• return_type (optional): Output format for the results. Options include json (default) and csv

Usage

Note

Some records may match multiple values for the field, depending on the values input. This happens because values are treated as substring matches - so results may include records where your input appears within a longer string. You may need to further filter the results to narrow them down precisely.

• Please include at least the field and values parameter values in the API URL to retrieve sample records by field and values. Replace {field} with the desired field name and {values} with the desired value(s).

• To apply filters, append them to the API URL as follows: sample/sample_field/{field}/{values}?standard=<standard>&return_type=<r eturn_type>. Replace {field}, {values}, <standard> and <return_type> with the desired values. See the example section below for full usage with optional filters.

Web Browser

https://copo-project.org/api/sample/sample_field/{field}/{values}

Command Line (curl)

$ curl -X GET "https://copo-
project.org/api/sample/sample_field/{field}/{values}" -H  "accept:
application/json"

Example

To retrieve sample records with the field SCIENTIFIC_NAME and values Marifugia cavatica, Graellsia isabellae and Valencia hispanica in the tol standard and return the results in CSV format, use the following.

The browser method will prompt a download of the CSV while the curl method is helpful if you are scripting or working in a terminal environment.

Web Browser

https://copo-project.org/api/sample/sample_field/SCIENTIFIC_NAME/Ma
rifugia%20cavatica%2CGraellsia%20isabellae%2CValencia%20hispanica?r
eturn_type=csv

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/sample_field/SC
IENTIFIC_NAME/Marifugia%20cavatica%2CGraellsia%20isabellae%2CValen
cia%20hispanica?return_type=csv" -H  "accept: application/json"

Fetch Sample Records by Sequencing Centre

Show endpoint details

Show API query parameters

Tip

Filters are applied by appending them as query parameters in the API URL. See the Usage and Example sections for details.

• sequencing_centre (required): The name of the sequencing centre used to filter sample records. Choose from the list of available sequencing centres provided in this this endpoint.

• return_type (optional): Output format for the results. Options include json (default) and csv

Usage

Please include at least the sequencing_centre parameter value in the API URL to retrieve full sample information for that sequencing centre. Replace <sequencing-centre> with the desired sequencing centre name.

Web Browser

https://copo-project.org/api/sample/sequencing_centre?sequencing_c
entre=<sequencing-centre>

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/sequencing_cent
re?sequencing_centre=<sequencing-centre>" -H  "accept:
application/json"

Example

To retrieve sample records with the sequencing centre EARLHAM INSTITUTE in the default JSON format, use the following URL.

Web Browser

https://copo-project.org/api/sample/sequencing_centre?sequencing_c
entre=EARLHAM%20INSTITUTE

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/sequencing_centr
e?sequencing_centre=EARLHAM%20INSTITUTE" -H  "accept:
application/json"

Fetch Sample Records by Taxon ID

Show endpoint details

Show API query parameters

Tip

Filters are applied by appending them as query parameters in the API URL. See the Usage and Example sections for details.

• taxon_ids (required): The taxon ID(s) of the sample records to be retrieved. Multiple taxon IDs can be provided as a comma (,) separated list in this endpoint. Commas (,) are represented as %2C URL-encoded values in the API URL.

• standard (optional): The standard to query the endpoint. Options include: tol (default), dwc, ena and mixs

• return_type (optional): Output format for the results. Options include json (default) and csv

Usage

• Please include at least the taxon_ids parameter values in the API URL to retrieve sample records by taxon IDs. Replace {taxon_ids} in the URL below with the taxon ID(s) of the sample records to be retrieved.

• To apply filters, append them to the API URL as follows: sample/taxon_id/{taxon_ids}?standard=<standard>&return_type=<return_typ e>. Replace {taxon_ids}, <standard> and <return_type> with the desired values. See the example section below for full usage with multiple taxon IDs and optional filters.

Web Browser

https://copo-project.org/api/sample/taxon_id/{taxon_ids}

Command Line (curl)

$ curl -X GET "https://copo-
project.org/api/sample/taxon_id/{taxon_ids}" -H  "accept:
application/json"

Example

To retrieve sample records with the taxon IDs - 6344, 199168 and 2614811 in the mixs standard and return the results in JSON format, use the following.

Please note that JSON is the default output format and does not need to be specified in the API URL. However, if you would like to explicitly state it, add &return_type=json to the end of the API URL.

Web Browser

https://copo-project.org/api/sample/taxon_id/6344%2C199168%2C26148
11?standard=mixs

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/taxon_id/6344%2
C199168%2C2614811?standard=mixs" -H  "accept: application/json"

Fetch Sample Records that have Image Submissions

Show endpoint details

Show API query parameters

Tip

Filters are applied by appending them as query parameters in the API URL. See the Usage and Example sections for details.

• profile_type (required): The name of the project. [1]

• associated_profile_type (optional): The associated project type of the sample records. This is the project type that the sample is a subproject of.

  For example, a sample may be associated with a project type of BGE but the sample itself may be an ERGA sample.

• d_from (optional): Start date for filtering (format: YYYY-MM- DDTHH:MM:SS+00:00)

• d_to (optional): End date for filtering (format: YYYY-MM- DDTHH:MM:SS+00:00)

• return_type (optional): Output format for the results. Options include json (default) and csv

Usage

• Please include at least the project parameter value in the API URL to retrieve sample records that have image submissions. Replace <project> with the name of the project.

• To apply filters, append them to the API URL as follows: sample/with_submitted_bioimages?project=<project>&from=<date>&to=<date> &return_type=<return_type>. Replace <project>, <from>, <to> and <return_type> with the project name, start date, end date and return type respectively. See the example below.

Web Browser

https://copo-
project.org/api/sample/with_submitted_bioimages?project=<project>

Command Line (curl)

$ curl -X GET "https://copo-
project.org/api/sample/with_submitted_bioimages?project=<project>"
-H  "accept: application/json"

Example

Additional filters like from, to and return_type are optional. Replace each parameter with the desired values. To retrieve sample records with image submissions for the project ERGA between 1st January, 2025 and 1st May, 2025 and return the results in CSV format, use the following.

The browser method will prompt a download of the CSV while the curl method is helpful if you are scripting or working in a terminal environment.

Web Browser

https://copo-project.org/api/sample/with_submitted_bioimages?proje
ct=erga&from=2025-01-01T00:00:00+00:0&to=2025-05-
01T00:00:00+00:0&return_type=csv

Command Line (curl)

$ curl -X GET "https://copo-project.org/api/sample/with_submitted
_bioimages?project=erga&from=2025-01-01T00:00:00+00:0&to=2025-05-
01T00:00:00+00:0&return_type=csv" -H  "accept: application/json"

---

Footnotes

[1] (1,2,3,4,5)

Refer to the Supported Projects section for more information

[2] (1,2,3)

See term: ENA

[3]

See term: Sample manager

[4]

See Secondary Projects section for available subprojects.

The associated project type refers to the subproject a sample is part of (e.g. a sample may be in the ERGA project but associated with the BGE subproject). In sample records, this is recorded as associated_tol_project whereas in profile records, as *associated_type.

[5] (1,2,3)

Sample records are identified by a unique ID known as copo_id in COPO and as alias in ENA.

[6]

A biosample accession is a unique identifier (ID) assigned to a sample record by ENA [2] after it has been submitted by a sample manager [3]. In COPO, this ID is referred to as biosampleAccession while in ENA, it appears as biosample_id.

---