{
  "openapi": "3.1.0",
  "info": {
    "title": "BioPulse API",
    "description": "Global biodiversity intelligence API. GBIF + IUCN + eBird + iNaturalist data synthesis. Species profiles, IUCN conservation status, sighting reports, birding hotspots, migration tracking, endangered species alerts, invasive species detection, marine biodiversity, and field identification. Serves naturalists, wildlife biologists, birdwatchers, conservation orgs, educators, and eco-travel agents. Field guide and optics affiliate links via Amazon included in species/birding endpoints. All endpoints support any language via ?lang=. Pricing: $0.05\u2013$0.15 USDC/call via x402 micropayment.",
    "version": "1.2.0",
    "contact": {
      "url": "https://biopulse-nine.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://biopulse-nine.vercel.app"
    }
  ],
  "paths": {
    "/api/bio/species": {
      "get": {
        "summary": "Species profile",
        "description": "Full species profile: taxonomy (GBIF), IUCN conservation status, range, habitat, biology, threats, cool facts, how to spot",
        "parameters": [
          {
            "name": "species",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Common or scientific name"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Species profile"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Full species profile \u2014 chain after /api/bio/identify for unknown species; pairs with /api/bio/endangered for conservation context"
      }
    },
    "/api/bio/sightings": {
      "get": {
        "summary": "Recent wildlife sightings",
        "description": "Recent citizen science wildlife observations near a location from iNaturalist and GBIF",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "radius",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Radius in km (max 100, default 25)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Sightings report"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Recent sightings \u2014 chain after /api/bio/species to find where species was recently seen; pairs with /api/bio/hotspot for site details"
      }
    },
    "/api/bio/birding": {
      "get": {
        "summary": "Birding intelligence",
        "description": "eBird-powered birding brief for a location \u2014 recent species, notable rarities, hotspots, gear",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "dist",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Search radius in km (max 50, default 25)"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Birding intelligence report"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Dedicated birding endpoint \u2014 pairs with /api/bio/hotspot; field guide and binoculars affiliate links auto-appended"
      }
    },
    "/api/bio/invasive": {
      "get": {
        "summary": "Invasive species alerts",
        "description": "Invasive species threat assessment for a region \u2014 which species are spreading, impacts, control, reporting",
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country, state, province, or region name"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invasive species report"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Invasive species reporting \u2014 chain with /api/bio/hotspot for affected sites; useful for conservation planning agents"
      }
    },
    "/api/bio/endangered": {
      "get": {
        "summary": "Endangered species profile",
        "description": "IUCN Red List deep dive \u2014 conservation status, population, primary threats, conservation actions, how to help",
        "parameters": [
          {
            "name": "species",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Endangered species profile"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "IUCN Red List analysis \u2014 chain after /api/bio/species; pairs with /api/bio/invasive for ecosystem context"
      }
    },
    "/api/bio/hotspot": {
      "get": {
        "summary": "Biodiversity hotspot guide",
        "description": "Best places to experience biodiversity near a location \u2014 nature spots, seasonal calendar, endemic species, gear",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Hotspot guide"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Birding/wildlife hotspot finder \u2014 pairs with TravelPulse for eco-travel planning; chain before /api/bio/sightings for target site"
      }
    },
    "/api/bio/identify": {
      "get": {
        "summary": "Species identification",
        "description": "Help identify a wildlife sighting from text description, location, and group hint \u2014 returns candidates with matching features",
        "parameters": [
          {
            "name": "description",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "What you observed \u2014 size, color, behavior, habitat"
          },
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "bird | mammal | reptile | amphibian | insect | plant | other"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Identification candidates"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Photo/description-based identification \u2014 chain to /api/bio/species for full profile; pairs with /api/bio/hotspot for where to find the identified species"
      }
    },
    "/api/bio/migrate": {
      "get": {
        "summary": "Migration intelligence",
        "description": "What species are migrating through a location right now \u2014 timing, where to watch, seasonal highlights",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Migration intelligence report"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Migration tracking \u2014 pairs with ClimatePulse /api/climate/forecast for weather correlation with migration timing"
      }
    },
    "/api/bio/marine": {
      "get": {
        "summary": "Marine biodiversity",
        "description": "OBIS-powered marine biodiversity intelligence \u2014 ocean occurrence data, coral reef health, megafauna presence, dive/snorkel intelligence for any coastal or ocean location globally",
        "operationId": "bioMarine",
        "security": [
          {
            "x402": []
          }
        ],
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Coastal or ocean location (e.g. Great Barrier Reef, Monterey Bay, Raja Ampat)"
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Marine biodiversity report"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.12,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Marine biodiversity \u2014 OBIS data integration; pairs with TravelPulse for marine eco-travel planning"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 micropayment signature. Send request without header to receive 402 with payment requirements."
      }
    }
  }
}