> ## Documentation Index
> Fetch the complete documentation index at: https://api.superseeded.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify Plant Names

> Validate botanical species names against 11 authoritative taxonomic databases with AI fallback. Queries GBIF, TNRS (WFO), POWO (Kew), iNaturalist, EOL, ALA, IP Australia PBR, UPOV, WikiSpecies, Wikidata, and Wikipedia in parallel. Returns unified taxonomic records with consensus scoring. Accepts input as: (1) JSON body with species_names array, (2) JSON body with file_url from TUS upload, or (3) multipart form-data with direct file upload.

Validate botanical species names against 11 authoritative taxonomic databases with Gemini AI fallback. Returns unified taxonomic records with consensus scoring.

## Overview

This endpoint queries 11 botanical databases in parallel, consolidates results using a weighted consensus algorithm, and returns a unified taxonomic record per species. Names that no source can resolve are sent to Google Gemini AI as a corrective fallback.

Sources queried: GBIF, TNRS (WFO), POWO (Kew), iNaturalist, EOL, ALA, IP Australia PBR, UPOV, WikiSpecies, Wikidata, Wikipedia.

## Input Options

This endpoint accepts input in three ways:

### 1. JSON Body with Species Names Array

```bash theme={"theme":"github-dark"}
curl -X POST https://api.superseeded.ai/v1/verify/plant-names \
  -H "X-API-Key: sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "species_names": [
      "Eucalyptus globulus",
      "Acacia melanoxylon",
      "Banksia integrifolia"
    ]
  }'
```

### 2. JSON Body with File URL (TUS Upload)

For files uploaded via TUS protocol. Names are pre-parsed by LLM, so no additional extraction is performed.

```bash theme={"theme":"github-dark"}
curl -X POST https://api.superseeded.ai/v1/verify/plant-names \
  -H "Authorization: Bearer <delegation_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://secure.superseeded.ai/files/abc123",
    "filename": "species_list.xlsx"
  }'
```

### 3. Direct File Upload (Multipart)

Upload files directly without TUS:

```bash theme={"theme":"github-dark"}
curl -X POST https://api.superseeded.ai/v1/verify/plant-names \
  -H "X-API-Key: sk_..." \
  -F "file=@plant_schedule.xlsx" \
  -F "extraction_column=Species"
```

## Request Body (JSON)

<ParamField body="species_names" type="string[]">
  An array of species name strings to validate. Takes precedence over file inputs.
</ParamField>

<ParamField body="file_url" type="file">
  URL to a previously uploaded file (from TUS storage). Names are pre-parsed via LLM.

  **Tip:** You can use the file input dialog in this playground to test with a local file.
</ParamField>

<ParamField body="filename" type="string">
  Original filename for context when using `file_url`.
</ParamField>

<ParamField body="extraction_column" type="string">
  Specific column name containing species names in spreadsheet files.
</ParamField>

<ParamField body="sources" type="string[]">
  Specific sources to query. Defaults to all 11 non-Gemini sources. Gemini is always a fallback-only source.

  Available: `gbif`, `tnrs`, `powo`, `inaturalist`, `eol`, `ala`, `ip_australia`, `upov`, `wikispecies`, `wikidata`, `wikipedia`
</ParamField>

<ParamField body="include_metadata" type="boolean" default="true">
  Include detailed taxonomic metadata in results.
</ParamField>

<ParamField body="cache_results" type="boolean" default="true">
  Cache validation results for future queries.
</ParamField>

## Form Data (Multipart Upload)

<ParamField body="file" type="file">
  Direct file upload. Supports: JSON, XLSX, XLS, CSV, PDF, TXT.
</ParamField>

<ParamField body="extraction_column" type="string">
  Column name containing species names for spreadsheet files.
</ParamField>

## Response

The response contains an array of unified taxonomic records and a summary.

