API & MCP technical reference

Authentication

Present your API key on every request, via either header — Authorization: Bearer sk_... or X-API-Key: sk_.... When both are present, Authorization wins. A missing, malformed, or revoked key is not an error on the versioned /api/v1/* read surface; the request simply resolves to the reduced public view. Keys are issued under Team agreements (bd@nameplatedata.com), shown once at issuance, and stored only as one-way SHA-256 hashes — a lost key is revoked and reissued, never recovered.

Every figure the API returns ties to a source document; claims that could not be verified against a source are refused and recorded rather than published.

Tiers & rate limits

API keys and MCP access are provided under Team agreements. The Pro subscription is workbench-only and does not carry an API key or MCP access; anonymous MCP connections are refused. A request without a key gets the reduced public view at the free rate limit, keyed by client IP.

REST API

Six read endpoints plus a bulk export live under /api/v1/. v1 is a stable contract: additive changes ship within it; breaking changes get a new prefix with a deprecation window. Clients should ignore unknown JSON fields. The interactive schema is at /docs (Swagger) and /redoc.

Conventions

These apply across every endpoint and are not repeated in the per-endpoint tables below.

• Tier field. Every JSON payload echoes the resolved tier (free / team) the response was shaped for. On the free tier, paid fields are present but nulled (or list blocks emptied) so the payload keeps its shape.
• Pagination. List payloads carry total (matches before the page cut), count (rows in this page), and has_more (boolean, more rows exist beyond this page). filters echoes the filter values the server resolved.
• Scores. Model scores are published as integers on a 0-100 scale (an unavailable or tier-withheld score is null). Companion 0-1 values that are not scores — confidence, percentiles, coverage_percent — are not rescaled.
• Units. MW fields are megawatts; dollar amounts are whole USD; dates are ISO-8601 (YYYY-MM-DD for filing/estimate dates, full ISO timestamps for retrieved_at / created_at).
• Response headers. Every response carries X-API-Tier and X-RateLimit-Limit / -Remaining / -Reset (seconds to full refill). Over the limit returns 429 with Retry-After (seconds).

GET /api/v1/health

Liveness and coverage counts. No query parameters. Served to all tiers.

GET /api/v1/me

Identity and entitlement echo. Always returns 200; never gated or rate-limited. No query parameters.

GET /api/v1/projects

Project summary rows for the full tracked portfolio. No query parameters. Free tier keeps identity, status, and MW presence; scores and third-party MW estimates are nulled.

Response: a JSON array of project summary rows.

GET /api/v1/projects/{project_id}

The full project dossier. Path parameter project_id (string). An unknown id returns 404. On the free tier the shape is preserved but every paid signal is withheld: dollar-amount blocks are emptied, score blocks keep their shape with every *_score nulled, and analytic panels are dropped.

Top-level structure

Additional paid analytic panels ride on the dossier and are withheld on the free tier: capital_stack, cost_benchmark, capex_trend, benchmark, investor_brief, risk_history, model_runs, evidence_impacts, tenant_credit, tenant_offtake, risk_trend, irr_dcf, tax_abatement, transaction_comps, interconnect_queue, community_signal, confidence_bands, anomalies, mw_captures, diligence_checklist.

power[] — power / interconnect evidence

cost_estimates[] — cost evidence

financing[] — financing evidence

regulatory_filings[]

timeline[]

evidence_depth_tier

latest_risk — risk-model run (paid)

GET /api/v1/market

Portfolio-wide aggregate rollup. No query parameters. Every breakdown carries the disclosed-vs-undisclosed MW split explicitly — undisclosed MW is reported as absent, never imputed. Free / anonymous callers get counts only: MW magnitudes and the model score are nulled, and the risk-band and score-histogram lists are emptied.

totals

Breakdown row shapes

GET /api/v1/sources/search

Full-text search or browse over the approved source corpus. Returns highlighted excerpts, never full documents (a third-party-copyright guard). Free / anonymous callers get counts only.

Query parameters

Response — sources[] row shape

On the free tier the sources rows are removed and replaced with counts_by_source_type and a detail_available note; total and filters are preserved.

GET /api/v1/export/projects.csv

Streaming CSV of the full portfolio. Team tier only; any lower tier returns 403. No query parameters. Columns: project_id, canonical_name, status, county, state, total_mw, energized_mw, expected_completion, utility.

Data semantics

Wherever scores appear in this reference, they are model ranking signals on a 0-100 scale, not calibrated probabilities.

Status lifecycle

A project's status moves through the lifecycle below. The five italicised states anchor the benchmark stage ladder in code; rumored, delayed, and cancelled are off-ladder states a project can also carry.

• rumored — reported but not confirmed by the operator.
• announced — publicly announced by the operator or sponsor.
• permitting — permits or regulatory filings are in progress.
• under_construction — construction is underway.
• partially_energized — some capacity is energized.
• energized — the project is energized / in service.
• delayed — schedule has slipped materially.
• cancelled — the project has been cancelled.

Evidence depth grades (A-D)

The dossier's evidence_depth_tier is derived live from four core evidence dimensions — MW, a cost estimate, power (utility/interconnect) evidence, a regulatory filing — plus whether an approved source, and an approved primary-tier source, are on file.

• A — Deep file: MW and a cost estimate and power evidence and an approved primary-source filing.
• B — Solid file: MW and (a cost estimate or power evidence) and at least one approved source.
• C — Partial file: at least two of {MW, cost estimate, power evidence, regulatory filing}.
• D — Thin file: everything else — a thin discovery stub with fewer than two core dimensions.

Financing rollup categories

The market view rolls each raw financing_type up to one of six categories (category_key → category_label). A project appears in each category it has evidence for; the none bucket is mutually exclusive with the evidence categories.

• sponsor_capex — Sponsor-announced capex
• corporate_investment — Corporate investment
• real_estate — Real-estate acquisition
• project_financing — Project / construction financing
• other_disclosed — Other disclosed financing
• none — No financing evidence

Holdout finding types

Holdouts are the refusal trail — evidence that was reviewed and deliberately not promoted to booked coverage, each with a recorded reason. Three finding_type values are treated as holdouts:

• project_mw_holdout — an MW figure reviewed and not counted (e.g. it mixed PPA capacity with load).
• capital_candidate_cost_holdout — a capex figure a source implied but never disclosed cleanly.
• project_entity_holdout — an entity relationship that could not be substantiated.

These ride inside the broader enrichment_findings stream, whose queue lanes are ready_to_promote, gap_review, tracked_gap, source_added, and audit_trail.

Risk scores

Risk is a set of ranking signals on a 0-100 scale carrying a model_version. The overall score decomposes into seven sub-scores: regulatory_risk_score, power_risk_score, timing_risk_score, financing_risk_score, site_risk_score, counterparty_risk_score, and data_confidence_risk_score. In the market rollup, risk bands are low (< 34), medium (34-66), and high (≥ 67).

Source types

Each source carries a source_type. The set is open — new types are added as the corpus grows and are not pinned to a fixed enum in code — so treat it as an open string and filter on the values you observe. Common values include news_report, company_filing, and government_record. Use GET /api/v1/sources/search without a query to browse the live set and its counts by type.

MCP server

The MCP server exposes the database to Claude, Cursor, and other agent clients as nine read-only tools over streamable HTTP at https://nameplatedata.com/mcp/. MCP connections authenticate with a Team API key in a request header; anonymous MCP connections are refused, and every data tool requires the Team tier (only get_access_info answers for any caller).

Client setup

Each client points at the same endpoint and passes the key as an X-API-Key header.

# Claude Code
claude mcp add --transport http nameplate https://nameplatedata.com/mcp/ \
  --header "X-API-Key: sk_..."

# Claude Desktop (claude_desktop_config.json) -- via the mcp-remote bridge.
# Claude Desktop's config file launches local processes only and cannot attach
# headers to a remote URL directly (the Connectors UI cannot either); mcp-remote
# bridges stdio to our endpoint and adds the key header. Requires Node.
# Note: no space after the colon in the header value.
{
  "mcpServers": {
    "nameplate": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://nameplatedata.com/mcp/",
        "--header",
        "X-API-Key:sk_..."
      ]
    }
  }
}

# Cursor (.cursor/mcp.json)
{
  "mcpServers": {
    "nameplate": {
      "url": "https://nameplatedata.com/mcp/",
      "headers": { "X-API-Key": "sk_..." }
    }
  }
}

# Codex (~/.codex/config.toml)
[mcp_servers.nameplate]
url = "https://nameplatedata.com/mcp/"
headers = { "X-API-Key" = "sk_..." }

Tools

The MCP tools return the same tier-shaped, receipt-carrying payloads the REST surface does; search_sources shares its exact response builder with GET /api/v1/sources/search.

Asking questions

Natural-language prompts an agent client can answer by chaining these tools:

Code examples

An authenticated GET /api/v1/projects in four environments, then a Python example paging /api/v1/sources/search.

curl

curl -H "X-API-Key: sk_..." \
  https://nameplatedata.com/api/v1/projects

Python (requests → DataFrame)

import requests, pandas as pd

resp = requests.get(
    "https://nameplatedata.com/api/v1/projects",
    headers={"X-API-Key": "sk_..."},
    timeout=30,
)
resp.raise_for_status()
df = pd.DataFrame(resp.json())
print(df[["project_id", "canonical_name", "state", "total_mw"]].head())

R (httr2 → data.frame)

library(httr2)

resp <- request("https://nameplatedata.com/api/v1/projects") |>
  req_headers(`X-API-Key` = "sk_...") |>
  req_perform()

projects <- do.call(rbind, lapply(resp_body_json(resp), as.data.frame))
head(projects[c("project_id", "canonical_name", "state", "total_mw")])

Power Query (Excel)

let
    Source = Json.Document(
        Web.Contents(
            "https://nameplatedata.com/api/v1/projects",
            [Headers = [#"X-API-Key" = "sk_..."]]
        )
    ),
    Table = Table.FromList(Source, Splitter.SplitByNothing()),
    Expanded = Table.ExpandRecordColumn(
        Table, "Column1",
        {"project_id", "canonical_name", "state", "total_mw"}
    )
in
    Expanded

Python — paging /api/v1/sources/search

import requests

def search_sources(q, page_size=25):
    url = "https://nameplatedata.com/api/v1/sources/search"
    headers = {"X-API-Key": "sk_..."}
    seen = []
    while True:
        resp = requests.get(
            url,
            headers=headers,
            params={"q": q, "limit": page_size},
            timeout=30,
        )
        resp.raise_for_status()
        payload = resp.json()
        seen.extend(payload["sources"])
        # limit is capped at 25 server-side; stop when the page is not full
        if not payload["has_more"]:
            break
        break  # single page here; advance your query/filter to page further
    return seen

rows = search_sources("Project Cannoli")
for row in rows:
    print(row["source_id"], row["title"], row["url"])

limit is clamped to 25; use has_more to know when more matches exist and narrow q or add source_type / project_id filters to walk a large result set.

Errors

The versioned /api/v1/* read endpoints fail open: a missing, invalid, or revoked key is not rejected — the request resolves to the free tier and returns 200 with the reduced view. The status codes below are the ones these surfaces actually return.

Because keys fail open to the free tier on /api/v1/*, an invalid key does not produce a 401 there — check GET /api/v1/me or the X-API-Tier header to confirm your key resolved as expected. Over MCP, a non-Team caller reaching a data tool gets a JSON refusal (mcp_requires_team_agreement), not an HTTP error.

Getting a key

API keys are issued under Team agreements only — see pricing. Email bd@nameplatedata.com and we'll set you up the same day. Usage is subject to the Terms of Service; the data may not be resold, republished, or used to build a competing dataset.