Enterprise Data API

The Enterprise Data API gives you programmatic, read-only access to everything CodeDD has analysed for your firm — repository audit results, findings, dependencies, architecture, and portfolio-level KPIs — so you can build your own dashboards, feed a warehouse, or attach CodeDD numbers to an investment committee pack.

It is a REST API over HTTPS returning JSON, authenticated with an organization-scoped API key. Every endpoint is a GET; nothing in this API can change your data.

Quick start#

# 1. Store your key outside your shell history
export CODEDD_API_KEY="codedd_ent_..."

# 2. Ask the API what your key can do
curl -H "Authorization: Bearer $CODEDD_API_KEY" \
  https://api.codedd.ai/api/v1/enterprise/

# 3. List the portfolio companies the key covers
curl -H "Authorization: Bearer $CODEDD_API_KEY" \
  https://api.codedd.ai/api/v1/enterprise/portcos/

Creating a key#

Keys are created by an administrator of your legal organization in Account → Enterprise plan → Data API keys.

1. Click Create API key.
2. Give it the name of the tool that will use it — Power BI production, not test — so you know what breaks if you revoke it.
3. Choose the scopes it needs (see below).
4. Choose a lifetime. Every key expires; the maximum is 365 days.
5. Copy the key immediately. It is displayed once and cannot be retrieved again.

A key belongs to the organization, not to the person who created it, so an integration keeps working when that person changes role or leaves. Up to 10 active keys per organization.

Scopes#

Grant only what the consuming tool needs.

read:audits does not imply read:portfolio. A pipeline that only needs per-repository findings should not be able to read the firm-level roll-ups you would present to an investment committee.

If you lose a key#

There is no reveal endpoint, by design: a value that can be fetched again can be fetched by the wrong person. Rotate the key instead. Rotation issues a replacement immediately and keeps the old key working for 24 hours, so you can roll the secret forward on your next deploy rather than at the same instant.

Authentication#

Send the key as a bearer token on every request:

Authorization: Bearer codedd_ent_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The key must not appear in a URL, a query string, or a client-side bundle. It reads your firm's entire audit estate; treat it like a database password and store it in your secret manager.

Navigating your data#

You never have to construct an identifier. Start from the key and walk down:

GET /api/v1/enterprise/                                        → what this key can do
GET /api/v1/enterprise/portcos/                                → your portfolio companies
GET /api/v1/enterprise/portcos/{portco_uuid}/group-audits/      → audits run for one company
GET /api/v1/enterprise/group-audits/{group_audit_uuid}/audits/  → repositories in one audit
GET /api/v1/enterprise/audits/{audit_uuid}/scores/               → results for one repository

PortCo endpoints#

No scope beyond org membership (any valid key for the firm).

Repository audit endpoints#

All require read:audits.

Unlike the in-app AI advisor, these return complete payloads — no truncated narratives, no "top 5 findings only". The architecture resource is the exception to "payload as the dashboard sees it": it has a stable, versioned shape of its own (see Schema versions).

Portfolio endpoints#

All require read:portfolio and are addressed by group audit; CodeDD derives the portfolio company for you.

Coverage boundary#

The API exposes the audit results and portfolio roll-ups that reporting tools need. It does not mirror every dashboard screen — some surfaces are operational, write-only, or intentionally excluded.

If you need a dataset that is not listed above, contact your account manager — new endpoints are added when a reporting use case is clear and the underlying data is stable.

Response format#

Every successful response uses the same envelope:

{
  "status": "success",
  "data": { "portcos": [ { "portco_uuid": "...", "name": "Acme GmbH" } ] },
  "meta": {
    "api_version": "1",
    "correlation_id": "3f2b...",
    "next_cursor": null,
    "total_count": 12
  }
}

Quote the correlation_id when contacting support — it identifies the exact request in our logs.

The three versioned resources also state the schema version of data in meta.schema_version.

Pagination#

List endpoints are paginated. Pass limit (default 50, maximum 100) and follow meta.next_cursor until it is null:

import requests

session = requests.Session()
session.headers['Authorization'] = f'Bearer {API_KEY}'
BASE = 'https://api.codedd.ai/api/v1/enterprise'

def fetch_all(path, key):
    """Every page of a list endpoint."""
    items, cursor = [], None
    while True:
        params = {'limit': 100}
        if cursor:
            params['cursor'] = cursor
        payload = session.get(f'{BASE}{path}', params=params, timeout=30).json()
        items.extend(payload['data'][key])
        cursor = payload['meta']['next_cursor']
        if not cursor:
            return items

portcos = fetch_all('/portcos/', 'portcos')

Treat the cursor as opaque. It is not an offset, and building your own would break the moment ordering changes.

Caching with ETags#

