Wells Intelligence API

Programmatic access to oil and gas well data, drilling permits, and monthly production history. Well and production endpoints are state-aware for Texas and New Mexico; drilling permits are Texas-only for now.

Base URL: https://wells.clearforkintelligence.com/api/v1

API access is included in the Operator ($249/mo) and Enterprise ($499/mo) tiers. The Permits endpoints are Enterprise-only.

Get an API key

API access requires a key in the format cfork_live_<32 hex chars>.

  1. Sign in to the app at wells.clearforkintelligence.com
  2. Click Support in the top tab bar
  3. Scroll down to the API Access panel
  4. Enter a name for the key (e.g. Field laptop, MCP server, CI) and click Generate Key
  5. Copy the key immediately. It's shown only once.

Treat the key like a password. Each key can be revoked at any time from the same panel; revoked keys stop working within seconds. The panel shows the last time each key was used, so you can spot inactive keys before rotating.

If you don't see the API Access panel inside Support, your tier doesn't include API access yet. Upgrade to Operator or Enterprise from inside the product.

Authentication

Send the key as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer cfork_live_..." \
  https://wells.clearforkintelligence.com/api/v1/health

For local scripts and agents, the API also accepts the same key in X-API-Key.

Every endpoint except /health requires authentication. Missing or invalid keys return 401 Unauthorized.

State and API IDs

State-aware endpoints accept state=tx or state=nm; values are case-insensitive. Omit state to default to Texas.

You can also pass canonical IDs in path or batch values:

  • Texas: TX:49534061 or raw 49534061
  • New Mexico: NM:3001548597 or raw 3001548597 with state=nm

Canonical IDs win over a conflicting state query/body value. New Mexico API numbers are 10 digits and typically start with 30; Texas API values in this service are stored as the RRC-style API value without a state prefix.

Quickstart

A 60-second walkthrough using curl:

# Set your key in the environment
export CFORK_KEY="cfork_live_..."
export CFORK_BASE="https://wells.clearforkintelligence.com/api/v1"

# Health check (the only unauthenticated endpoint)
curl $CFORK_BASE/health

# Look up a single well (Formentera Operations, Winkler County)
curl -H "Authorization: Bearer $CFORK_KEY" \
  $CFORK_BASE/well/49534061

# Look up a New Mexico well by state parameter or canonical ID
curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/well/3001548597?state=nm"

curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/well/NM:3001548597"

# Search by operator + county (case-insensitive)
curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/wells/search?operator=Formentera&county=Winkler&limit=10"

curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/wells/search?operator=OXY&county=Lea&state=nm&limit=10"

# Wells within 2 miles of a point
curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/wells/by-radius?lat=31.967&lon=-102.8692&radius_miles=2"

# Monthly production history (last 6 months)
curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/well/49534061/production?start_month=202509"

Python: official CLI + SDK

We ship a Python package (clearfork) that wraps the API and includes the command-line tools. It is distributed to Operator and Enterprise subscribers as a wheel file from inside the app.

To download it:

  1. Sign in to Clearfork.
  2. Open Support.
  3. Go to API Access.
  4. Click Download CLI.

The wheel will look like clearfork-0.1.2-py3-none-any.whl. It requires Python 3.9 or newer.

Install with pipx:

python3 -m pip install --user pipx
python3 -m pipx ensurepath
python3 -m pipx install ./clearfork-0.1.2-py3-none-any.whl

Or install into a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install ./clearfork-0.1.2-py3-none-any.whl

Save your API key once:

clearfork auth set-key cfork_live_...
clearfork auth status

You can also use an environment variable instead of saving the key:

export CLEARFORK_API_KEY=cfork_live_...

Common CLI commands:

# Single well lookup
clearfork wells get 49534061

# State-aware calls default to Texas, but can use canonical IDs or --state
clearfork wells get TX:49534061
clearfork wells get NM:3001548597
clearfork wells get 3001548597 --state nm

# Search wells by operator, county, field, or bounding box
clearfork wells search --operator Formentera --county Winkler --limit 10
clearfork wells search --state TX --operator Formentera
clearfork wells search --state nm --operator OXY --county Lea

# Radius search
clearfork wells radius --lat 31.967 --lon -102.8692 --miles 2 --table
clearfork wells radius --state nm --lat 32.7 --lon -103.4 --miles 5 --table

