Multispecies API — AI Usage Guide

This page provides instructions for AI assistants helping users write code, analyse data, or conduct scientific and forestry modelling using the Multispecies API.

Authoritative documentation

• OpenAPI specification (machine-readable): https://api.multispecies.nz/openapi.json
• Full documentation and Getting Started guide: https://api.multispecies.nz/doc

Instructions for AI assistants

When a user asks you to use the Multispecies API, follow these instructions before writing code or conducting an analysis.

1. Read the OpenAPI specification. Retrieve and inspect https://api.multispecies.nz/openapi.json . Do not rely solely on the /doc page, which is rendered with JavaScript and may not be readable by your browsing tools. If you cannot retrieve the specification directly, try another available method before concluding that it is inaccessible.
2. Read the relevant usage guidance. Consult the Getting Started section and applicable examples in the API documentation. Use the OpenAPI specification as the authoritative source for endpoint names, HTTP methods, parameters, request formats, response schemas, and authentication requirements. Where this page and an example in the specification disagree, follow this page for the points it states explicitly, and the specification for everything else.
3. Identify the appropriate workflow. Select the documented endpoint that matches the user's objective. Do not assume that an endpoint supports a particular operation without checking its specification.
4. Understand the model and its outputs. Check parameter descriptions, units, defaults, and constraints, and the meaning of each output field. Results are model projections, not observations. Do not invent field names, units, scientific relationships, or unsupported capabilities.
5. Produce a useful solution. Tailor the code and analysis to the user's request rather than merely demonstrating a basic API call. For analytical tasks, this may include parameter sweeps, comparisons between species, tables, plots, summary statistics, or sensitivity analysis, where the API supports them.

Hard rules

These constraints are easy to miss in the specification. Follow them exactly.

• Base URL: https://api.multispecies.nz
• No API key is required to call POST /run, POST /run/batch, or POST /run/scenario. Do that for a first test and for users who do not have a key. Do not use GET /health as a substitute for a model run: it only checks that the process is up. Without a key, the limits are 10 requests per minute per client, batches of at most 10 runs, and scenarios of at most 100 combinations. A successful response then sets meta.anonymous to true and includes meta.notice. For higher limits, send a key in the x-api-key header (not Authorization: Bearer, and not a query parameter). An invalid key is rejected. Users can request a key from [email protected].
• Endpoints:
  • POST /run — one JSON object.
  • POST /run/batch — a JSON array of those objects. Each result echoes its request in inputs. Array order is not request order.
  • POST /run/scenario — { "base_request": …, "scenario": { "sweeps": … } }. Each result's inputs holds the swept values for that combination.
  • GET /health — process health check only.
• Required stand inputs live under input_criteria: species, initialStocking, siteIndex, index300, and rotationLength. Climate and calibration fields, including meanAnnualTemperature, belong under growth_parameters. They do not replace site index or 300 Index.
• Species strings are exact lowercase names with spaces. Use "radiata pine", not "radiata_pine" or other invented spellings. Accepted identifiers:
  • radiata pine
  • coast redwood
  • douglas-fir
  • blackwood
  • cupressus macrocarpa (n.i.)
  • cupressus macrocarpa (s.i.)
  • cupressus lusitanica (n.i.)
  • cupressus lusitanica (s.i.)
  • eucalyptus regnans
  • eucalyptus fastigata
  • eucalyptus nitens
  • eucalyptus delegatensis
  • eucalyptus saligna
  (n.i.) and (s.i.) mean North Island and South Island.
• Request shape: unknown properties are rejected. Do not add fields that are not in the schema. Integer fields such as rotationLength must be JSON integers (25), not 25.0. A validation failure is HTTP 422.
• Success: HTTP 200 is not enough. Check that the JSON status field is "OK" before treating results as a valid projection.
• Limits: without a key, 10 requests per minute per client, at most 10 runs per batch, and at most 100 scenario combinations. With a key, 100 requests per minute and at most 5,000 scenario combinations (HTTP 400 if exceeded, HTTP 429 if the rate limit is exceeded). Prefer /run/batch or /run/scenario over many separate /run calls.
• Interpretation: outputs are typical modelled projections for Aotearoa New Zealand, not measurements. Do not present them as carbon-accounting, investment, or planting advice. The licence and disclaimer on the documentation page apply.

Python scripts and analysis

Unless the user requests another language or format, use Python for code examples. Aim to provide complete, runnable scripts suitable for users who may not be professional software developers.

• Include all necessary imports and identify required dependencies, with installation instructions where useful.
• Call the API without an API key unless the user already has one. Do not block a test or an analysis on obtaining a key. If the user supplies a key, send it in the x-api-key header from an environment variable. Never embed a key in source code, never print it, and never place it in the chat. If a call returns HTTP 429, explain the no-key limits and how to request a key.
• Use the request and response formats defined by the OpenAPI specification and the hard rules above. Handle unsuccessful HTTP responses, including 401, 422, 400, and 429, and explain common configuration errors.
• Explain important inputs and assumptions, particularly model parameters the user has not specified. State those assumptions. Do not silently invent values for required fields such as species, site index, or 300 Index.
• For analytical tasks, retrieve and process the results, and provide appropriate visualisation or tabular output. Use libraries such as pandas and Plotly when they add value.
• Stay inside the documented rate and scenario limits.

Running analyses

If the user wants an analysis rather than just a script, and you have the necessary execution tools, network access, and API credentials, perform the analysis and explain the method and results.

If you cannot execute the requests yourself, provide a complete script the user can run. Clearly distinguish actual API results from illustrative examples or expected output. Never claim to have run an analysis that you have not executed.

Handling uncertainty

Make reasonable, explicit assumptions when the user's objective is clear but some optional inputs are unspecified. If a required detail cannot be established from the documentation or the user, explain the uncertainty and ask a focused question. Never silently substitute invented API functionality or unsupported scientific assumptions.

For users

To get started, tell your AI assistant what you want to investigate and reference this page. For example:

Use the Multispecies API, following the instructions at https://api.multispecies.nz/ai, to investigate how mean annual temperature affects predicted carbon yields for different tree species. Write a Python script that performs the analysis and plots the results.

Mean annual temperature is growth_parameters.meanAnnualTemperature. Species, site index, 300 Index, stocking, and rotation length are still required. Replace the example with any question you want to explore. You do not need to know the API endpoints or request formats in advance.