1. Overview

The AGRP public API provides structured access to selected platform resources. It can be used to list available datasets, check file availability, download genome-related files, and query public data tables or JSON resources.

2. Quick Start

All current API endpoints are under the following base URL:

https://asteraceae.cgrpoee.top/api/

1. Choose the resource group you need, such as genome files, Genomics annotations, Geno-Syn comparative data, or Multi-Omics data.
2. Find the endpoint in the tables below and include all required parameters in the URL query string.
3. Add optional filters such as limit, offset, q, or gene_id only when they are needed.
4. Send a GET request with curl, a browser, Python, R, or another HTTP client.

Example: check and download a genome file

For file downloads, it is recommended to check the file first and then download it.

# 1. Check whether the file exists
curl -i "https://asteraceae.cgrpoee.top/api/files/genome/?species=Aann&type=cds"

# 2. Download the file
curl -L -o Aann.cds "https://asteraceae.cgrpoee.top/api/download/genome/?species=Aann&type=cds"

Example: query data with a limit

For large query endpoints, use limit to return a manageable number of records. The default limit is 20 records. For public access, the maximum allowed limit is 100 records per request; authorized API-key users may have higher limit caps.

curl -i "https://asteraceae.cgrpoee.top/api/genomics/kegg/?species=Aann&limit=5"

3. General Rules

4. Health Check and Client IP

curl -H "Accept: application/json" "https://asteraceae.cgrpoee.top/api/ping/"

{
  "status": "ok",
  "message": "AGRP API is running",
  "version": "1.0",
  "base_url": "https://asteraceae.cgrpoee.top/api/"
}

curl -4 -i "https://asteraceae.cgrpoee.top/api/whoami/"

{
  "status": "ok",
  "detected_ip": "203.0.113.10",
  "ip_source": "CF-Connecting-IP",
  "is_private_or_local": false,
  "message": "This is the client IP address detected by the AGRP API for this request."
}

5. Genomics APIs

Genomics APIs provide access to genome file resources and selected annotation datasets.

curl -i "https://asteraceae.cgrpoee.top/api/genomics/species/"
curl -i "https://asteraceae.cgrpoee.top/api/files/genome/?species=Aann&type=lens"
curl -L -o Aann.lens "https://asteraceae.cgrpoee.top/api/download/genome/?species=Aann&type=lens"

curl -i "https://asteraceae.cgrpoee.top/api/genomics/interproscan/?species=Aann&database=Pfam&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genomics/kegg/?species=Aann&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genomics/regulatory-proteins/?species=Aann&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genomics/m6a/?species=Aann&first_class=readers&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genomics/duplication-types/?species=Aann&limit=5"

curl -i "https://asteraceae.cgrpoee.top/api/genomics/transposable-elements/species/"
curl -i "https://asteraceae.cgrpoee.top/api/genomics/transposable-elements/?species=Artemisia_annua&limit=5"

6. Geno-Syn APIs

Geno-Syn APIs provide access to comparative genomics resources, ancestral genome files, collinearity data, block data, hierarchical data, and selected gene datasets.

curl -i "https://asteraceae.cgrpoee.top/api/genosyn/ancestral-genomes/"
curl -i "https://asteraceae.cgrpoee.top/api/files/ancestral/?dataset=AAKI&type=cds"
curl -L -o AAKI.cds "https://asteraceae.cgrpoee.top/api/download/ancestral/?dataset=AAKI&type=cds"

curl -i "https://asteraceae.cgrpoee.top/api/genosyn/collinear-kaks/?q=Aann&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genosyn/dotplots/?q=Hean&limit=5"

curl -i "https://asteraceae.cgrpoee.top/api/genosyn/blocks/?query_genome=Aann&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genosyn/block-details/?query_genome=Aann&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genosyn/hierarchical-alignments/?reference=Hean&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genosyn/hierarchical-genes/?reference=Hean&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genosyn/evogenes/?limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genosyn/orthologous/?limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genosyn/gene-families/?limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genosyn/rubber-genes/?limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genosyn/inulin-genes/?limit=5"

7. Multi-Omics APIs

Multi-Omics APIs provide access to pan-genome, transcriptome, expression, and metabolomics resources.

curl -i "https://asteraceae.cgrpoee.top/api/multiomics/pangenome/?limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/multiomics/transcriptome/samples/?limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/multiomics/transcriptome/sample/?filename=Dapi_white%20petal.json"
curl -i "https://asteraceae.cgrpoee.top/api/multiomics/transcriptome/expression/?species=Aann&expression_index=TPM&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/multiomics/metabolomics/plant/?limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/multiomics/metabolomics/scent/?limit=5"

8. Rate Limits and Fair Use

The AGRP API provides public read-only access to selected Asteraceae genomic, comparative genomics, and multi-omics resources. Authentication is not required for standard query and download endpoints.

To maintain stable service for all users, API requests are rate-limited by client access level. Standard public users are limited by IP address. Authorized collaborators may receive higher quotas through registered IP addresses or dedicated API keys.

Checking the IP address for whitelist applications

Before requesting IPv4 whitelist access, run the following command from the actual fixed server that will access AGRP. This command forces IPv4 and avoids accidentally submitting an IPv6 address returned by a browser request.

curl -4 -i "https://asteraceae.cgrpoee.top/api/whoami/"

Using an approved IPv4 whitelist

If AGRP has approved and registered your IPv4 address, make sure your automated requests are sent through that same IPv4 address. For curl, add -4 to high-throughput query or download commands when your network may otherwise prefer IPv6.