# Monthly production history
clearfork wells production 49534061 --start 202509 --json
clearfork wells production NM:3001548597 --json

# Batch well lookup from a CSV with API numbers in the first column
clearfork wells batch apis.csv --csv
clearfork wells batch mixed_canonical_ids.csv --json

# Drilling permits (Enterprise only)
clearfork permits search --operator Formentera --county Winkler --limit 10
clearfork permits get 914743 --json

# Usage for your API key
clearfork usage

Most commands support --table (default), --json, and --csv output.

Use the Python SDK directly when you want to call Clearfork from scripts:

from clearfork.client import WellsClient

with WellsClient(api_key="cfork_live_...") as client:
    well = client.get_well("49534061")
    nearby = client.radius_search(lat=31.967, lon=-102.8692, radius_miles=2)
    production = client.get_production("49534061")

The same wheel also installs clearfork-mcp, which lets Claude Code, Cursor, and other MCP-capable tools call the API. For setup, see MCP setup below.

Endpoints

GET /health

Status check. No auth required.

{ "status": "ok", "version": "v1" }

GET /well/<api>

Look up a single well by API number.

Param Type Description
api path Well API number (no dashes), or canonical ID like TX:49534061 or NM:3001548597
state query Optional state postal abbreviation: tx or nm. Defaults to tx when omitted. 
curl -H "Authorization: Bearer $CFORK_KEY" \
  $CFORK_BASE/well/49534061
{
  "data": {
    "canonical_well_id": "TX:49534061",
    "state": "TX",
    "api": "49534061",
    "well_type": "OIL",
    "well_status": "producing_oil",
    "operator_name": "FORMENTERA OPERATIONS LLC",
    "field_name": "KEYSTONE (WOLFCAMP)",
    "county_name": "Winkler",
    "latitude": 31.967,
    "longitude": -102.8692,
    "total_depth": 8277,
    "lease_name": "WHITING NORTH 26",
    "first_production": 201805,
    "last_production": 202602,
    "months_producing": 92,
    "total_oil": 68511,
    "total_gas": 0,
    "peak_oil": 2981,
    "peak_gas": 0,
    "latest_oil": 466,
    "latest_gas": 0,
    "recent_avg_oil": 358.6667,
    "recent_avg_gas": 0,
    "sb1150_exposed": false
  }
}

Volumes: oil and water in barrels, gas in mcf, where those fields are available. latitude is positive, longitude is negative (standard). Use canonical_well_id when storing wells outside a Texas-only workflow; API numbers are not guaranteed to be globally unique across states.

GET /wells/search

Search wells with filters. At least one of bbox, operator, county, or field is required.

Param Description
bbox min_lon,min_lat,max_lon,max_lat (negative longitudes). Max 2° × 2° (~140 mi).
operator Partial match, case-insensitive (e.g. Formentera matches FORMENTERA OPERATIONS LLC)
county Exact county name, case-insensitive (e.g. Midland, Lea)
state State postal abbreviation: tx or nm. Defaults to tx.
field Partial match, case-insensitive
well_type OIL, GAS, or OIL/GAS
well_status e.g. producing_oil, plugged_oil, shut_in_oil, dry_hole
sb1150 true to filter to SB-1150-exposed (zombie) wells
limit 1–500 (Operator: 100, Enterprise: 500), default 100
offset Pagination offset 
curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/wells/search?operator=Formentera&county=Winkler&limit=50"
{
  "data": [ /* array of well objects, same shape as /well/:api */ ],
  "meta": {
    "total": 195,
    "limit": 50,
    "offset": 0,
    "state": "TX"
  }
}

Sorted by total_oil DESC NULLS LAST. Use offset to paginate.

GET /wells/by-radius

Find wells within a radius of a point. The endpoint is state-aware; pass standard negative longitudes for both Texas and New Mexico.