Audit results are written once and then do not change, so repeat reads should be conditional. Repository endpoints return an ETag; send it back as If-None-Match and a 304 Not Modified costs you nothing:

curl -H "Authorization: Bearer $CODEDD_API_KEY" \
     -H 'If-None-Match: "a1b2c3d4..."' \
     https://api.codedd.ai/api/v1/enterprise/audits/$AUDIT/scores/

An audit still being analysed has no ETag, because its data is still moving.

The architecture resource can change after an audit completes: when an admin curates the repository's architecture style, CodeDD stores the repository's architecture model later, or its requirement ladder is recomputed. Its ETag changes with it, so a conditional request then returns the new representation instead of a 304. The tier-benchmark resource's ETag also follows the requirement ladder and the method the tier is shown by.

Schema versions of the architecture resources#

CodeDD's architecture analysis keeps improving. So that an improvement never changes the data your pipeline parses without warning, the three architecture resources have a schema version:

All other endpoints are unversioned and ignore the selector.

Selecting a version#

# Query parameter
curl -H "Authorization: Bearer $CODEDD_API_KEY" \
  "https://api.codedd.ai/api/v1/enterprise/audits/$AUDIT/architecture/?version=2"

# Or a header
curl -H "Authorization: Bearer $CODEDD_API_KEY" -H "X-CodeDD-Schema-Version: 2" \
  https://api.codedd.ai/api/v1/enterprise/audits/$AUDIT/architecture/

• Accepted values are 1 and 2 (v1, v1-legacy and v2 work too). Any other value is a 400 invalid_parameter, as is a query parameter and a header that name different versions.
• The response states the version it carries: in meta.schema_version and in the X-CodeDD-Schema-Version response header (responses vary on that header). A v1 response served because the request named no version also carries a Sunset header with the date below: it marks the end of v1 as the default. A request that names version=1 gets no Sunset header, because explicit v1 keeps working after that date.
• Each version has its own ETag, so a conditional request never answers with a 304 for the other shape. The ETag also changes when the version's output changes for the same audit (v2 gains a field, a value rule is corrected), so a cached copy is never revalidated across such a change. The ETags of the architecture resource changed once when versions were introduced; expect one full re-read.

Default version and sunset plan#

Send version=2 now: requests that name a version are unaffected by the default changing.

What can change in each version#

Both versions change their ETag whenever their output for the same audit changes, whether a field is added or a value rule is corrected. A conditional request therefore never keeps a stale copy. Parse v2 leniently: ignore fields you do not know.

v1-legacy#

v1-legacy keeps the fields and nesting these resources had before versions existed. Fields the analysis has gained since appear only in v2. These include coverage and data quality, edge semantics and relationships, structured evidence and candidate links, detection coverage, the shared stack, dimension evidence states, repository kinds, deployment platforms, the estate stages and membership, the org consolidation, structural criticality, module dependencies, provenance and the requirement ladder. The frozen field set reaches into the documents CodeDD's classifiers store: dimension scores, confidence components, tier gap and ceiling analyses, the repository tier breakdown and the group topology summary keep the fields they had.

