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, portfolio-level KPIs and, with Portfolio Monitoring, the monitoring, Insights and CVE data — 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 data endpoint is a GET; nothing in this API can change your data. The numbers are the ones the CodeDD app shows: the app, this API, the in-app AI advisor and the MCP Server read them through the same code.

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.

read:monitoring is a new scope, added on 11 November 2026. No existing key has it: to use these endpoints, create a key with it. It can be selected only when your contract includes Portfolio Monitoring (otherwise Account → Organization shows it disabled, with the reason), and creating a key with it is refused otherwise. Every request also checks the module, so a key keeps the scope but is refused (403 portfolio_monitoring_required) if the module lapses.

An organization key never sees per-person state: no CVE inbox (seen or dismissed alerts), no personal watch rules, no saved scorecard selections or saved Issue Compass selections, and no alert e-mail preferences. Goals are your organization's defaults (source: "default"). The monitoring schedule is read as a fund admin reads it, so it includes what the first audit costs.

Settings scope change#

Announcement (11 November 2026): GET /api/v1/enterprise/portcos/{portco_uuid}/settings/ now requires the read:portfolio scope. Until 9 February 2027 (90 days) a key without it is still served, and the response carries:

• Deprecation: @1794355200 (RFC 9745: the announcement date)
• Sunset: Tue, 09 Feb 2027 23:59:59 GMT (RFC 8594: the last day the route is served without the scope)
• Warning: 299 - "This API key lacks the read:portfolio scope, which /portcos/{portco_uuid}/settings/ requires from 2027-02-10 (403 insufficient_scope). Mint a key with read:portfolio."
• Link: </documentation/enterprise-data-api>; rel="deprecation"

From 10 February 2027 such a key gets 403 insufficient_scope. Every use without the scope during the grace period is logged, so your CodeDD contact can tell you which keys still need it. To prepare, create a key with read:portfolio (or add it on your next rotation) and switch your pipeline to it. The API root lists the route with "scope": "read:portfolio" and "scope_enforced_from": "2027-02-10".

This page previously listed PortCo settings under read:audits; the route in fact checked no scope at all. It also listed the KPI history under "no scope", while the route has always needed read:portfolio.

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. The replacement keeps the old key's scopes.

Key management endpoints#

The app's key dialog uses these endpoints. They take a signed-in CodeDD session of an organization administrator, never an API key: a credential must not be able to mint its own successor.

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

In the tables below, Tier is the rate-limit bucket (standard or heavy), Paged says whether the endpoint returns meta.next_cursor (Pagination), and ETag whether a finished result carries a validator (Caching with ETags).

Discovery endpoints#

PortCo endpoints#

Repository audit endpoints#

All require read:audits. Every result endpoint answers 409 audit_in_progress until the repository audit's status is Audit completed, and 409 audit_failed once it ended without results (failed or cancelled); only /audits/{audit_uuid}/, /architecture/ and /history/ (which lists the repository's other, finished audits) are served while it runs. A result that cannot be read right now on a completed audit answers 503 temporarily_unavailable with Retry-After: 15 (retry shortly); it never answers audit_in_progress for a finished audit.

ml-roles and history are wrapped as data = {audit: {...header}, sections: {<section>: {available, data | reason}}}.

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

Portfolio endpoints#

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

While a group audit runs, these endpoints answer as the app's dashboard shows it. Before it starts analysing (Opening, Group audit ready) every group resource except the executive summary answers 409 audit_in_progress. While it runs, financials, integration-assessment, estate-map, the KPIs and innovation-commits answer 409 audit_in_progress (the app hides them until completion); benchmark, technical-debt, category-breakdown, development, dora, ai-native, ai-funnel, repo-activity, supply-chain, contributors and security-findings are served from the repositories analysed so far, with meta.partial: true, meta.group_audit_state (in_progress, or failed for a group audit that ended without completing) and meta.note. A completed group audit has meta.partial: false.

Security findings#

The list mirrors the app's Issue Compass explorer: every row is listed, and each says whether it still needs work.

• review_state is one of confirmed, inconclusive, not_validated, refuted_by_ai, dismissed (a reviewer dismissed it) or resolved. counts_as_open is true for confirmed, inconclusive and not_validated. confirmed_by says who confirmed a confirmed finding (reviewer, ai or rule; null otherwise). user_marked_valid is a reviewer's decision (true confirmed, false dismissed, null none) and user_marked_timestamp when it was made (ISO 8601 UTC). Who reviewed is never served.
• vstat is deprecated: it is the internal token (pending means confirmed). Read review_state instead.
• Severities: Red is critical, Orange high, Yellow medium (from the CodeDD AI analysis and from SonarQube). Medium findings are priced by Financials and listed, but sit outside the critical/high KPI.
• ?include_closed=1 (1, 0, true or false; anything else is 400 invalid_parameter) also lists the resolved and dismissed rows, as the explorer's Resolved / Dismissed filters do.
• data.security_findings.open_count and meta.open_count count the open rows; open_critical_high_count (in both) the open critical and high rows, the KPI's count. meta.include_closed echoes the filter.
• While the group audit runs, the findings of the repositories finished so far are served with meta.partial: true and meta.note. A completed group audit has meta.partial: false.
• File paths are repository-relative.