Param Description
lat Latitude (required)
lon Longitude, standard negative (required)
state State postal abbreviation: tx or nm. Defaults to tx.
radius_miles Default 5, max 25
operator Optional partial-match filter
well_status Optional exact-match filter
limit 1–500 (Operator: 100, Enterprise: 500), default 100
offset Pagination offset 
curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/wells/by-radius?lat=31.967&lon=-102.8692&radius_miles=2"
{
  "data": [
    {
      "api": "49534061",
      "operator_name": "FORMENTERA OPERATIONS LLC",
      "field_name": "KEYSTONE (WOLFCAMP)",
      "distance_miles": 0,
      "...": "..."
    },
    {
      "api": "49530155",
      "operator_name": null,
      "well_status": "plugged",
      "distance_miles": 0.73,
      "...": "..."
    }
  ],
  "meta": {
    "total": 3,
    "limit": 100,
    "offset": 0,
    "center": { "lat": 31.967, "lon": -102.8692 },
    "radius_miles": 2,
    "state": "TX"
  }
}

Each result includes distance_miles from the search center. Sorted by distance ascending.

POST /wells/batch

Bulk lookup of up to 500 wells by API number (Operator: 100, Enterprise: 500). Pass a top-level state for unprefixed API numbers, or use canonical IDs such as TX:49534061 and NM:3001548597. Mixed-state batches are supported when values are canonical IDs.

curl -X POST -H "Authorization: Bearer $CFORK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state": "TX", "apis": ["49534061", "49533851", "49533768"]}' \
  $CFORK_BASE/wells/batch
{
  "data": [ /* array of well objects */ ],
  "meta": { "total": 3, "requested": 3, "state": "TX", "states": ["TX"] }
}

Mixed-state example:

curl -X POST -H "Authorization: Bearer $CFORK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apis": ["TX:49534061", "NM:3001548597"]}' \
  $CFORK_BASE/wells/batch

Wells not found are absent from the response. Compare meta.total against meta.requested to detect missing rows.

GET /well/<api>/production

Monthly oil and gas production history for a single well.

Param Description
api path. Well API number, or canonical ID like TX:49534061 or NM:3001548597.
state Optional state postal abbreviation: tx or nm. Defaults to tx when omitted.
start_month Optional YYYYMM lower bound (e.g. 202001)
end_month Optional YYYYMM upper bound 
curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/well/49534061/production?start_month=202509"
{
  "data": [
    { "month": 202509, "oil": 372, "gas": 0 },
    { "month": 202510, "oil": 355, "gas": 0 },
    { "month": 202511, "oil": 321, "gas": 0 },
    { "month": 202512, "oil": 255, "gas": 0 },
    { "month": 202601, "oil": 355, "gas": 0 },
    { "month": 202602, "oil": 466, "gas": 0 }
  ],
  "meta": { "api": "49534061", "canonical_well_id": "TX:49534061", "state": "TX", "total_months": 6 }
}

Volumes: oil, water, and condensate in barrels; gas in mcf. water and condensate appear when the serving database contains those columns. Values are allocated monthly volumes where the source state reports production above the well level; they are not guaranteed to be directly metered per-well.

GET /permits/search (Enterprise only)

Search Texas drilling permits. Permits are currently Texas-only; state=nm returns a clear 400 response.

Param Description
operator Partial match, case-insensitive
county County name or numeric RRC county code. Examples: Midland, midland, 329
state Optional. Must be tx; defaults to tx.
since YYYY-MM-DD lower bound on date_received
bbox min_lon,min_lat,max_lon,max_lat
limit 1–500, default 50
offset Pagination offset 
curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/permits/search?operator=Formentera&since=2026-01-01"
{
  "data": [
    {
      "permit_number": 914743,
      "api_number": 16334412,
      "operator_name": "FORMENTERA OPERATIONS LLC",
      "lease_name": "LUCILLE-STX-UNIT-B",
      "well_number": "S727H",
      "county_code": 163,
      "district": 1,
      "total_depth": 10500,
      "date_received": "2026-04-10",
      "issue_date": "2026-04-13",
      "spud_date": null,
      "type_application": "01",
      "directional_well": false,
      "horizontal_well": true,
      "sidetrack_well": false,
      "surface_longitude": -98.9567,
      "surface_latitude": 28.8446
    }
  ],
  "meta": { "total": 11, "limit": 50, "offset": 0 }
}

You can also filter by county and bounding box:

curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/permits/search?county=Winkler&limit=10"

curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/permits/search?bbox=-103.0,31.9,-102.8,32.0&limit=10"

