Taxonomy

`GET /api/v1/taxonomy/tree/roots`

Returns top-level root nodes with child counts for progressive tree expansion.

curl "https://api.ilepbase.com/api/v1/taxonomy/tree/roots?page=1&pageSize=50"

Query Parameters

Name	Type	Required	Default	Description
`page`	`int`	No	`1`	Page number.
`pageSize`	`int`	No	`50`	Items per page (max 200).

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "name": "Lepidoptera",
        "rank": "order",
        "depth": 1,
        "childCount": 126,
        "hasDetail": true
      }
    ],
    "pagination": {
      "page": 1, "pageSize": 50,
      "total": 1, "totalPages": 1,
      "hasNext": false, "hasPrev": false
    }
  },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

`GET /api/v1/taxonomy/tree/children`

Returns child nodes for a given parent taxonomy node.

curl "https://api.ilepbase.com/api/v1/taxonomy/tree/children?parentId=1&page=1&pageSize=50"

Query Parameters

Name	Type	Required	Default	Description
`parentId`	`int`	Yes	—	Parent node ID.
`page`	`int`	No	`1`	Page number.
`pageSize`	`int`	No	`50`	Items per page (max 200).

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 2,
        "name": "Papilionidae",
        "rank": "family",
        "depth": 2,
        "childCount": 31,
        "hasDetail": false
      }
    ],
    "parentId": 1,
    "pagination": {
      "page": 1, "pageSize": 50,
      "total": 126, "totalPages": 3,
      "hasNext": true, "hasPrev": false
    }
  },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

Error: 400 Bad Request

{
  "success": false,
  "error": {
    "code": "MISSING_PARENT_ID",
    "message": "Query parameter 'parentId' is required."
  },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

`GET /api/v1/taxonomy/search`

Full-text search across the taxonomy tree. Supports scientific name and synonym search with HTML highlighting.

curl "https://api.ilepbase.com/api/v1/taxonomy/search?q=papilio&limit=20"

Query Parameters

Name	Type	Required	Default	Description
`q`	`string`	Yes	—	Search keyword.
`limit`	`int`	No	`20`	Maximum results (max 100).

`GET /api/v1/taxonomy/typeahead`

Prefix-based typeahead for taxonomy nodes. Returns scientific names, common names, and parent context.

curl "https://api.ilepbase.com/api/v1/taxonomy/typeahead?q=Pap&limit=10"

Query Parameters

Name	Type	Required	Default	Description
`q`	`string`	Yes	—	Prefix keyword (min 2 characters).
`limit`	`int`	No	`10`	Maximum results (max 20).

Error: 503 Service Unavailable

{
  "success": false,
  "error": {
    "code": "TYPEAHEAD_UNAVAILABLE",
    "message": "Typeahead service is unavailable."
  },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

`GET /api/v1/taxonomy/nodes/{nodeId}`

Returns the full detail payload for a taxonomy node.

curl https://api.ilepbase.com/api/v1/taxonomy/nodes/1

Response

{
  "success": true,
  "data": {
    "node": {
      "id": "order-lepidoptera",
      "name": "Lepidoptera",
      "rank": "Order",
      "detailId": "order-lepidoptera"
    },
    "detail": {
      "id": "order-lepidoptera",
      "title": "Lepidoptera",
      "rank": "Order",
      "summary": "Lepidoptera comprises butterflies and moths, with approximately 180,000 described species worldwide...",
      "image": "/assets/images/home/u50.png",
      "links": [
        { "label": "GBIF", "href": "https://www.gbif.org/species/1852787" }
      ],
      "metrics": [
        { "label": "Families", "value": "126" },
        { "label": "Species", "value": "114,852" }
      ],
      "omics": {
        "summary": "Multi-omics data available for selected species.",
        "items": [
          { "label": "Genomes", "value": "48 assemblies" },
          { "label": "Transcriptomes", "value": "24 datasets" }
        ]
      },
      "ecology": {
        "summary": "Hostplant associations and distribution data.",
        "items": [
          { "label": "Hostplant Records", "value": "3,200+" }
        ]
      },
      "literature": {
        "summary": "Key publications referencing this taxon.",
        "publications": [
          {
            "title": "A comprehensive phylogeny of Lepidoptera...",
            "citation": "Kawahara et al., 2019, PNAS",
            "href": "https://doi.org/10.1073/pnas.1907842116",
            "tags": ["phylogeny", "transcriptome"]
          }
        ],
        "graph": {
          "nodes": [ ... ],
          "edges": [ ... ]
        }
      },
      "genetics": "Lepidoptera have a ZW sex-determination system...",
      "morphology": "Adults characterized by two pairs of membranous wings covered in scales..."
    }
  },
  "timestamp": "2026-04-23T12:00:00.000Z"
}

`GET /api/v1/taxonomy/nodes/{nodeId}/literature`

Paginated literature linked to a taxonomy node.

curl "https://api.ilepbase.com/api/v1/taxonomy/nodes/1/literature?page=1&pageSize=20"

Query Parameters

Name	Type	Required	Default	Description
`page`	`int`	No	`1`	Page number.
`pageSize`	`int`	No	`20`	Items per page.

Path Parameters

Name	Type	Description
`nodeId`	`int`	Taxonomy node ID.

Taxonomy

On this page