Docs → API reference

MISO Capacity Accreditation (internal) API v1

Generated from core.contract.describe_power_capacity_accreditation_miso_v1() and checked fixture-backed examples. Do not hand-edit the example JSON files.

Capability

• Capability: power.capacity_accreditation_miso
• Primitive: query_power_capacity_accreditation_miso_v1
• Status: available
• Current source: energy.miso.accreditation
• Source publisher: Midcontinent Independent System Operator, Inc.
• Snapshot behavior: as_of = latest resolves to an exact snapshot date in every response.

What It Can Answer

• MISO Schedule 53 ISAC/ICAP class averages and published contributing-unit counts.
• Indicative DLOL UCAP/ICAP class ratios, keeping each stated storage variant separate.
• Explicitly suppressed Schedule 53 classes, without turning non-public ratios into zero.
• Raw PDF page-row evidence for any returned citation.

Represented Facts

• MISO-published seasonal capacity accreditation ratios per resource class, as a fraction of installed capacity (ICAP), from two coexisting tariff constructs kept apart by document_kind: Schedule 53 class-average ISAC/ICAP ratios (the construct binding until Planning Year 2027-2028) and indicative Direct Loss of Load class-level UCAP/ICAP ratios published under Schedule 53A ahead of its 2028-2029 implementation. Storage classes served under multiple DLOL modeling variants are separate cited atoms carrying the stated variant, never blended. Classes MISO suppresses for data-integrity/confidentiality (<30 contributing units) yield a suppression atom, so absence is provably "not published", never "not parsed". Ratios from different documents or constructs are never merged, preferred, or reconciled by this block.

Data Point Contract

• Data point: power.capacity_accreditation_miso
• Product spec: blocks/power_capacity_accreditation_miso/card.md
• Grain: document_planning_year_resource_class_season
• Source basis: energy.miso.accreditation
• Represented fact: MISO-published seasonal capacity accreditation ratios per resource class, as a fraction of installed capacity (ICAP), from two coexisting tariff constructs kept apart by document_kind: Schedule 53 class-average ISAC/ICAP ratios (the construct binding until Planning Year 2027-2028) and indicative Direct Loss of Load class-level UCAP/ICAP ratios published under Schedule 53A ahead of its 2028-2029 implementation. Storage classes served under multiple DLOL modeling variants are separate cited atoms carrying the stated variant, never blended. Classes MISO suppresses for data-integrity/confidentiality (<30 contributing units) yield a suppression atom, so absence is provably "not published", never "not parsed". Ratios from different documents or constructs are never merged, preferred, or reconciled by this block.

Does not answer:

