Build on it

API reference

A versioned REST API over every record on the site — wells, permits, operators, production, Texas ownership — with provenance and freshness on every response.

Overview & authentication

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

Every request outside the Public plan carries an x-api-key header. Keys are issued per account and scoped to a plan (see Plans); a missing or invalid key on a gated dataset returns 401 unauthorized, and a valid key below the dataset’s required plan returns 403 forbidden_plan.

Rate limit: 120 requests/minute per key (burst up to 20), enforced per key across all endpoints. Exceeding it returns 429 with error.code: "rate_limited" and a Retry-After header in seconds.

Endpoints

Every family in SPEC §10, grouped as they appear in the client. Detail routes take a numeric id except wells, which also accept the API/UWI.

Endpoint catalog

33 routes

Method	Path	Description	Key params	Min. plan
GET	/coverage	Aggregate counts — wells, operators, states, periods covered.	—	Public
GET	/sources	Registry of upstream agencies and systems the data is sourced from.	filter, sort, cursor, limit	Public
GET	/freshness	Retrieval and publish timestamps per dataset.	—	Public
GET	/schemas	Machine-readable field definitions for every record type.	—	Public
GET	/search	Cross-entity text search across wells, operators, leases and properties.	q, limit	Public
GET	/wells	Well search with the full filter grammar.	filter, sort, cursor, limit	Core
GET	/wells/{id}	Well detail — header, nearby wells, permit and frac-disclosure counts.	—	Core
GET	/operators	Operator directory.	filter, sort, cursor, limit	Core
GET	/operators/{id}	Operator profile with production summary.	—	Core
GET	/leases	Lease search.	filter, sort, cursor, limit	Core
GET	/leases/{id}	Lease detail.	—	Core
GET	/properties	Property search.	filter, sort, cursor, limit	Core
GET	/properties/{id}	Property detail.	—	Core
GET	/permits	Drilling permits.	filter, sort, cursor, limit	Core
GET	/production	Production records at well/lease/property/operator/operator-county grain, with record_status.	filter, sort, cursor, limit	Core
GET	/well-tests	Point-in-time well test rates.	filter, sort, cursor, limit	Core
GET	/well-logs	Well log index — type, depths, external file URL.	filter, sort, cursor, limit	Core
GET	/frac-disclosures	FracFocus hydraulic fracturing disclosures and chemicals.	filter, sort, cursor, limit	Core
GET	/states	State summaries — ranks, latest period, well and operator counts.	filter, sort, cursor, limit	Public
GET	/states/{code}	State detail — top counties, operators and properties.	—	Public
GET	/counties	County summaries.	filter, sort, cursor, limit	Public
GET	/owners	Texas mineral/royalty owners from county appraisal districts.	filter, sort, cursor, limit	Texas Enriched
GET	/mineral-interests	Texas mineral interests — decimal interest, appraisal value, legal description.	filter, sort, cursor, limit	Texas Enriched
GET	/purchasers	Texas crude/gas purchasers.	filter, sort, cursor, limit	Texas Enriched
GET	/sales	Texas Comptroller severance-tax sales filings.	filter, sort, cursor, limit	Texas Enriched
GET	/map/wells	Individual well points inside a bounding box, for the map view.	bbox, filter, limit	Core
GET	/map/clusters	Deterministic well clusters inside a bounding box at a zoom level.	bbox, zoom, filter	Core
GET	/tiles/wells/{z}/{x}/{y}.mvt	Mapbox Vector Tile of wells for the given tile coordinate.	—	Core
GET	/forecasts/{entity_type}/{id}	Decline-curve forecast for a well, lease, property or operator.	—	Core
POST	/valuations	Compute a DCF or market-multiple valuation for an entity.	body: entity_type, entity_id, ownership_decimal, oil_price_usd, gas_price_usd, discount_rate	Core
POST	/exports	Queue an async export job for a dataset with the current filter/sort/params.	body: dataset, format, params	Core
GET	/exports/{job_id}	Poll an export job's status; carries the download URL once completed.	—	Core
DELETE	/exports/{job_id}	Cancel a queued or running export job.	—	Core

/search, /states and /counties aren’t registered in the contract’s dataset-to-plan table; they are shown here as Public in line with §5.3’s “aggregate summaries” scope. Confirm with the API owner before treating that as authoritative access-control copy.

Filter grammar

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.

GET /v1/wells?filter=state_code:eq:TX&filter=cum_oil_bbl:gt:100000&filter=status:in:producing|shut_in

Operators

12 ops

Op	Meaning
eq	Exact match.
neq	Excludes exact match.
contains	Case-insensitive substring match.
ncontains	Excludes case-insensitive substring match.
lt	Less than.
lte	Less than or equal to.
gt	Greater than.
gte	Greater than or equal to.
in	Matches any of a list of values, pipe-joined.
between	Inclusive range — two pipe-joined values, low then high.
is_null	Field is null or missing. No value.
not_null	Field is present. No value.