Only documents without a fixed schema are served as stored, as before, and may carry whatever the analysis wrote: a component's or relationship's properties (the LLM's component document), the insights_* blocks, and the detector blocks coupling_analysis, communication_patterns, flow_patterns, coupling_metrics and communication_flows. Treat their keys as data, not as part of the contract.

The values are not frozen: where the analysis now computes a value correctly, v1 carries the corrected value under the same field.

Repository architecture

Estate map

Portfolio executive summary: summaries generated with evidence guardrails (v2 provenance.guardrails_applied) make no coupling, role or tier claim the evidence does not support, and state when cross-repository coupling cannot be determined.

v2#

Conventions for every v2 resource:

• Every documented field is always present; null means unknown, never zero: a count is 0 only when CodeDD counted nothing, and a ratio without a denominator (dependency_edges_per_repo of an estate without repositories) is null. Flags such as is_external and the curated flags are false unless set.
• Every confidence is an integer from 0 to 100.
• File references are repository-relative paths; no field contains an absolute path.
• Stored LLM documents (component properties, insight blocks, detector blobs) are not served; their facts are, as typed fields.
• A list taken from an unbounded source is capped and its total is served beside it (for example external_systems.total).

Vocabularies

Estate edge types. Every relationship between repositories has one of the types below. A type's meaning does not change. A type can gain an alias, and an edge stored under an alias is served under the type.

Repository architecture (v2)

A component's structural_criticality is {is_critical, reason, reasons, fan_in, fan_out}. Each entry of reasons is a code with its figures: articulation_point (separated_nodes, parts), high_fan_in (fan_in, percentile) or single_point_of_failure (dependent_count). It is null, and so is an edge's is_critical, when the graph could not be assessed or the audit predates structural criticality. Before that, is_critical was the LLM's strength label, and v2 never serves it as structural criticality.

A component of the LLM synthesis has the evidence_tier llm: its boundary, name and responsibilities are the model's, even when the files it cites are real. Its evidence_basis says what backs it: repository_files_verified (the cited files were checked against the analysed repository), repository_files (cited, not checked) or analysis_only (no file cited). A component of the deterministic fallback graph (deterministic_fallback) is deterministic, and an external system (relationship_target) takes the strongest tier of the edges that reference it.

Estate map (v2)

How the tier is determined (requirement ladder). A tier is the highest level whose required capabilities are all evidenced, cumulatively, in every area that applies to the repository. Each requirement is Met, Not met, Not assessed (it could not be checked, for example because it is configured outside the repository, or CodeDD does not check it yet) or Not applicable, and Not assessed never counts against a tier. When the next tier could not be verified, the tier is a lower bound (certainty at_least). The company tier is reached in an area when repositories holding at least 80% of the weight (the square root of their lines of code) reach it there, plus every repository rated critical; the company tier is the lowest area. Libraries, infrastructure code and other repositories without a running scale are not rated. basis says which method the tier is shown by; the tier and org_tier blocks keep the previous method's values until every consumer switches, and v1-legacy does not change.

Two confidences. evidence_confidence (0 to 100) answers whether the relation is real. Detectors that read the same input count once, and independent ones are combined (noisy-OR), so a relation found by the runtime configuration and by the architecture analysis scores above either finding. coupling_weight (0 to 1) answers how significant the relation is architecturally. It is the fixed weight of the edge's type in the edge-type registry, and a relationship takes the largest weight of its types. The weights are: deploy_assembly 1, catalog_relation 0.95, build_inheritance 0.9, interface_dependency 0.88, vcs_dependency and contract_dependency 0.85, ci_orchestration 0.8, api_dependency 0.75, library_dependency, event_coupling and event_dependency 0.7, data_dependency and uses_base_image 0.65, api_consumer_producer (paired from consumer and producer roles) 0.6, unknown 0.5, and shared_technology, shared_messaging and shared_database 0. One is never folded into the other. confidence on an edge equals its evidence_confidence.

Structured evidence. Each item of evidence_items is {repo, file, signal, detector, identity_tier}: the repository whose file holds the evidence, the repository-relative file, the signal that matched (for example BILLING_URL=http://billing-api:8080), the detector that read it, and how precisely the target was identified (coordinate, git, image, chart, runtime_name, host, alias, repo_name, ...). A list holds at most 20 items, and evidence_item_count gives the total.

Portfolio executive summary (v2)

{
  "schema_version": "2",
  "group_audit_uuid": "8c1e...",
  "executive_summary": "## 1. ...",
  "provenance": {
    "generated_at": "2026-10-04T12:30:00+00:00",
    "input_hash": "3f7a...",
    "guardrails_applied": true,
    "coverage_caveat_applied": true
  }
}

input_hash is the SHA-256 of the input the summary was generated from: a changed hash means a summary generated from different data. coverage_caveat_applied says whether the summary states that cross-repository coupling cannot be determined from the evidence. Both are null (and guardrails_applied is false) for summaries generated before provenance was recorded. When the provenance cannot be read, every provenance field is null, guardrails_applied included: unknown, not false.

Example: one estate edge in v2 (abridged: the audit and domain identifiers of both ends and the empty subject fields are left out)

{
  "source_repo": "checkout",
  "target_repo": "payments",
  "type": "api_dependency",
  "relation_kind": "directed",
  "direction_meaning": "depends_on",
  "relation_class": "dependency",
  "evidence_tier": "deterministic",
  "evidence_basis": "static_evidence",
  "confidence": 85,
  "is_critical_path": true,
  "criticality_kind": "structural",
  "subject": { "service_name": "payments-api" },
  "evidence": ["config/services.yml: PAYMENTS_URL"],
  "evidence_count": 1
}

Example: the relationship that edge belongs to (abridged). A second detector found the same call in the architecture analysis. Its finding is a separate facet, and because it is independent evidence it raises evidence_confidence.

{
  "edge_id": "rel_3c9d0e5a71b24f6a8d10",
  "source_repo": "checkout",
  "target_repo": "payments",
  "channel": "http",
  "relation_kind": "directed",
  "relation_class": "dependency",
  "is_coupling": true,
  "types": ["api_dependency", "interface_dependency"],
  "evidence_confidence": 93,
  "coupling_weight": 0.88,
  "evidence_tier": "deterministic",
  "is_critical_path": true,
  "facets": [
    { "type": "api_dependency", "detector": "integration_matcher", "confidence": 85, "evidence_tier": "deterministic" },
    { "type": "interface_dependency", "detector": "architecture_bridge", "confidence": 55, "evidence_tier": "heuristic" }
  ],
  "facet_count": 2,
  "evidence_items": [
    { "repo": "checkout", "file": "config/services.yml", "signal": "PAYMENTS_URL=http://payments-api:8080", "detector": "integration_matcher", "identity_tier": "runtime_name" }
  ],
  "evidence_item_count": 1
}

Moving from v1 to v2#

The OpenAPI document of the API describes both versions of each resource (oneOf).

Errors#

Failures use a stable error_code you can branch on. Messages may be reworded; codes will not change within v1.

{
  "status": "error",
  "error_code": "insufficient_scope",
  "message": "This API key does not have the \"read:portfolio\" scope.",
  "correlation_id": "9c1f..."
}

Rate limits#

Limits are per key, not per IP address, so one pipeline cannot throttle another that happens to share an egress address. On a 429, wait for Retry-After seconds; do not retry immediately.

Building a reporting pipeline#

A complete nightly extract:

import os
import requests

API_KEY = os.environ['CODEDD_API_KEY']
BASE = 'https://api.codedd.ai/api/v1/enterprise'

session = requests.Session()
session.headers['Authorization'] = f'Bearer {API_KEY}'


def get(path, **params):
    response = session.get(f'{BASE}{path}', params=params, timeout=60)
    if response.status_code == 429:
        raise RuntimeError(f"Rate limited; retry after {response.headers['Retry-After']}s")
    if response.status_code == 409:
        return None          # Audit still running; nothing to extract yet.
    response.raise_for_status()
    return response.json()['data']


rows = []
for portco in get('/portcos/', limit=100)['portcos']:
    group_audits = get(f"/portcos/{portco['portco_uuid']}/group-audits/", limit=100)

    for group_audit in group_audits['group_audits']:
        group_uuid = group_audit['group_audit_uuid']

        debt = get(f'/group-audits/{group_uuid}/kpis/technical-debt/')
        if debt is None:
            continue

        for audit in get(f'/group-audits/{group_uuid}/audits/', limit=100)['audits']:
            # Skip repositories whose analysis has not produced results.
            if not audit['is_completed']:
                continue

            scores = get(f"/audits/{audit['audit_uuid']}/scores/")
            rows.append({
                'portco': portco['name'],
                'group_audit': group_audit['name'],
                'repository': audit['name'],
                'lines_of_code': audit['lines_of_code'],
                'scores': scores['scores'],
                'portfolio_technical_debt': debt['data'],
            })

print(f'Extracted {len(rows)} repositories')

Recommended practice#

• Store the key in a secret manager, never in source control, a notebook, or a dashboard definition.
• Rotate on a schedule — quarterly is a reasonable default — and always after someone with access leaves.
• Use one key per consuming system. When something misbehaves you can revoke it without taking down every other integration.
• Grant the narrowest scope the tool needs.
• Cache with ETags and only re-read what changed. Of a completed audit, only the architecture changes later (through curation or a stored architecture model), and its ETag changes with it.
• Retry with exponential backoff on 429 and 5xx; never retry a 4xx other than 429.
• Check is_completed before extracting results, and treat 409 audit_in_progress as "come back later", not as an error.

Security and auditability#

• Keys are stored only as SHA-256 digests. Neither a database dump nor a query log yields a usable credential.
• Every request is recorded against the key — method, route, resource, status, and outcome — including refusals. Ask support for an access export if you need to evidence who read what.
• Access is re-checked on every request against your live contract, the key's scopes, and the resource's ownership. Nothing is inherited from when the key was created.
• Responses are marked Cache-Control: private, no-store so audit findings do not linger in an intermediary cache.
• All traffic must be HTTPS.

Frequently asked#

Can I write data through this API? No. Every endpoint is read-only. Audits are started in the app or through the CodeDD CLI.

Can I use it with an MCP client? The API is the foundation for MCP access to CodeDD data. Contact your account manager about current MCP availability.

What happens when our contract lapses? The API closes within a minute, and existing keys stop working. They resume if the contract is reinstated and has not expired.

Can a key read another firm's data? No. A key is bound to one legal organization and can only reach portfolio companies, audits, and results that belong to it. Anything else returns 404.

Do invited team members access the API with their login? No. The data endpoints do not accept session JWTs — only an organization API key (Authorization: Bearer codedd_ent_...). Invited members do not get automatic API access; an organization administrator must create a key and share it with the tool (or person) that needs it. Keys are org-scoped: whoever holds the key can read the firm's entire entitled audit estate, not just the subset one member sees in the web UI.

Who can create or revoke keys? Only administrators of the legal organization (the Enterprise billing entity), via Account → Enterprise plan → Data API keys, while on an active full Enterprise contract.

Related documentation#

• Portfolio Monitoring
• Setting Up a Portfolio Organization
• CodeDD CLI Guide