Wells Intelligence API

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

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

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

# Search by operator + county (case-insensitive)
curl -H "Authorization: Bearer $CFORK_KEY" \
  "$CFORK_BASE/wells/search?operator=Formentera&county=Winkler&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.1-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.1-py3-none-any.whl

Or install into a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install ./clearfork-0.1.1-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

# Search wells by operator, county, field, or bounding box
clearfork wells search --operator Formentera --county Winkler --limit 10

# Radius search
clearfork wells radius --lat 31.967 --lon -102.8692 --miles 2 --table

# Monthly production history
clearfork wells production 49534061 --start 202509 --json

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

# 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

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

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

{
  "data": {
    "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
  }
}

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
  }
}

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
  }
}

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

{
  "data": [ /* array of well objects */ ],
  "meta": { "total": 3, "requested": 3 }
}

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", "total_months": 6 }
}

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 }
}

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"

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
  }
}

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.

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"
  }
}

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.