Buckhead Energy Encyclopedia API

openapi: 3.2.0
info:
  title: Buckhead Energy Public Encyclopedia API
  version: 3.0.0
  description: 'Read-only JSON over oil & gas metrics Buckhead Energy computes: state and county drilling-activity counts, permit-to-spud and spud-to-production cycle times, DUC aging, lateral-length trends, production bands, county momentum scores, operator leaderboards by wells operated, and county / formation leaderboards. Designed for AI agents, partner integrations, and custom data consumers.


    Coverage: 24 U.S. states (TX, OK, NM, ND, CO, WY, CA, KS, MS, UT, IL, MT, AL, AR, IN, KY, LA, MI, NE, OH, PA, SD, TN, WV). Figures are Buckhead Energy analysis of public oil and gas data. The derived metrics (activity counts, cycle times, DUC aging, lateral trends, production bands, momentum) and the leaderboards are recomputed daily; the county production volumes that momentum reads are updated monthly.


    **Aggregates only.** The API never returns per-well records (no API numbers, well or lease names) and never returns commodity prices. Every list is capped at 25 rows.


    **Drilling activity by state and county only.** Permits, spuds, first production, DUCs, cycle times and lateral trends are published only as state and county counts. No drilling-activity figure is attributed to an operator, and nothing is finer than a county. Operator endpoints return wells operated and producing wells. Counts resting on fewer than 3 wells, and percentiles resting on fewer than 5, are withheld (null).


    **No authentication required.** Subject to standard rate-limiting (100 req/min per IP, 5,000 req/day per IP, 10 concurrent per IP). The daily limit is shared by REST and MCP, and both limits apply across all server instances. Responses include X-Request-ID and X-RateLimit-* headers; 429 includes Retry-After. Responses are bounded to 1 MiB and 5,000 array entries, with a 15-second execution deadline.'
  contact:
    name: Buckhead Energy
    url: https://www.buckheadenergy.com/
    email: land@buckheadenergy.com
servers:
- url: https://www.buckheadenergy.com/api/v1
  description: Production
tags:
- name: encyclopedia
  description: Oil & Gas Encyclopedia — root-slug definition pages (educational)
paths:
  /encyclopedia:
    get:
      tags:
      - encyclopedia
      summary: List all Oil & Gas Encyclopedia term pages
      description: Returns every encyclopedia definition page (slug, term, category, url). Fetch one in full at /encyclopedia/{slug}.
      responses:
        '200':
          description: List of term pages
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        slug:
                          type: string
                        term:
                          type: string
                        category:
                          type: string
                        url:
                          type: string
                  meta:
                    type: object
      operationId: getEncyclopediaTerms
  /encyclopedia/{slug}:
    get:
      tags:
      - encyclopedia
      summary: Get one Oil & Gas Encyclopedia term page
      description: Returns the full definition, sections, FAQ, and related terms for a single encyclopedia page by slug (e.g. rule-of-capture).
      parameters:
      - name: slug
        in: path
        required: true
        description: Term slug (lowercase, hyphenated)
        schema:
          type: string
          pattern: ^[a-z0-9-]{1,160}$
      responses:
        '200':
          description: Full term page
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      slug:
                        type: string
                      term:
                        type: string
                      h1:
                        type: string
                      category:
                        type: string
                      url:
                        type: string
                      definition:
                        type: string
                      sections:
                        type: array
                      faqs:
                        type: array
                      related:
                        type: array
                  meta:
                    type: object
        '404':
          description: No term with that slug
      operationId: getEncyclopediaTerm
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 metrics as MCP tools.