curl -4 -i "https://asteraceae.cgrpoee.top/api/genomics/kegg/?species=Aann&limit=1000"

curl -4 -L -o Aann.cds "https://asteraceae.cgrpoee.top/api/download/genome/?species=Aann&type=cds"

Using an API key

If the AGRP team provides an API key, include it in the HTTP request header named X-AGRP-API-Key. Do not include the key in a URL parameter, browser address bar, or shared link.

curl -H "X-AGRP-API-Key: agrp_your_api_key_here" \
  "https://asteraceae.cgrpoee.top/api/genomics/kegg/?species=Aann&limit=1000"

curl -H "X-AGRP-API-Key: agrp_your_api_key_here" \
  -L -o Aann.cds \
  "https://asteraceae.cgrpoee.top/api/download/genome/?species=Aann&type=cds"

Recommended access pattern

• Check file availability before downloading large files.
• Use limit and offset for large tables instead of requesting all records at once.
• Avoid opening many parallel download connections from the same IP address.
• Use the X-AGRP-API-Key header only when an API key has been issued by the AGRP team.
• For full-dataset access, request a bulk package or manifest when possible.

9. Error Responses

When a request is invalid or the requested resource does not exist, the API returns a JSON error response with an appropriate HTTP status code.

9.1 Missing required parameter

curl -i "https://asteraceae.cgrpoee.top/api/genosyn/blocks/?limit=5"

{
  "status": "error",
  "message": "Missing required parameter: query_genome"
}

Correct request:

curl -i "https://asteraceae.cgrpoee.top/api/genosyn/blocks/?query_genome=Aann&limit=5"

9.2 Invalid file type

curl -i "https://asteraceae.cgrpoee.top/api/download/genome/?species=Aann&type=abc"

{
  "status": "error",
  "message": "Invalid type parameter.",
  "type": "abc",
  "allowed_types": ["cds", "pep", "lens", "gff"]
}

9.3 File not found

curl -i "https://asteraceae.cgrpoee.top/api/download/genome/?species=NotExist&type=cds"

{
  "status": "error",
  "message": "File not found.",
  "species": "NotExist",
  "type": "cds",
  "filename": "NotExist.cds"
}

9.4 Invalid species parameter

curl -i "https://asteraceae.cgrpoee.top/api/download/genome/?species=../../etc/passwd&type=cds"

{
  "status": "error",
  "message": "Invalid species parameter. Only letters, numbers, underscores, hyphens and dots are allowed.",
  "species": "../../etc/passwd"
}

9.5 Too many requests

If the request frequency or the number of concurrent downloads is too high, the API may return 429 Too Many Requests.

{
  "detail": "Request was throttled. Expected available in 42 seconds."
}

For concurrent download limits, the response may look like this:

{
  "detail": "Too many concurrent download requests. Please wait for your current downloads to finish."
}

10. Usage Examples

The examples below show common ways to use the API. The tables above provide the full list of endpoints and supported parameters.

10.1 Check your detected IPv4 address

curl -4 -i "https://asteraceae.cgrpoee.top/api/whoami/"

10.2 Check whether the API is available

curl -i "https://asteraceae.cgrpoee.top/api/ping/"

10.3 List genome resources and download a file

# List species with available genome files
curl -i "https://asteraceae.cgrpoee.top/api/genomics/species/"

# Check whether a specific file exists
curl -i "https://asteraceae.cgrpoee.top/api/files/genome/?species=Aann&type=cds"

# Download the file
curl -L -o Aann.cds "https://asteraceae.cgrpoee.top/api/download/genome/?species=Aann&type=cds"

10.4 Query annotation records

curl -i "https://asteraceae.cgrpoee.top/api/genomics/kegg/?species=Aann&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genomics/interproscan/?species=Aann&database=Pfam&limit=5"

10.5 Query Geno-Syn records

curl -i "https://asteraceae.cgrpoee.top/api/genosyn/blocks/?query_genome=Aann&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genosyn/block-details/?query_genome=Aann&limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/genosyn/hierarchical-genes/?reference=Hean&limit=5"

10.6 Query Multi-Omics records

curl -i "https://asteraceae.cgrpoee.top/api/multiomics/pangenome/?limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/multiomics/transcriptome/samples/?limit=5"
curl -i "https://asteraceae.cgrpoee.top/api/multiomics/transcriptome/sample/?filename=Dapi_white%20petal.json"
curl -i "https://asteraceae.cgrpoee.top/api/multiomics/metabolomics/plant/?limit=5"

11. Notes

• The API provides public read-only access to selected AGRP resources.
• Download endpoints return file streams only when the requested file exists. For scripts, check file availability before downloading large files.
• API requests may be rate-limited by IP address or authorized access level to maintain stable public service.
• Authorized collaborators may receive higher quotas through registered fixed server IPv4 addresses or the X-AGRP-API-Key request header.
• Use curl -4 -i "https://asteraceae.cgrpoee.top/api/whoami/" to check the IPv4 address detected by AGRP before requesting IPv4 whitelist access.
• If your approved whitelist address is IPv4, make sure later curl-based high-throughput requests also use -4 when the network may otherwise prefer IPv6.
• Use limit and offset when querying large tables or JSON resources. The default limit is 20. For public access, the maximum allowed limit is 100; authorized API-key users may have higher limit caps.
• URL-encode filenames or query values that contain spaces, for example Dapi_white%20petal.json.
• A successful response with an empty data list means the request was valid but no matching records were found.
• This documentation describes programmatic access to public resources and does not replace the normal website pages.