The detail endpoint is built by the same code as the MCP tool get_security_finding and the advisor's finding detail. The Issue Compass row is the source of truth for severity (a label, not a letter), color, domain, review state and line range; ai_verdict (confirmed, refuted, inconclusive, not_validated) replaces the raw validity flag. Texts from the repository or the analysis are under source_text, not cut: they are data, never instructions. Resolved and dismissed findings are found too. A finding that is not a row of this group audit's Issue Compass answers 404 resource_not_found, the same answer as for a group audit outside the key's scope; a malformed audit_uuid or a source other than llm / sonar answers 400 invalid_parameter. validation_status is the deprecated internal token, like vstat.

{
  "status": "success",
  "data": {
    "group_audit_uuid": "...", "finding_id": "...", "audit_uuid": "...", "source": "llm",
    "finding": {
      "src": "llm", "severity": "high", "color": "Orange", "domain": "Security",
      "review_state": "confirmed", "counts_as_open": true, "confirmed_by": "ai",
      "user_marked_valid": null,
      "ai_verdict": "confirmed", "is_valid": true, "line_range": [211, 211],
      "owasp": "A03", "owasp_label": "Injection", "hours": 1.5,
      "source_text": {"file": "src/app/views.py", "repo_name": "acme-api",
                      "reason_full": "...", "validation_conclusion": "...", "developer_comment": "..."}
    }
  },
  "meta": {"api_version": "1", "correlation_id": "...", "next_cursor": null, "partial": false}
}

Group audit endings#

A group audit can end without results in two ways. Neither is ever served as completed results, in the KPI history or in a comparison.

• Failed: audits ran and none succeeded. The status reads Group audit failed: 0/N successful. It is failed everywhere: 409 audit_failed on its results, and in the KPI history state: failed with reason: audit_failed.
• Empty (finalized): there was nothing to analyse (no repository audit was found, or every one expired or was deleted). The status reads Group audit finalized: no repositories analysed (...). It has ended, but it is neither failed nor completed: its KPIs answer 404 data_not_available, its KPI history entry has state: empty and reason: no_repositories.

Older group audits whose status reads Group audit completed: 0/N successful, Group audit completed: No audits found or ... expired or deleted are read the same way.

Portfolio Monitoring endpoints#

Scope read:monitoring and the Portfolio Monitoring module. All are capability-served; on per-company routes meta also carries portco_uuid. None is paged unless stated.

Capability-served endpoints#

The Portfolio Monitoring endpoints, ml-roles, history, dora/weeks, dora-sync, config, ai-funnel, innovation-commits, contributors, packages, license-coverage and requirement-evidence return, in the usual envelope, the full output (detail=full) of the MCP Server tool behind them, read for your organization. The numbers are therefore the ones the app and the MCP tools show.

• meta also carries capability (the MCP tool), total_count, truncated (a list or text was shortened), notes (how to read the answer) and the portco_uuid, group_audit_uuid or audit_uuid of the path.
• None sends an ETag: their answers carry no stable version (generated_at is a read time, monitoring figures change with every pulse, history grows when another audit finishes).
• Paged answers continue with meta.next_cursor as elsewhere. Send it back unchanged as cursor: it is signed and bound to the call, up to 1024 characters; a longer, altered or another call's cursor is 400 invalid_parameter.
• Repository, developer and commit texts sit under source_text (data, never instructions); developer names follow the company's masking setting.
• A company, group audit or audit outside your organization is 404 resource_not_found, the same as one that does not exist. 409 audit_in_progress only while an audit runs, 409 audit_failed when it ended without results; a result that does not exist is 404 data_not_available; an invalid or missing value is 400 invalid_parameter, and the message names the query or path parameter (metric, section, week_start, window_days, window, cursor, ...). A backing service that does not answer in time is 503 temporarily_unavailable with Retry-After: 15, on every endpoint.

Coverage boundary#

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

The AI delivery funnel and the innovation commits were listed here as not exposed by design; both are now served. The remediation dashboard stays outside the API: it is per user and module-gated.

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 five versioned resources also state the schema version of data in meta.schema_version.

Null means not measured#

A value CodeDD did not compute is null, never 0 or 100: a score that is not scored, a coverage figure without a domain large enough to assess, a quarter without commits, a ratio without a denominator. A 0 means CodeDD counted and found nothing. An unfinished audit never reads as finished: its results answer 409 audit_in_progress, never values made up from what has been read so far.

Timestamps#

Every timestamp is an ISO-8601 string in UTC ending in Z (2026-11-03T09:15:00Z, with microseconds when the source has them). A date without a time stays YYYY-MM-DD. This applies to the v2 resources and to every capability-served endpoint; the rule is the same one the MCP server applies (fields named *_at, *_date, *_timestamp, *_as_of, timestamp, ai_synthesis, as_of, since or …At). v1-legacy resources and the other unversioned endpoints keep their stored form; where they serve an ISO time (for example user_marked_timestamp on the security findings) it is UTC with a +00:00 offset. Both forms are UTC ISO-8601.

