API reference

Ohio records: Ohio Department of Natural Resources, Division of Oil and Gas Resources Management. Location quality varies; some records describe proposed or unlocated wells. General-information research data; not intended for resale or site-specific investigation. Attribute ODNR in distributed compilations. Ohio bulk exports are unavailable. Kentucky records: Kentucky Geological Survey. Historical records; current status and location accuracy are not guaranteed. Kentucky bulk exports are unavailable; KGS provides the original archive with its documentation. Florida locations: Florida DEP. Approximate, illustrative reference only; not for engineering, calculations, analysis or legal determinations. Consult approved permits for accurate positions.

Base URL: /api/v1 (same origin as this site) or https://terraledger.ayrical.com/api/v1 externally. The API is versioned by path segment (v1); breaking changes ship as v2 rather than mutating v1 in place.

The Model Context Protocol lets an AI agent call this API as a set of typed tools rather than composing URLs and parsing them back. Terraledger runs an open MCP server at https://terraledger.ayrical.com/api/mcp over Streamable HTTP. It is free and unauthenticated, and it reaches exactly what an anonymous REST caller reaches, under the same rate limit.

Tool results are the envelopes documented below, returned unchanged — an agent sees the same provenance, freshness and record_status the site does, so a derived figure cannot be reported as a regulator filing.

Ordinary read requests work without credentials. Anonymous callers are limited by client address to 60 requests per minute. Send an optional x-api-key for a stable caller identity, a separately assigned limit, async export ownership, or a source-specific record family that requires an audit identity.

An invalid or revoked supplied key returns 401 unauthorized. A key that lacks a reviewed source-specific scope returns 403 forbidden_plan. Rate-limited API responses publish RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 also carries Retry-After in seconds.

Requests accept at most 20 filter clauses, each no longer than 500 characters; q must be 3–200 characters and JSON request bodies are limited to 64 KiB.

Implemented v1 routes, grouped as they appear in the client. Detail routes take a numeric id except wells, which also accept the API/UWI.

Every list endpoint accepts repeatable filter query params in the form filter=<field>:<op>:<value>. Multi-value operators (in, between) join their values with a pipe.

List endpoints return a data array plus a meta block carrying an exact or explicitly capped total, the cursor for the next page, and freshness.

Every production figure carries a record_status so a filing is never read as a calculation. The four statuses are never mingled into one silent series — a chart or export that spans them keeps them as separate, labeled series.

period_type is equally load-bearing. Monthly, quarterly, and annual filings can share the same period start date; they remain separate rows and are never silently summed or interpolated together. Daily-rate analytics return one row per reporting cadence and include the complete source and record-status sets represented by each aggregate.

An export is a job, not a download. POST /exports queues it against a dataset and the same filter/sort/params a list request would use; GET /exports/{job_id} polls it; DELETE /exports/{job_id} cancels a queued or running job.