GET /permit/<permit_number> (Enterprise only)

Look up a single drilling permit.

Permits are currently Texas-only; state=nm returns 400 with Permits are currently Texas-only. New Mexico permits arriving soon.

curl -H "Authorization: Bearer $CFORK_KEY" \
  $CFORK_BASE/permit/914743
{
  "data": {
    "permit_number": 914743,
    "api_number": 16334412,
    "operator_name": "FORMENTERA OPERATIONS LLC",
    "lease_name": "LUCILLE-STX-UNIT-B",
    "well_number": "S727H",
    "county_code": 163,
    "district": 1,
    "total_depth": 10500,
    "date_received": "2026-04-10",
    "issue_date": "2026-04-13",
    "spud_date": null,
    "type_application": "01",
    "directional_well": false,
    "horizontal_well": true,
    "sidetrack_well": false,
    "surface_longitude": -98.9567,
    "surface_latitude": 28.8446
  }
}

GET /usage

Your own usage stats: today's call count, all-time count, current tier limit, calls by endpoint.

curl -H "Authorization: Bearer $CFORK_KEY" $CFORK_BASE/usage
{
  "data": {
    "today": 42,
    "total_all_time": 1247,
    "tier": "operator",
    "daily_limit": 100,
    "by_endpoint": [
      { "endpoint": "wells/search", "calls": 30, "total_rows": 2400 },
      { "endpoint": "well/:api", "calls": 12, "total_rows": 12 }
    ]
  }
}

Rate limits

Limits are per Firebase user (shared across all your keys), measured in UTC.

Tier Calls/day Rows/day Calls/min Max page size Permits
Operator ($249/mo) 100 5,000 15 100 —
Enterprise ($499/mo) 1,000 100,000 60 500 ✅

When you hit a limit you get 429 Too Many Requests with details:

{
  "error": {
    "code": "rate_limited",
    "reason": "daily_requests",
    "limit": 100,
    "remaining": 0,
    "rows_remaining": 3200,
    "reset_at": "2026-05-06T00:00:00Z"
  }
}

reason is one of per_minute, daily_requests, or daily_rows. The minute-window resets continuously; daily windows reset at 00:00 UTC.

If you're consistently hitting limits, contact us and we'll figure out the right plan rather than have you fight 429s.

Errors

All errors come back as JSON with an error object:

{
  "error": {
    "code": "missing_filter",
    "message": "Provide at least one: bbox, operator, county, or field"
  }
}
Status When
400 Invalid params (invalid_bbox, bbox_too_large, out_of_range, missing_filter, invalid_param, missing_apis, too_many)
401 Missing or invalid API key
403 Tier doesn't include the requested endpoint (tier_required)
404 Well or permit not found (not_found)
429 Rate-limited (rate_limited)
500 Server-side error. Email kyle@clearforkintelligence.com if persistent (internal_error)

MCP setup for AI agents

The clearfork package includes an MCP (Model Context Protocol) server, so Claude Code, Codex, Claude Desktop, Cursor, and other agent clients can query wells data directly from chat.

After installing the wheel, register the server with your client.

Claude Code (CLI, one-liner):

claude mcp add clearfork -e CLEARFORK_API_KEY=cfork_live_... -- clearfork-mcp

Codex CLI (one-liner):

codex mcp add clearfork --env CLEARFORK_API_KEY=cfork_live_... -- clearfork-mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "clearfork": {
      "command": "clearfork-mcp",
      "env": {
        "CLEARFORK_API_KEY": "cfork_live_..."
      }
    }
  }
}

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "clearfork": {
      "command": "clearfork-mcp",
      "env": { "CLEARFORK_API_KEY": "cfork_live_..." }
    }
  }
}

Restart your client. The agent can now call tools like lookup_well, search_wells, radius_search, and get_production directly. Rate limits and tier gating apply the same as the REST API.

Versioning + change policy

This is API v1. We won't break it once it's stable. While the API is in beta:

  • Additions (new endpoints, new optional params, new response fields): may happen any time, won't break existing clients
  • Removals or breaking changes: announced via email to API users at least 30 days in advance
  • The CLI version is independent of the API version. You'll receive new wheels when meaningful improvements ship

For status updates, breaking-change notices, or to request a new endpoint, email kyle@clearforkintelligence.com.