<ResponseField name="results" type="object[]">
  Array of unified taxonomic records, one per species name.

  <Expandable title="Unified Taxonomic Record">
    <ResponseField name="query" type="object">
      Query information.

      <Expandable title="properties">
        <ResponseField name="submitted_name" type="string">
          Original species name as submitted.
        </ResponseField>

        <ResponseField name="normalized_name" type="string">
          Lowercase, trimmed version used for matching.
        </ResponseField>

        <ResponseField name="query_timestamp" type="string">
          ISO 8601 timestamp of the query.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="validation" type="object">
      Validation status and confidence scoring.

      <Expandable title="properties">
        <ResponseField name="status" type="string">
          Validation result: `validated`, `uncertain`, or `not_found`.
        </ResponseField>

        <ResponseField name="confidence" type="string">
          Confidence level: `high`, `medium`, or `low`.
        </ResponseField>

        <ResponseField name="consensus_score" type="number">
          0.0-1.0 score based on source agreement.
        </ResponseField>

        <ResponseField name="sources_checked" type="integer">
          Number of sources that returned results.
        </ResponseField>

        <ResponseField name="sources_matched" type="integer">
          Number of sources with a match.
        </ResponseField>

        <ResponseField name="match_summary" type="object">
          Counts of exact\_matches, inexact\_matches, no\_match.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="accepted_name" type="object">
      The determined correct scientific name.

      <Expandable title="properties">
        <ResponseField name="scientific_name" type="string">
          Accepted scientific name determined by weighted consensus.
        </ResponseField>

        <ResponseField name="author" type="string">
          Taxonomic author (e.g. "Labill.").
        </ResponseField>

        <ResponseField name="nomenclatural_status" type="string">
          `accepted`, `synonym`, `unresolved`, or `not_found`.
        </ResponseField>

        <ResponseField name="common_names" type="object[]">
          Common names with language and region.
        </ResponseField>

        <ResponseField name="taxonomic_rank" type="string">
          Rank: species, subspecies, variety, etc.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="taxonomy" type="object">
      Complete taxonomic classification.

      <Expandable title="properties">
        <ResponseField name="kingdom" type="string">Always "Plantae".</ResponseField>
        <ResponseField name="family" type="string">Plant family (e.g. "Myrtaceae").</ResponseField>
        <ResponseField name="genus" type="string">Genus name.</ResponseField>
        <ResponseField name="species" type="string">Species epithet.</ResponseField>
        <ResponseField name="subspecies" type="string">Subspecies if applicable.</ResponseField>
        <ResponseField name="variety" type="string">Variety if applicable.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="cross_references" type="object">
      Database IDs for deep linking.

      <Expandable title="properties">
        <ResponseField name="gbif_id" type="string">GBIF taxon key.</ResponseField>
        <ResponseField name="wfo_id" type="string">World Flora Online ID.</ResponseField>
        <ResponseField name="powo_id" type="string">Plants of the World Online ID.</ResponseField>
        <ResponseField name="eol_id" type="string">Encyclopedia of Life page ID.</ResponseField>
        <ResponseField name="ala_guid" type="string">Atlas of Living Australia GUID.</ResponseField>
        <ResponseField name="wikidata_id" type="string">Wikidata entity ID.</ResponseField>
        <ResponseField name="inaturalist_taxon_id" type="string">iNaturalist taxon ID.</ResponseField>
        <ResponseField name="pbr_numbers" type="string[]">IP Australia PBR identifiers.</ResponseField>
        <ResponseField name="upov_code" type="string">UPOV variety code.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Processing metadata.

      <Expandable title="properties">
        <ResponseField name="quality_score" type="number">Overall data quality (0.0-1.0).</ResponseField>
        <ResponseField name="api_version" type="string">API version.</ResponseField>
        <ResponseField name="processing_time_seconds" type="number">Processing time.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="warnings" type="string[]">
      Any data quality warnings or conflicts.
    </ResponseField>

    <ResponseField name="notes" type="string[]">
      Informational notes about validation.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object">
  Batch validation summary.

  <Expandable title="properties">
    <ResponseField name="total" type="integer">Total species processed.</ResponseField>
    <ResponseField name="validated" type="integer">Count with validated status.</ResponseField>
    <ResponseField name="uncertain" type="integer">Count with uncertain status.</ResponseField>
    <ResponseField name="not_found" type="integer">Count with not\_found status.</ResponseField>
  </Expandable>
