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; purchases always require a quote and explicit confirmation.

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: do not buy it again. For access_required, request a free quote at POST /access/quotes. Replace example IDs and section keys below with your returned values:

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

Review the quote, then explicitly accept it at POST /access/acquisitions with Authorization, Content-Type: application/json, a durable Idempotency-Key and:

{
  "quote_id": "80d7eb65-2b52-46aa-9212-96e5ff0aa277",
  "maximum_credits": 7
}

Set maximum_credits to the most you approve spending. Persist the request, key and receipt. If the response is lost, retry the identical request with the same key; do not start another purchase. A new or changed quote requires a new logical confirmation.

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. 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 create a report, request a quote at POST /access/quotes:

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

EnviroD selects the applicable configured report. No template selector or preliminary data query is required. Review the quoted price, included sections, report-provided sections and any omitted sections. A report does not automatically buy general query access to its data.

Accept with POST /reports, an Idempotency-Key, and the same quote_id / maximum_credits structure shown above. Save report_id; poll GET /reports/{report_id} until completed or failed. 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 also stops downloads. 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 available text; a usable PDF may have none. 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.