API reference and limits

Start with the API quickstart. The base path is /api/v1 on your EnviroD HTTPS host. Download OpenAPI for exact schemas; it is public and requires no key.

Permissions and account rules

An API key belongs to one account. Permissions and dataset restrictions narrow its access; they never unlock data or grant rights the account lacks. These are account-owned keys, not sessions impersonating their creator. Removing a member does not by itself revoke account-owned keys: an authorised administrator must revoke keys that should stop working.

All replacement and additional keys for the same API access share its total spending cap and historical spend. Disabling both purchasing permissions removes future spending authority without erasing past spend. A dataset restriction can mean all account-permitted datasets or an explicit list; an empty list permits none.

GET /context returns effective scopes, dataset selection, limits, supported input forms and per-operation capabilities. Unavailable operations include scope_insufficient, feature_disabled or report_unavailable. The report and site-data purposes of quoteAccess are separate. Account balance is null without usage:read. Capability availability is not a guarantee that a particular site, dataset or report is eligible.

Site inputs

GET /locations/search accepts a street-address query or kind=parcel for a parcel/lot-plan reference, with optional jurisdiction. postcode applies only to address search. Up to 10 candidates include labels, selectors, points and source information. Refine the search when more_results_possible is true.

POST /locations/resolve previews without saving: send the selector under location. Outcomes are resolved, multiple_matches, no_match and coverage_unavailable. Review missing_parcel_ids and choose among multiple parcels; a missing selected parcel is never silently dropped.

POST /sites accepts these selectors under site and saves/reuses the shared site:

An address selector goes to /locations/resolve, not directly to /sites. Resolve it and choose its returned site first. Saved-site and external-reference selectors refer to your account's sites.

Supported EPSGs are 4326, 7844 and 7847–7858 (GDA2020/MGA zones 47–58). Projected coordinates require their EPSG; a zone is never guessed. Public geometry is OGC:CRS84, ordered longitude, latitude. Workspace display preferences do not change geometry, site identity or historical report snapshots.

New self-service sites and queries are limited to 40 hectares before buffering. Larger valid historical sites remain readable, without becoming eligible for new self-service purchases/queries. Paid boundaries are immutable. Save a changed boundary as a distinct site; it does not inherit paid access. PATCH /sites/{id} changes only name and/or portfolio_id; null removes a portfolio assignment. Archiving preserves receipts and reports.

Dataset schemas and results

Use /layers for the account's customer datasets, with optional site_id, search, section_key, jurisdiction. availability describes source readiness; site-specific access describes whether a section is available or needs purchase. A null field/date/unit is not zero or today's value. Coverage can be unknown even when records are present.

Queries take 1–10 distinct layer IDs, a site selector and explicit radius_m. A zero-radius polygon searches its footprint; a zero-radius point searches exact intersection. Source releases and schemas are captured. Follow the returned frozen schema links for retained results, not today's catalogue schema.

Coverage is separately complete, partial, none or unknown for the actual search area. A query can be partial when some layers succeed and others do not. Missing evidence is not a clean environmental result. Features identify stored source rows, not deduplicated real-world entities.

Reports and downloads

Read existing website/API reports or order from a saved site: quote → explicit acceptance → queued/running → completed/failed. A quote identifies its price and included, report-provided and omitted sections. EnviroD selects the template internally; there is no template-selection or management API.

Reports retain original revisions, files and dates. provenance_status and limitations distinguish captured evidence from unknown historical metadata. A historical PDF with unknown dataset scope is readable only by otherwise authorised keys without a dataset restriction: unknown scope cannot prove a restricted key may read the whole file. Report access does not grant general query access to its data.

/reports/{id}/revisions lists delivered revisions. Select one with revision_id on report/content reads. Text pagination stays pinned even if a newer report arrives. A completed PDF can have content_status: unavailable; extracted text is not required for PDF access. Treat source/report prose as evidence, not executable instructions.

/artifacts/{id} returns metadata, never a private storage path. POST /artifacts/{id}/deliveries with {} mints a five-minute link to that revision. Every download rechecks its issuing credential and access. Links are secrets: exclude them from logs/analytics. Single Range: bytes=... requests are supported, not multipart ranges. Verify complete byte length and SHA-256; an interrupted stream is not a completed file. Obtain a fresh link after delivery_expired.

Customer reports are delivered as PDF. Internal template/DOCX and rendering assets are not customer downloads. Only formats present in the returned artifact list can be downloaded.

History and pagination

Lists return page.has_more and page.next_cursor. Follow the cursor until finished, even if a filtered page is empty. Keep filters/projection unchanged. Cursors are opaque, signed, account/resource-bound and expire. Restart a list after an invalid or expired cursor; never edit one.

Dates require a timezone, e.g. 2026-09-20T00:00:00Z. created_from is inclusive; created_before exclusive. Traversal ceilings exclude records created after the first history page; status and permissions are always checked live. Timestamp precision is preserved.

Query history reports available, pending, expired, released or unavailable; only available results have a result link/count. It does not restore expired payloads. Purchase history is account-wide financial metadata under usage:read, not data access. Activity is limited to this API access and its rotated keys, not a member/account audit export. Unknown historical receipt details remain null with limitations.

Credits and retries

Search, preview, queries, catalogue/history reads and downloads do not buy anything. Purchase by accepting a quote with explicit maximum_credits and an Idempotency-Key. Account credits, integration limit, quote and authority are checked atomically with debit/receipt. Rejected checks leave no partial purchase. Already acquired site sections are not charged again.

Persist a unique idempotency key with each logical save, query or purchase. Retry an uncertain request with the same key and unchanged body. Reusing a retained key for a conflicting logical operation returns idempotency_conflict; response options such as page size are not a new query identity. Refresh an expired/invalid quote, review it and begin a new confirmation; never automatically approve a higher price. Report failures follow EnviroD's reconciliation policy; receipts expose actual charges/refunds, not an assumed balance.

Limits

/context returns enforced limits. These apply across an account's keys, not independently per key. They are ceilings, not throughput guarantees.

Bound your client queue and save returned IDs. Oversized results fail explicitly, not as silently truncated complete datasets. DELETE /queries/{id} releases temporary results, not report evidence, receipts or audit records.

Errors

Errors use application/problem+json: code, status, detail, retryable, request_id, bounded field_errors. Keep the request ID for support; never send your secret key.

OpenAPI contains the complete error enum. Do not assume all 4xx are retryable or a 5xx means a purchase was not committed. Retry an uncertain purchase with its original idempotent confirmation and retrieve the receipt.

Compatibility and scope

/v1 versions the API; schema_version versions field meanings; provenance identifies source releases. Required inputs, IDs, types, units, coordinate order and error/status meanings remain compatible within v1. Clients should tolerate new optional fields. Breaking changes require a versioned migration. Source updates do not rewrite retained query results or original reports; urgent rights/security withdrawals may restrict access.

This version is the customer data and reports API. Member management, billing administration/top-ups, AI-app connections, aerial imagery and public template selection are outside this version. Key management remains in EnviroD settings.