</ResponseField>

## Example Response

```json theme={"theme":"github-dark"}
{
  "results": [
    {
      "query": {
        "submitted_name": "Eucalyptus globulus",
        "normalized_name": "eucalyptus globulus",
        "query_timestamp": "2025-01-15T10:30:00Z"
      },
      "validation": {
        "status": "validated",
        "confidence": "high",
        "consensus_score": 0.98,
        "sources_checked": 11,
        "sources_matched": 9,
        "match_summary": {
          "exact_matches": 8,
          "inexact_matches": 1,
          "no_match": 0
        }
      },
      "accepted_name": {
        "scientific_name": "Eucalyptus globulus",
        "author": "Labill.",
        "nomenclatural_status": "accepted",
        "common_names": [
          {
            "name": "Tasmanian Blue Gum",
            "language": "en",
            "region": "Global"
          }
        ],
        "taxonomic_rank": "species"
      },
      "taxonomy": {
        "kingdom": "Plantae",
        "family": "Myrtaceae",
        "genus": "Eucalyptus",
        "species": "globulus",
        "subspecies": null,
        "variety": null
      },
      "cross_references": {
        "gbif_id": "3176787",
        "wfo_id": "946382",
        "powo_id": "urn:lsid:ipni.org:names:30001419-2",
        "eol_id": "301421",
        "ala_guid": "https://id.biodiversity.org.au/taxon/apni/51440555",
        "wikidata_id": "Q159528",
        "inaturalist_taxon_id": "53398",
        "pbr_numbers": ["1990/106"],
        "upov_code": "EUCAL_GLO"
      },
      "metadata": {
        "version": "1.0",
        "api_version": "1.0.0",
        "quality_score": 0.9,
        "processing_time_seconds": 4.67
      },
      "warnings": [],
      "notes": [
        "Name validated against 9 authoritative botanical databases",
        "Confirmed by: Taxonomic Name Resolution Service (WFO), Plants of the World Online (Kew Gardens), Global Biodiversity Information Facility"
      ]
    }
  ],
  "summary": {
    "total": 1,
    "validated": 1,
    "uncertain": 0,
    "not_found": 0
  }
}
```

## Authentication

<ParamField header="X-API-Key" type="string">
  Your API key for Basic/Pro plan authentication.
</ParamField>

<ParamField header="Authorization" type="string">
  Bearer token for Teams plan platform integration.
</ParamField>

## Supported File Formats

| Format | Extension       | Description                             |
| ------ | --------------- | --------------------------------------- |
| JSON   | `.json`         | Direct arrays of species names          |
| Excel  | `.xlsx`, `.xls` | Spreadsheets with species columns       |
| CSV    | `.csv`          | Comma-separated values                  |
| PDF    | `.pdf`          | Text extraction from documents          |
| Text   | `.txt`          | One species per line or comma-separated |

## Error Handling

| Status Code | Description                                                        |
| ----------- | ------------------------------------------------------------------ |
| 200         | Success                                                            |
| 400         | Bad request (invalid input, missing species names, invalid source) |
| 401         | Unauthorized (invalid or missing API key)                          |
| 403         | Forbidden (API key inactive, expired, or usage limit exceeded)     |
| 500         | Internal server error                                              |

## Rate Limits

* API usage is tracked per API key
* Each species name processed counts as 1 usage unit
* Rate limits vary by subscription plan
* Batch processing is more efficient for large datasets


## OpenAPI

````yaml POST /verify/plant-names
openapi: 3.1.0
info:
  title: Superseeded API
  description: >-
    Modern nursery industry API for reconciling plant specifications, resolving
    equivalence and assessing logistical risks for plant stock.
  version: 1.0.0
  license:
    name: MIT
  contact:
    name: Superseeded Support
