API quickstart

Find a property → save a site → discover data → query or create a report → retrieve your work.

The API uses your existing EnviroD account, sites, data access and credits. You can also retrieve reports created on the website. Reading data or downloading a report does not buy anything. Unlock site data or order a report in one purchase request.

Use the API reference for permissions, input formats, pagination, limits and errors. The OpenAPI contract describes every request and response.

1. Create a key and check access

In your workspace, open Settings → API access → Create API key. An account owner or authorised administrator manages these keys. If API access is not enabled, contact EnviroD.

For this walkthrough, select Read saved sites, Register sites, Discover layers, Run queries on permitted data, Read reports and Download report files. Select Purchase site data access and Create paid reports only if you want those purchases, and set an appropriate spending limit. Read usage and balance lets you retrieve balances and receipts.

Copy the key once into your backend secret store. Never put it in a browser application, URL, source repository or chat. The spending limit caps this API access in total; it uses existing account credits, does not buy credits, and does not reset when you replace the key.

These shell examples use curl and jq. Run them on a trusted machine without shell tracing or verbose HTTP logging. Supply ENVIROD_API_KEY through your secret manager and set ENVIROD_URL to the HTTPS origin you use for EnviroD, without a trailing slash.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $ENVIROD_API_KEY" \
  "$ENVIROD_URL/api/v1/context" | jq

The response shows your account, permissions, spending authority, limits and operation capabilities. A capability means the key is permitted and the service is configured; actual site access, dataset availability and purchase costs are checked on each request. Account balance is shown only with Read usage and balance permission.

2. Find an address and preview the boundary

Replace the example address with your property:

curl --fail-with-body --silent --show-error --get \
  -H "Authorization: Bearer $ENVIROD_API_KEY" \
  --data-urlencode 'query=123 Example Street' \
  --data-urlencode 'jurisdiction=NSW' \
  --data-urlencode 'kind=address' \
  "$ENVIROD_URL/api/v1/locations/search" > addresses.json
jq '.results[] | {label, selector, point}' addresses.json

Choose the correct candidate. This selects the first result only as an example; review its label before proceeding. It sends the returned selector unchanged:

jq '{location: .results[0].selector}' addresses.json > location.json
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $ENVIROD_API_KEY" \
  -H 'Content-Type: application/json' --data @location.json \
  "$ENVIROD_URL/api/v1/locations/resolve" > boundary.json
jq '{status, point, boundary, site, parcels, missing_parcel_ids}' boundary.json

resolved returns the selected site and boundary where one can be established. For multiple_matches, choose the intended parcel IDs and resolve a cadastre selector. For no_match or coverage_unavailable, refine the search or explicitly supply a point or your own boundary. A nearby parcel is not automatically your property. Search and preview do not save a site or spend credits.

You can also resolve longitude/latitude, supported easting/northing with an EPSG code, parcel IDs, an existing site or a custom polygon. See all inputs.

3. Save or reuse the site

Continue only with the boundary you intended. This guard refuses an unresolved or ambiguous result:

jq -e 'if .status == "resolved" and .site != null
  then {site: .site, name: "Example property"}
  else error("Choose and resolve the intended site first") end' \
  boundary.json > site-request.json
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $ENVIROD_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-property-save-01' \
  --data @site-request.json \
  "$ENVIROD_URL/api/v1/sites" > site.json
SITE_ID=$(jq -er '.site.site_id' site.json)

Keep site_id: it is the same saved site used by the website. Repeating the same request with its idempotency key does not create duplicates. Use a new key for a different logical operation. You may attach your own external_reference when saving and use it to find the site later.

For an existing site, use GET /sites?search=... instead of saving another. List portfolios with GET /portfolios; filter sites with portfolio_id. Rename or move a site with PATCH /sites/{site_id}. Archive with DELETE /sites/{site_id}; reports and receipts remain.

4. Discover data and acquire access if needed

curl --fail-with-body --silent --show-error --get \
  -H "Authorization: Bearer $ENVIROD_API_KEY" \
  --data-urlencode "site_id=$SITE_ID" \
  "$ENVIROD_URL/api/v1/layers" > layers.json
jq '.layers[] | {layer_id, name, section_key, access, availability, coverage, schema_url}' layers.json

Follow additional pages if present. Choose layer IDs from the catalogue, not internal map identifiers. Filter by search, section_key or jurisdiction. Each layer includes its field schema, units, source attribution and available dates.

already_available means the site already has that section. A listed layer is available to select; it does not promise that the selected site's buffer contains matching features. For access_required, purchase the section with one POST /access/acquisitions request. Replace the section key with one returned by the catalogue:

{
  "site_id": "615f59d3-b5c2-4f4f-926b-270e9410eef1",
  "section_keys": ["land-use"]
}

Send Authorization, Content-Type: application/json and a durable Idempotency-Key. The response states the credits actually charged and the remaining account balance. Your key must have purchase permission and a spending limit; the account must have enough credits. Persist the request, key and receipt. If the response is lost, retry the identical request with the same key; do not start another purchase.

5. Query the site

Send this to POST /queries, with Authorization, Content-Type: application/json and a new Idempotency-Key. Replace the example site and layer IDs:

{
  "site": { "kind": "saved_site", "site_id": "615f59d3-b5c2-4f4f-926b-270e9410eef1" },
  "layer_ids": ["qld.land_use"],
  "radius_m": 500,
  "page_size": 100,
  "include_geometry": true
}

Use radius_m: 0 to search only inside a polygon; for a point it means exact intersection, not a surrounding area. Positive radii are also capped by each section's limit.

A 202 response is queued or running. Save query_id and poll the returned Location. Prefer: wait=3 allows a short initial wait. Inspect each layer's data_status, reason, coverage, units and provenance before consuming features. no_data is a successful empty result; unavailable is not. Neither an empty result nor incomplete coverage proves absence of environmental risk.

Follow page.next_cursor while page.has_more is true. Keep the same query and projection, including include_geometry; never edit cursors. GET /queries finds previous work and says whether results remain available, expired or released. Query results are retained for 24 hours after completion.

6. Download a map image

After unlocking a section, download the same kind of map image available on the website for this saved site and its saved buffer:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $ENVIROD_API_KEY" \
  "$ENVIROD_URL/api/v1/sites/$SITE_ID/sections/land-use/map-image" \
  --output land-use-map.jpg

Replace land-use with the unlocked section_key from /layers. The response is a 1280 × 900 JPEG with the website's current section style, visible features, legend and scale. It does not include browser-only pinned cards or hidden-feature choices. The key needs Read saved sites and Run queries on permitted data. This download does not charge credits or unlock a section.

7. Create or download a report

Find existing website or API reports with GET /reports?site_id=...&status=completed. Reading one does not generate another report or charge credits.

To order the report configured for your saved site, send POST /reports with a durable Idempotency-Key:

{
  "site_id": "615f59d3-b5c2-4f4f-926b-270e9410eef1"
}

EnviroD selects the applicable configured report and charges your existing credits under the key's spending limit. No template selector or preliminary data query is required. A report does not automatically buy general query access to its data.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $ENVIROD_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-report-01' \
  --data "{\"site_id\":\"$SITE_ID\"}" \
  "$ENVIROD_URL/api/v1/reports" > report.json

Save report_id; poll GET /reports/{report_id} until completed or failed. If the order response is lost, retry the same request and idempotency key. On failure, inspect reason_code and its receipt before deciding to order a new report.

For a completed report, choose the PDF from artifacts. Its metadata includes artifact_id, revision, filename, size and SHA-256. Request a download link:

# Set ARTIFACT_ID to the PDF artifact returned by your report.
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $ENVIROD_API_KEY" \
  -H 'Content-Type: application/json' --data '{}' \
  "$ENVIROD_URL/api/v1/artifacts/$ARTIFACT_ID/deliveries" > delivery.json
DOWNLOAD_URL=$(jq -er '.url' delivery.json)
curl --fail --silent --show-error "$DOWNLOAD_URL" --output report.pdf

The link expires after five minutes and is itself a secret. Revoking the key or removing access stops API-issued download links; it does not revoke a website file URL that was shared separately. Do not send your API key to the download URL. Check the complete file's SHA-256 against delivery.json before treating it as received; discard incomplete files and retry with a fresh link when needed.

GET /reports/{report_id}/content retrieves retained text when available. Reports produced by the current website pipeline are PDF-only through the API, so this route returns content_unavailable for them. GET /reports/{report_id}/revisions finds previous delivered versions. Old reports retain original bytes and dates; missing historical provenance is stated in limitations, never replaced with today's data.

Resume work and troubleshoot

• GET /queries — previous queries and result availability.
• GET /reports — reports, with site, status and date filters.
• GET /purchases — original receipts, charges and refunds.
• GET /activity — activity for this API access, including replacement keys.
• GET /usage — account credits and this API access's spending limit and usage.

Errors include a stable code, retryable and a request_id for support. Respect Retry-After; do not repeatedly retry invalid inputs or missing permission. Read the error and retry reference.