openapi: 3.1.0
info:
  title: Perenual Care Species 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
servers:
- url: https://perenual.com/api/v2
  description: Production
security:
- apiKeyAuth: []
tags:
- name: Species
  description: Plant species data
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
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: query
      name: key
externalDocs:
  description: Documentation
  url: https://perenual.com/docs/api