servers:
  - url: https://api.superseeded.ai/v1
    description: Production Server
security: []
tags:
  - name: Resolvers
    description: Endpoints for cleaning, normalizing, and interpreting messy nursery data.
  - name: Validation
    description: >-
      Endpoints for validating botanical species names against taxonomic
      databases.
  - name: Flowers
    description: >-
      Search flowers by color using spectral reflectance data from the Floral
      Reflectance Database (FReD).
  - name: System
    description: Health checks and service status.
  - name: Images
    description: Resolve public catalog image URLs for storefront and product integrations.
paths:
  /verify/plant-names:
    post:
      tags:
        - Validation
      summary: Verify Plant Names
      description: >-
        Validate botanical species names against 11 authoritative taxonomic
        databases with AI fallback. Queries GBIF, TNRS (WFO), POWO (Kew),
        iNaturalist, EOL, ALA, IP Australia PBR, UPOV, WikiSpecies, Wikidata,
        and Wikipedia in parallel. Returns unified taxonomic records with
        consensus scoring. Accepts input as: (1) JSON body with species_names
        array, (2) JSON body with file_url from TUS upload, or (3) multipart
        form-data with direct file upload.
      operationId: verifyPlantNames
      requestBody:
        description: Object containing species names to validate or file reference.
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: 'File to upload. Supports: JSON, XLSX, XLS, CSV, PDF, TXT.'
                extraction_column:
                  type: string
                  description: Column name containing species names for spreadsheet files.
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateSpeciesRequest'
      responses:
        '200':
          description: Successful validation with unified taxonomic records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateSpeciesResponse'
        '400':
          description: Bad Request - Invalid input or no species names found.
        '401':
          description: Unauthorized - Missing API Key.
        '403':
          description: Forbidden - Invalid API Key or usage limit exceeded.
        '500':
          description: Internal Server Error - Species validation failed.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ValidateSpeciesRequest:
      type: object
      properties:
        species_names:
          type: array
          items:
            type: string
          description: List of species names to validate
          example:
            - Eucalyptus globulus
            - Acacia melanoxylon
        file_url:
          type: string
          format: binary
          description: URL to uploaded file containing species names
          example: https://secure.superseeded.ai/files/abc123
        filename:
          type: string
          description: Original filename for context
          example: species_list.xlsx
        extraction_column:
          type: string
          description: Column name containing species names in spreadsheet files
          example: Botanical Name
        sources:
          type: array
          items:
            type: string
            enum:
              - gbif
              - tnrs
              - powo
              - inaturalist
              - eol
              - ala
              - ip_australia
              - upov
              - wikispecies
              - wikidata
              - wikipedia
          description: >-
            Specific sources to query. Defaults to all 11 sources (excludes
            gemini AI fallback). Gemini is only used when all other sources
            return no match.
          example:
            - gbif
            - tnrs
            - powo
        include_metadata:
          type: boolean
          default: true
          description: Include detailed taxonomic metadata
        cache_results:
          type: boolean
          default: true
          description: Cache results for future queries
    ValidateSpeciesResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/UnifiedTaxonomicRecord'
          description: Array of unified taxonomic records, one per species
        summary:
          type: object
          properties:
            total:
              type: integer
              description: Total species processed
            validated:
              type: integer
              description: Count with validated status (high confidence)
            uncertain:
              type: integer
              description: Count with uncertain status (requires review)
            not_found:
              type: integer
              description: Count with not_found status
    UnifiedTaxonomicRecord:
      type: object
      properties:
        query:
          type: object
          properties:
            submitted_name:
              type: string
              description: Original species name as submitted
            normalized_name:
              type: string
              description: Lowercase, trimmed version used for matching
            query_timestamp:
              type: string
              format: date-time
              description: ISO 8601 timestamp of the query
        validation:
          type: object
          properties:
            status:
              type: string
              enum:
                - validated
                - uncertain
                - not_found
              description: Validation result
            confidence:
              type: string
              enum:
                - high
                - medium
                - low
              description: Confidence level
            consensus_score:
              type: number
              minimum: 0
              maximum: 1
              description: 0.0-1.0 score based on source agreement
            sources_checked:
              type: integer
              description: Number of sources that returned results
            sources_matched:
              type: integer
              description: Number of sources with a match
            match_summary:
              type: object
              properties:
                exact_matches:
                  type: integer
                inexact_matches:
                  type: integer
                no_match:
                  type: integer
        accepted_name:
          type: object
          properties:
            scientific_name:
              type: string
              description: Accepted scientific name determined by consensus
            author:
              type: string
              description: Taxonomic author
            nomenclatural_status:
              type: string
              enum:
                - accepted
                - synonym
                - unresolved
                - not_found
              description: Nomenclatural status
            common_names:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  language:
                    type: string
                  region:
                    type: string
            taxonomic_rank:
              type: string
              description: 'Rank: species, subspecies, variety, etc.'
        taxonomy:
          type: object
          properties:
            kingdom:
              type: string
              example: Plantae
            family:
              type: string
              description: Plant family
            genus:
              type: string
              description: Genus name
            species:
              type: string
              description: Species epithet
            subspecies:
              type: string
              nullable: true
            variety:
              type: string
              nullable: true
        cross_references:
          type: object
          properties:
            gbif_id:
              type: string
              description: GBIF taxon key
            wfo_id:
              type: string
              description: World Flora Online ID
            powo_id:
              type: string
              description: Plants of the World Online ID
            eol_id:
              type: string
              description: Encyclopedia of Life page ID
            ala_guid:
              type: string
              description: Atlas of Living Australia GUID
            wikidata_id:
              type: string
              description: Wikidata entity ID
            inaturalist_taxon_id:
              type: string
              description: iNaturalist taxon ID
            pbr_numbers:
              type: array
              items:
                type: string
              description: IP Australia PBR identifiers
            upov_code:
              type: string
              description: UPOV variety code
        metadata:
          type: object
          properties:
            quality_score:
              type: number
              minimum: 0
              maximum: 1
              description: Overall data quality score
            api_version:
              type: string
              description: API version
            processing_time_seconds:
              type: number
              description: Processing time
        warnings:
          type: array
          items:
            type: string
          description: Data quality warnings or conflicts
        notes:
          type: array
          items:
            type: string
          description: Informational notes about validation
      example:
        query:
          submitted_name: Eucalyptus globulus
          normalized_name: eucalyptus globulus
          query_timestamp: '2025-01-15T10:30:00Z'
        validation:
          status: validated
          confidence: high
          consensus_score: 0.98
          sources_checked: 11
          sources_matched: 9
          match_summary:
            exact_matches: 8
            inexact_matches: 1
            no_match: 0
        accepted_name:
          scientific_name: Eucalyptus globulus
          author: Labill.
          nomenclatural_status: accepted
          common_names:
            - name: Tasmanian Blue Gum
              language: en
              region: Global
          taxonomic_rank: species
        taxonomy:
          kingdom: Plantae
          family: Myrtaceae
          genus: Eucalyptus
          species: globulus
          subspecies: null
          variety: null
        cross_references:
          gbif_id: '3176787'
          wfo_id: '946382'
          powo_id: urn:lsid:ipni.org:names:30001419-2
          eol_id: '301421'
          ala_guid: https://id.biodiversity.org.au/taxon/apni/51440555
          wikidata_id: Q159528
          inaturalist_taxon_id: '53398'
          pbr_numbers:
            - 1990/106
          upov_code: EUCAL_GLO
        metadata:
          quality_score: 0.9
          api_version: 1.0.0
          processing_time_seconds: 4.67
        warnings: []
        notes:
          - Name validated against 9 authoritative botanical databases
          - >-
            Confirmed by: Taxonomic Name Resolution Service (WFO), Plants of the
            World Online (Kew Gardens), Global Biodiversity Information Facility
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Standard API Key authentication.

````