Python SDK

cmdash-api-sdk — a Python client for the CMDash Public API. client.<namespace> is v2, the current version (client.v2.<namespace> is the same object spelled out); the deprecated v1 surface is at client.v1.<namespace>. Generated from the same spec the docs site itself serves at /docs/openapi.json. Zero runtime dependencies.

Install

The package version is generated in lockstep with the API version.

pip install cmdash-api-sdk

To install from source (repository access required):

git clone https://github.com/bgovanlu/cmdash.git
cd cmdash
pip install ./packages/sdk-python

Authentication

Settings → API Keys → Create API Key, with whichever permission scopes the calls you plan to make require — see public-api-reference.md for the scope each endpoint needs. Store it securely, e.g. as an environment variable, never committed:

import os
from cmdash_sdk import CmdashClient

client = CmdashClient(api_key=os.environ["CMDASH_API_KEY"])

Examples

Read your posture score

posture = client.posture.get_latest()
if posture is not None:
    print(posture["score"], posture["grade"])

List open risks

result = client.risks.list(status="OPEN", limit=20)
for risk in result["risks"]:
    print(risk["riskId"], risk["title"], risk["riskScore"])

Run the posture gate in CI

from cmdash_sdk import CmdashApiError

try:
    gate = client.gate.evaluate()
except CmdashApiError as err:
    raise SystemExit(f"gate evaluation failed: {err.message}")

if not gate["pass"]:
    raise SystemExit(1)

Every method raises CmdashApiError (a real HTTP error response) or CmdashClientError (the server was unreachable, or returned something that isn't the documented envelope) — full error-handling detail in the package README, published with the package.

Typing

Every method is fully type-hinted and the package ships py.typed (PEP 561), so mypy/pyright see those hints in your own project. Return types are Dict[str, Any] / List[Dict[str, Any]], not per-endpoint dataclasses — deliberately the "minimal typed client" the roadmap item calls for rather than a full schema-to-model generator.

Kept in sync with the API

The client is generated from the served OpenAPI document (/docs/openapi.json) and checked in both directions: every operation in the served document has a Python method, and every method exists and behaves correctly on the installed package. The method surface (names and parameters) follows the served document, and the per-field shapes are documented in public-api-reference.md.