sort=field sorts ascending, sort=-field descending. Pagination is cursor-based: cursor is an opaque token from the previous response’s meta.next_cursor; limit caps the page size at 500 (default 50).

Response envelope

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

List envelope

{
  "data": [
    {
      "id": 48213,
      "api_number": "4212330001",
      "name": "SPRABERRY UNIT 12",
      "operator_name": "PIONEER NATURAL RESOURCES",
      "state_code": "TX",
      "county": "Midland",
      "status": "producing",
      "cum_oil_bbl": 184220
    }
  ],
  "meta": {
    "next_cursor": "eyJvIjo1MH0",
    "total": 4821,
    "total_capped": false,
    "returned": 50,
    "source_period": "2026-05",
    "retrieved_at": "2026-06-02T14:05:00Z",
    "published_at": "2026-06-03T09:00:00Z",
    "as_of": "2026-08-05T18:22:11Z"
  }
}

Detail envelope

{
  "data": {
    "id": 48213,
    "api_number": "4212330001",
    "name": "SPRABERRY UNIT 12",
    "status": "producing",
    "nearby_wells": []
  },
  "meta": {
    "source_period": "2026-05",
    "retrieved_at": "2026-06-02T14:05:00Z",
    "published_at": "2026-06-03T09:00:00Z",
    "as_of": "2026-08-05T18:22:11Z"
  }
}

Error envelope

{
  "error": {
    "code": "forbidden_plan",
    "message": "Your plan doesn't include this dataset."
  }
}

Error codes

7 codes

Code	Meaning
unauthorized	Missing or invalid x-api-key.
forbidden_plan	Valid key, but your plan doesn't include this dataset.
not_found	No endpoint or record at this path.
invalid_request	Malformed filter, sort, or parameter.
rate_limited	Too many requests for this key — see Retry-After.
internal	The API failed to answer. Retry shortly.
not_implemented	Specified, but unavailable in this deployment — vector tiles need PostGIS.

Record status

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.

reported: Filed as-is by the source agency or operator — not derived.
allocated: Split from a lease- or unit-level report down to a well, by a documented weight.
estimated: Modeled where no report exists, with method, inputs and confidence stored.
forecast: Projected beyond the reported history by a decline-curve model, versioned.

curl examples

Filtered well search, sorted, limited

curl -H "x-api-key: $TERRALEDGER_KEY" \
  "https://terraledger.alturex.com/api/v1/wells?filter=state_code:eq:TX&filter=cum_oil_bbl:gt:100000&sort=-cum_oil_bbl&limit=50"

Cursor follow-up (same filters, next page)

curl -H "x-api-key: $TERRALEDGER_KEY" \
  "https://terraledger.alturex.com/api/v1/wells?filter=state_code:eq:TX&filter=cum_oil_bbl:gt:100000&sort=-cum_oil_bbl&limit=50&cursor=eyJvIjo1MH0"

Map clusters for a bounding box at a zoom level

curl -H "x-api-key: $TERRALEDGER_KEY" \
  "https://terraledger.alturex.com/api/v1/map/clusters?bbox=-103.5,31.0,-101.0,33.0&zoom=7"

Export lifecycle: queue, poll, download

# 1. Queue the export
curl -X POST -H "x-api-key: $TERRALEDGER_KEY" -H "Content-Type: application/json" \
  -d '{"dataset":"wells","format":"csv","params":{"filter":["state_code:eq:TX"]}}' \
  https://terraledger.alturex.com/api/v1/exports

# 2. Poll until it leaves queued/running
curl -H "x-api-key: $TERRALEDGER_KEY" \
  https://terraledger.alturex.com/api/v1/exports/exp_9f2c1a

# 3. Download once status is "completed"
curl -H "x-api-key: $TERRALEDGER_KEY" -OJ \
  https://terraledger.alturex.com/api/v1/exports/exp_9f2c1a/download

Export lifecycle

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.

Statuses: queued → running → completed | failed | expired. A completed job carries download_url and row_count; a failed job carries error.
Formats: csv, ndjson, geojson. parquet is reserved for large historical exports on the Enterprise plan (SPEC §10).
Expiry: A completed job stays downloadable until its expires_at; after that its status becomes expired and the export must be re-queued.

Plans

Entitlements are per API key. A key’s plan determines which datasets it can read, not which endpoints exist.

Public

Coverage, source registry, freshness report, schemas
Aggregate state and county summaries
Limited record previews

Core

Nationwide wells, permits, operators, leases, properties
Production records, well tests, well logs, frac disclosures
Map, clusters, tiles
Forecasts and valuations
Bounded synchronous exports

Texas Enriched

Mineral/royalty owners and mineral interests
Appraisal values and legal descriptions
Surveys and abstracts
Purchasers and severance-tax sales

API

Metered programmatic access at Texas Enriched data scope
Webhooks
Async exports
Source metadata

Enterprise

Large historical bulk exports
Redistribution rights
Custom SLAs

Hit a 403 forbidden_plan in the browser? See it live on the Texas enrichment page, which requires Texas Enriched.

Search records