openapi: 3.1.0
info:
  title: Perenual API
  description: >-
    Perenual provides a comprehensive plant database API offering access to over 10,000+
    plant species, including details on care, watering, sunlight, edibility, toxicity,
    pests, diseases, and care guides.
  version: '2.0'
  contact:
    name: Perenual API Support
    url: https://perenual.com/docs/api
externalDocs:
  description: Documentation
  url: https://perenual.com/docs/api
servers:
  - url: https://perenual.com/api/v2
    description: Production
tags:
  - name: Species
    description: Plant species data
  - name: Pests
    description: Pest and disease data
  - name: Care
    description: Plant care guides
  - name: Maps
    description: Hardiness map data
security:
  - apiKeyAuth: []
paths:
  /species-list:
    get:
      operationId: getSpeciesList
      summary: List plant species
      description: Returns a paginated list of plant species with filtering options.
      tags:
        - Species
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: q
          in: query
          schema:
            type: string
        - name: order
          in: query
          schema:
            type: string
            enum: [asc, desc]
        - name: edible
          in: query
          schema:
            type: boolean
        - name: poisonous
          in: query
          schema:
            type: boolean
        - name: cycle
          in: query
          schema:
            type: string
            enum: [perennial, annual, biennial, biannual]
        - name: watering
          in: query
          schema:
            type: string
            enum: [frequent, average, minimum, none]
        - name: sunlight
          in: query
          schema:
            type: string
            enum: [full_shade, part_shade, sun-part_shade, full_sun]
        - name: indoor
          in: query
          schema:
            type: boolean
        - name: hardiness
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 13
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '429':
          description: Too many requests
  /species/details/{id}:
    get:
      operationId: getSpeciesDetails
      summary: Get plant species details
      description: Returns details for a specific plant species.
      tags:
        - Species
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /pest-disease-list:
    get:
      operationId: getPestDiseaseList
      summary: List pests and diseases
      description: Returns a paginated list of plant pests and diseases.
      tags:
        - Pests
      parameters:
        - name: id
          in: query
          schema:
            type: integer
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: q
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Unauthorized
  /species-care-guide-list:
    get:
      operationId: getCareGuides
      summary: List plant care guides
      description: Returns plant care guides (Supreme tier).
      tags:
        - Care
      parameters:
        - name: species_id
          in: query
          schema:
            type: integer
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: q
          in: query
          schema:
            type: string
        - name: type
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
        '403':
          description: Tier required
  /hardiness-map:
    get:
      operationId: getHardinessMap
      summary: Get hardiness map for species
      description: Returns hardiness map data for a plant species (Supreme tier).
      tags:
        - Maps
      parameters:
        - name: species_id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
        '403':
          description: Tier required
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: key