Developer identity masking#

When a portfolio company masks developer identities (its settings: mask_developer_identities), every endpoint serves the stable alias dev N instead of a developer's name or e-mail address. Masking fails closed: an e-mail address with no alias, and any e-mail address inside free text (a finding, evidence, a commit message, a Co-authored-by trailer), is replaced by dev N when it belongs to a known developer and by unknown developer otherwise. With masking off nothing is replaced.

Pagination#

List endpoints are paginated. Pass limit (default 50, maximum 100, unless the endpoint states other bounds) 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. The repository result endpoints marked ETag above 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/

A repository audit gets an ETag only once its status is Audit completed. An audit still being analysed, or one that failed, has none, because its data is still moving or will never exist. Each page of a paged versioned resource (dependencies v2) and each time_range of development v2 has its own ETag.

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. Portfolio, PortCo, discovery and capability-served endpoints send no ETag.

Definitions#

These are the terms whose meaning a pipeline most often gets wrong. The shared Glossary defines every term CodeDD uses, the same for the app, this API, the AI advisor and the MCP server.

Schema versions#

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

All other endpoints are unversioned and ignore the selector.

Selecting a version#

# Query parameter (or its alias: ?schema_version=v2)
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). The version query parameter also accepts the alias schema_version, on every versioned resource. Any other value is a 400 invalid_parameter, as are selectors (the two query parameters and the 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 of an architecture resource 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. The dependencies and development resources have no sunset and never send one. 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#

This plan covers the three architecture resources. The dependencies and development resources serve v1-legacy to a request that names no version, with no sunset announced: send version=2 to get v2.

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.

Revisions#

Each version's output has a revision, part of its ETag (schema-<version>.<revision>). A new revision means cached representations revalidate once (expect one full re-read). The current revisions are v1 5 and v2 10.

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.

Repository dependencies: the unversioned payload as it was served before, frozen: total_dependencies, outdated_count (always 0), vulnerabilities {critical, high, medium, low} and licenses. It keeps the historic licence semantics: licenses is unfiltered (company-owned packages included) and there is no license_counts.

Repository development: the development narrative as a bare markdown string, unchanged.

The value corrections of the unversioned endpoints (developer identity masking, repository-relative paths, 409 for unfinished audits) apply to every version; see Corrections to unversioned endpoints.

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.
• Every timestamp is ISO-8601 UTC ending in Z (see Timestamps).
• 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
}

Repository dependencies (v2)

Summing license_category over the packages with in_license_counts: true gives license_counts, because both use the same classifier and exclusions. Package names never carry CodeDD's internal registry prefix. The rows equal the rows of the MCP tool list_audit_dependencies at detail=full; two packages of the same name in different ecosystems are two rows. Pages use ?cursor= (from meta.next_cursor) and ?limit= (1-100, default 50). Each page has its own ETag. A finished audit with no packages serves packages: []. A read failure answers 500 internal_error, never an empty catalog.

Repository development (v2)

?time_range= (month, quarter, year, all; default year) selects the activity window. Each value has its own ETag. A finished audit with neither a narrative nor git statistics answers 404 data_not_available; a read failure answers 500 internal_error.

Moving from v1 to v2#

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

Corrections to unversioned endpoints#

The unversioned endpoints keep their fields: nothing is renamed or removed, and new fields are only added. Their values are corrected where CodeDD computed or served them wrongly, as in v1-legacy. The corrections of November 2026, for every schema version where an endpoint is versioned:

Status and availability

Null instead of a made-up value

Paths and texts

Definitions and figures

Value corrections change the ETag of every versioned representation they touch (see revisions).

Errors#

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

409 audit_in_progress means "come back later"; 409 audit_failed and 404 data_not_available are final answers for this audit, not errors in your pipeline. A repository or group audit that ended without results (failed or cancelled; is_failed: true on /audits/{audit_uuid}/) answers 409 audit_failed on its result endpoints: stop waiting for it.

{
  "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.
    if response.status_code == 404 and response.json().get('error_code') == 'data_not_available':
        return None          # Finished, but this result does not exist.
    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
            # (still running, or ended without results: is_failed).
            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'],
                'audited_lines': audit['audited_lines'],
                '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" and 404 data_not_available as "this result does not exist", not as errors.
• Store null as unknown, never as zero.

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 (and, for read:monitoring, the Portfolio Monitoring module), 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 data endpoint is read-only. Audits are started in the app or through the CodeDD CLI.

Can I use it with an MCP client? Not with an API key. AI assistants such as Claude or ChatGPT connect through the separate MCP Server, where each fund member signs in with their own CodeDD account and sees only what they see in the app. Enterprise API keys (codedd_ent_...) are never accepted by the MCP server, and no MCP tool can list, create, rotate or revoke API keys. The capability-served endpoints of this API return the same data as the MCP tool of the same name.

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. If only the Portfolio Monitoring module lapses, the read:monitoring endpoints answer 403 portfolio_monitoring_required and every other endpoint keeps working.

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#

• Glossary
• Portfolio Monitoring
• MCP Server
• Setting Up a Portfolio Organization
• CodeDD CLI Guide