{ "openapi": "3.0.3", "info": { "title": "Buckhead Energy Public API", "version": "1.1.0", "description": "Read-only structured-data API over Buckhead Energy's oil & gas operator-intelligence dataset. Wraps the same monthly-refreshed PG cache that powers the public website's operator dashboards. Designed for AI agents, partner integrations, and custom data consumers.\n\nAll data is sourced from the Texas Railroad Commission (TX RRC) and the Oklahoma Corporation Commission (OCC) public well-header records, refreshed monthly. Live commodity prices come from a third-party market-data feed.\n\n**No authentication required.** Subject to standard rate-limiting (~60 req/min per IP).", "contact": { "name": "Buckhead Energy", "url": "https://www.buckheadenergy.com/", "email": "land@buckheadenergy.com" }, "license": { "name": "CC-BY-4.0", "url": "https://creativecommons.org/licenses/by/4.0/" } }, "servers": [ { "url": "https://www.buckheadenergy.com/api/v1", "description": "Production" } ], "tags": [ { "name": "operators", "description": "Per-operator profile + activity data" }, { "name": "state", "description": "State-level rollups: snapshots, leaderboards, top wells, permits, counties" }, { "name": "formations", "description": "Per-formation deep-dive data (TX + OK)" }, { "name": "commodities", "description": "Live oil & gas spot prices" } ], "paths": { "/operators/{slug}": { "get": { "tags": [ "operators" ], "summary": "Get operator profile + activity counts", "description": "Returns operator profile (when in directory) plus summary counts across all four activity datasets (permits, recent spuds, new producers, DUCs).", "parameters": [ { "$ref": "#/components/parameters/OperatorSlug" } ], "responses": { "200": { "description": "Operator data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "getOperatorProfile" } }, "/operators/{slug}/permits": { "get": { "tags": [ "operators" ], "summary": "Get operator's TX + OK drilling permits (last 24 months)", "parameters": [ { "$ref": "#/components/parameters/OperatorSlug" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Permit list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermitListEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "operationId": "getOperatorPermits" } }, "/operators/{slug}/recent-activity": { "get": { "tags": [ "operators" ], "summary": "Get operator's consolidated recent drilling activity", "description": "Returns the operator's last-24mo permits, last-90d spuds, last-6mo new producers, and current DUC inventory in one response.", "parameters": [ { "$ref": "#/components/parameters/OperatorSlug" } ], "responses": { "200": { "description": "Activity dashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "getOperatorRecentActivity" } }, "/state/{state}/snapshot": { "get": { "tags": [ "state" ], "summary": "Full state oil & gas industry snapshot", "description": "Aggregate dashboard: counts (permits, DUCs, spuds, new producers, counties, formations) plus top 10 operators / counties / formations and latest 10 permits / spuds / new producers / DUCs.", "parameters": [ { "$ref": "#/components/parameters/State" } ], "responses": { "200": { "description": "State snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnapshotEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "operationId": "getStateSnapshot" } }, "/state/{state}/operators": { "get": { "tags": [ "state" ], "summary": "Top operators leaderboard by total well count", "parameters": [ { "$ref": "#/components/parameters/State" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Operator leaderboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorLeaderboardEnvelope" } } } } }, "operationId": "getTopOperators" } }, "/state/{state}/top-wells": { "get": { "tags": [ "state" ], "summary": "Top 500 oil + 500 gas producing wells by latest monthly volume", "parameters": [ { "$ref": "#/components/parameters/State" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "oil", "gas" ] }, "description": "Optional: return only one category" } ], "responses": { "200": { "description": "Top wells", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopWellsEnvelope" } } } } }, "operationId": "getTopProducingWells" } }, "/state/{state}/permits": { "get": { "tags": [ "state" ], "summary": "Recent state-wide drilling permits (last 24 months)", "parameters": [ { "$ref": "#/components/parameters/State" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Permit list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermitListEnvelope" } } } } }, "operationId": "getStateRecentPermits" } }, "/state/{state}/counties": { "get": { "tags": [ "state" ], "summary": "County-level drilling activity rankings", "parameters": [ { "$ref": "#/components/parameters/State" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "County rankings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountyListEnvelope" } } } } }, "operationId": "getCountyDrillingActivity" } }, "/formations/{state}/{slug}": { "get": { "tags": [ "formations" ], "summary": "Per-formation deep-dive (well count, top operators, recent permits, DUCs)", "parameters": [ { "$ref": "#/components/parameters/State" }, { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,160}$" }, "description": "Formation slug (lowercase, hyphenated)", "example": "wolfcamp" } ], "responses": { "200": { "description": "Formation detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FormationEnvelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "operationId": "getFormationDetail" } }, "/commodities/spot": { "get": { "tags": [ "commodities" ], "summary": "Live WTI Crude + Henry Hub Natural Gas spot prices", "responses": { "200": { "description": "Spot prices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommoditiesEnvelope" } } } } }, "operationId": "getCommoditySpotPrices" } }, "/api/v1/payors": { "get": { "summary": "Search operators/payors by name (the company on a royalty check stub)", "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "description": "Company name or fragment" } ], "responses": { "200": { "description": "Registry matches with profile/sell URLs and national well counts" } } } }, "/api/v1/permits/{state}/{county}": { "get": { "summary": "Recent drilling permits for a county (trailing 24 months)", "parameters": [ { "name": "state", "in": "path", "required": true, "schema": { "type": "string" }, "description": "2-letter state code" }, { "name": "county", "in": "path", "required": true, "schema": { "type": "string" }, "description": "County name or page slug" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500 } } ], "responses": { "200": { "description": "Permit filings, newest first, with dataAsOf" } } } } }, "components": { "parameters": { "OperatorSlug": { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,160}$" }, "description": "Operator slug (lowercase, hyphenated). Example: pioneer-natural-resources, exxonmobil, eog.", "example": "exxonmobil" }, "State": { "name": "state", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "TX", "OK" ] }, "description": "Two-letter state code", "example": "TX" }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "Max records to return (default varies per endpoint)" } }, "responses": { "BadRequest": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Meta": { "type": "object", "properties": { "apiVersion": { "type": "string", "example": "1.0" }, "dataAsOf": { "type": "string", "nullable": true, "format": "date", "description": "Date the underlying PG cache was last refreshed" }, "source": { "type": "string", "description": "Authoritative data source" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer" }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "OperatorProfile": { "type": "object", "properties": { "slug": { "type": "string" }, "companyName": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true } } }, "OperatorEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "profile": { "$ref": "#/components/schemas/OperatorProfile" }, "counts": { "type": "object", "properties": { "permits24mo": { "type": "integer" }, "recentSpuds90d": { "type": "integer" }, "newProducers6mo": { "type": "integer" }, "ducs": { "type": "integer" }, "totalActivityRecords": { "type": "integer" } } }, "statesActive": { "type": "array", "items": { "type": "string" } }, "countyBreakdown": { "type": "array", "items": { "type": "object" } }, "formationBreakdown": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Permit": { "type": "object", "properties": { "operatorSlug": { "type": "string", "nullable": true }, "permitDate": { "type": "string", "format": "date", "nullable": true }, "apiNumber": { "type": "string", "nullable": true }, "county": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "wellName": { "type": "string", "nullable": true }, "formation": { "type": "string", "nullable": true }, "lateralLength": { "type": "integer", "nullable": true } } }, "PermitListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Permit" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ActivityEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "permits": { "type": "array", "items": { "$ref": "#/components/schemas/Permit" } }, "recentSpuds": { "type": "array", "items": { "type": "object" } }, "newProducers": { "type": "array", "items": { "type": "object" } }, "ducs": { "type": "array", "items": { "type": "object" } }, "countyBreakdown": { "type": "array", "items": { "type": "object" } }, "formationBreakdown": { "type": "array", "items": { "type": "object" } }, "statesActive": { "type": "array", "items": { "type": "string" } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "SnapshotEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "state": { "type": "string" }, "counts": { "type": "object" }, "topOperators": { "type": "array", "items": { "type": "object" } }, "topCounties": { "type": "array", "items": { "type": "object" } }, "topFormations": { "type": "array", "items": { "type": "object" } }, "recentPermits": { "type": "array", "items": { "type": "object" } }, "recentSpuds": { "type": "array", "items": { "type": "object" } }, "newProducers": { "type": "array", "items": { "type": "object" } }, "ducs": { "type": "array", "items": { "type": "object" } }, "dataAsOf": { "type": "string", "format": "date", "nullable": true } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "OperatorLeaderboardEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "TopWell": { "type": "object", "properties": { "category": { "type": "string", "enum": [ "oil", "gas" ] }, "rank": { "type": "integer" }, "leaseName": { "type": "string", "nullable": true }, "wellName": { "type": "string", "nullable": true }, "leaseId": { "type": "string", "nullable": true }, "apiNumber": { "type": "string", "nullable": true }, "operatorName": { "type": "string", "nullable": true }, "operatorSlug": { "type": "string", "nullable": true }, "county": { "type": "string", "nullable": true }, "oilBbl": { "type": "number", "nullable": true }, "gasMcf": { "type": "number", "nullable": true }, "reportMonth": { "type": "string", "format": "date", "nullable": true } } }, "TopWellsEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "oilRows": { "type": "array", "items": { "$ref": "#/components/schemas/TopWell" } }, "gasRows": { "type": "array", "items": { "$ref": "#/components/schemas/TopWell" } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "CountyListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "FormationEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "formation": { "type": "object" }, "recentPermits": { "type": "array", "items": { "$ref": "#/components/schemas/Permit" } }, "ducs": { "type": "array", "items": { "type": "object" } } } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "CommoditiesEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "oil": { "type": "object", "properties": { "benchmark": { "type": "string", "example": "WTI Crude" }, "price": { "type": "number", "nullable": true }, "unit": { "type": "string", "example": "USD per barrel" } } }, "naturalGas": { "type": "object", "properties": { "benchmark": { "type": "string", "example": "Henry Hub" }, "price": { "type": "number", "nullable": true }, "unit": { "type": "string", "example": "USD per MMBtu" } } } } }, "meta": { "allOf": [ { "$ref": "#/components/schemas/Meta" }, { "type": "object", "properties": { "asOf": { "type": "string", "format": "date", "nullable": true }, "isMockData": { "type": "boolean" } } } ] } } } } }, "x-mcp": { "url": "https://www.buckheadenergy.com/mcp", "transport": "streamable-http", "discovery": "https://www.buckheadenergy.com/.well-known/mcp.json", "note": "A native Model Context Protocol server exposes the same data as MCP tools." } }