• planning years before 2025-2026 (MISO's older Schedule 53 documents use layouts this block does not read; they are archived, not served)
• resource-specific (unit-level) SAC, ISAC, GVTC, or interconnection-service values
• PRMR, LRR, or reserve-margin requirements (capacity_market block scope)
• ICAP or UCAP megawatt totals per class (ratios only in v1)
• a reconciled or "current best" accreditation across constructs or documents
• ELCC constructs from other ISOs, or any forecast beyond MISO's published documents

REST Surface

• GET /v1/health
• GET /v1/capabilities
• GET /v1/power/capacity-accreditation-miso/schema
• POST /v1/power/capacity-accreditation-miso/query
• POST /v1/evidence/source-row

MCP Surface

• list_capabilities_v1
• describe_power_capacity_accreditation_miso_v1
• query_power_capacity_accreditation_miso_v1
• get_source_evidence_v1

Local MCP Setup

Some MCP clients launch servers from the user's home directory or ignore a configured cwd. Use uv run --directory so the server always starts from the repository project.

{
  "command": "uv",
  "args": [
    "run",
    "--directory",
    "/absolute/path/to/OSINT",
    "python",
    "-m",
    "core.mcp_server"
  ]
}

Leave EXASCALE_PARQUET_BASE / EXASCALE_RAW_BASE unset: the one server hosts every data point's tools, and with no override it resolves each block's promoted snapshots and raw archive from the repository layout. Setting either env var points ALL tools at one directory — a per-block path breaks every other block's tools. They exist only for single-source sandboxes and tests.

Request Schema

Filters:

• as_of
• document_kind
• planning_year
• resource_class
• class_family
• season
• storage_variant

Group by:

• document_kind
• planning_year
• resource_class
• class_family
• season
• storage_variant

Date range parameters:

Controls:

• include_records
• include_evidence
• limit
• order_by
• top_n
• order
• rollup_other

Ranking (how order_by / top_n / order join — order_by ranks groups by a metric, never a group_by dimension; top_n needs both a group_by and an order_by):

{
  "no_ranking": "Omit order_by and top_n to return all groups in group-key order.",
  "order": {
    "default": "desc",
    "valid_values": [
      "desc",
      "asc"
    ]
  },
  "order_by": {
    "accepts": "one of output.metrics",
    "note": "Ranks the groups by a metric (a measure). Not a group_by dimension \u2014 rows already come back grouped by each group_by field.",
    "requires": [
      "group_by"
    ],
    "valid_values": [
      "avg_accreditation_ratio",
      "min_accreditation_ratio",
      "max_accreditation_ratio",
      "count_of_units",
      "source_record_count"
    ]
  },
  "top_n": {
    "note": "Keeps the top N groups by order_by; the rest fold into one (other) remainder (additive metrics sum into it, non-additive ones are nulled) so the result still reconciles to summary.totals.",
    "requires": [
      "group_by",
      "order_by"
    ],
    "type": "positive integer"
  }
}

Output Schema

Aggregate metrics:

• avg_accreditation_ratio
• min_accreditation_ratio
• max_accreditation_ratio
• count_of_units
• source_record_count

Metric groups:

{
  "accreditation": [
    "avg_accreditation_ratio",
    "min_accreditation_ratio",
    "max_accreditation_ratio"
  ],
  "records": [
    "source_record_count"
  ],
  "units": [
    "count_of_units"
  ]
}

Response summary fields:

• group_count
• totals

Accepted fact policy:

• Query responses contain accepted, gate-passed facts only.
• Gate, monitor, and audit quality signals are internal controls, not agent-facing answer caveats.
• If a source snapshot is not fit to serve, the source must fail closed before it reaches this API.

Metric metadata:

Rollup rules:

• summary.totals.<metric> is the authoritative total for the full matched query.
• Grouped row metrics may be summed only when additive_across_groups is true.
• Do not sum grouped values for these non-additive metrics: avg_accreditation_ratio, min_accreditation_ratio, max_accreditation_ratio, count_of_units.

Detail record fields returned when include_records is true:

• source_id
• sheet_name
• iso
• document_kind
• planning_year
• resource_class
• class_family
• season
• storage_variant
• atom_type
• accreditation_ratio
• count_of_units
• suppression_reason
• report_period
• source_record_key
• source_row_number
• as_of
• raw_file_sha256
• citation

Row-level citation fields:

• source_id
• source_url
• source_file
• sheet
• source_row
• raw_file_sha256
• as_of

Aggregate citation fields:

• source_id
• publisher
• source_url
• source_file
• raw_file_sha256
• as_of
• source_rows_count
• source_rows_sample
• verify
• lineage_filter

Codebooks

The complete machine-readable codebooks are included in capability-schema.json.

Checked Examples

The checked schema output is capability-schema.json.

Agent Workflow

1. Call list_capabilities_v1 and select power.capacity_accreditation_miso.
2. Call describe_power_capacity_accreditation_miso_v1 to inspect valid filters, groupings, metrics, and citation fields.
3. Call query_power_capacity_accreditation_miso_v1 with bounded JSON params.
4. If the answer needs proof, pass a returned row-level citation object to get_source_evidence_v1.
5. Answer with the resolved as_of and relevant citations. Present returned metrics as authoritative for their declared source, snapshot, grain, and aggregation.