API Reference

This guide is intended for developers who wish to build their own frontend applications or integrations on top of the Calyntro API.

The API is built with FastAPI and follows RESTful principles. All responses are JSON-formatted.

Note

The Base URL for all endpoints is /api/v1.

Common Concepts

Request Format

Most analysis endpoints accept POST requests to allow for complex filtering parameters in the body. Dates should be provided in ISO 8601 format (e.g., 2023-01-01T00:00:00).

Standard Filter Parameters:

start_date (or from_): The beginning of the analysis time window.
end_date (or to): The end of the analysis time window.
module_name (or module): Optional. Filter results to a specific architectural component/module.

Response Format

List-based responses follow a consistent structure wrapping the results in an items array:

{
  "items": [
    { ... },
    { ... }
  ]
}

Lines of Code (LOC)

Endpoints for analyzing the size of the codebase.

Get LOC per File

Returns the Lines of Code count for each file, based on the latest commit within the selected timeframe.

URL: /analysis/loc/files
Method: POST

Request Body:

{
  "start_date": "2023-01-01T00:00:00",
  "end_date": "2023-12-31T23:59:59",
  "module_name": "optional_module_name"
}

Response:

{
  "items": [
    {
      "name": "src/main.py",
      "loc": 150
    }
  ]
}

Get LOC per Module

Returns the aggregated Lines of Code for each defined module.

URL: /analysis/loc/modules
Method: POST

Request Body: Same as Get LOC per File.

Response:

{
  "items": [
    {
      "name": "src/core/",
      "loc": 5240
    }
  ]
}

Get Total LOC

Returns the grand total Lines of Code for the entire project (or filtered selection).

URL: /analysis/loc/total
Method: POST
Request Body: Same as Get LOC per File.

Response:

{
  "items": [
    {
      "name": "Total",
      "loc": 15420
    }
  ]
}

Evolution & Pulse

Endpoints for analyzing how the codebase changes over time.

Change Frequency (Files)

Retrieves commit activity for files, including commit counts, author metrics, and last modification details.

URL: /analyze/commits
Method: POST

Request Body:

{
  "start_date": "2023-01-01T00:00:00",
  "end_date": "2023-12-31T23:59:59",
  "module_name": "optional_module_name"
}

Response:

{
  "items": [
    {
      "file_path": "src/core/analysis.py",
      "commit_count": 42,
      "last_modified": "2023-12-01T10:00:00",
      "main_contributor": "John Doe",
      "author_count": 3,
      "last_commit_message": "Refactor analysis engine"
    }
  ]
}

Change Frequency (Modules)

Retrieves commit activity aggregated by module.

URL: /analyze/modules/commits
Method: POST
Request Body: Same as Change Frequency (Files).

Response:

{
  "items": [
    {
      "module_name": "src/api/",
      "commit_count": 85,
      "last_modified": "2023-12-15T14:30:00",
      "main_contributor": "Jane Smith",
      "author_count": 5,
      "last_commit_message": "Fix API authentication"
    }
  ]
}

Change Recency (Files)

Returns the age of files (time since first and last commit).

URL: /analyze/age
Method: POST

Request Body:

{
  "from_": "2023-01-01T00:00:00",
  "to": "2023-12-31T23:59:59",
  "module": "optional_module_name",
  "nbr_items": 50
}

Response:

{
  "items": [
    {
      "file_path": "src/utils.py",
      "first_commit": "2021-01-01T12:00:00",
      "last_commit": "2023-11-15T09:30:00",
      "age_days": 1048,
      "revisions": 15
    }
  ]
}

Change Recency (Modules)

Returns the age aggregated by module.

URL: /analyze/modules/age
Method: POST
Request Body: Same as Change Recency (Files).

Response:

{
  "items": [
    {
      "module_name": "src/core/",
      "first_commit": "2020-05-10T08:00:00",
      "last_commit": "2023-12-01T16:45:00",
      "age_days": 1300,
      "revisions": 450
    }
  ]
}

Absolute Churn

Returns the absolute churn (added + deleted lines) per file.

URL: /analyze/abs_churn/files
Method: POST

Request Body:

{
  "from": "2023-01-01T00:00:00",
  "to": "2023-12-31T23:59:59",
  "module": "optional_module_name",
  "nbr_items": 100
}

Response:

{
  "items": [
    {
      "file_path": "src/db/connection.py",
      "abs_churn": 1250,
      "total_added": 800,
      "total_deleted": 450,
      "first_change": "2023-01-15T10:00:00",
      "last_change": "2023-11-20T15:30:00",
      "revisions": 12
    }
  ]
}

Absolute Churn (Modules)

Returns the absolute churn aggregated by module.

URL: /analyze/abs_churn/modules
Method: POST
Request Body: Same as Absolute Churn.

Development Trend

Analyzes the evolution of hotspots by comparing a baseline time window with a current time window.

URL: /analyze/hotspot_trends
Method: POST

Request Body:

{
  "baseline": {
    "from": "2023-01-01T00:00:00",
    "to": "2023-06-30T23:59:59"
  },
  "current": {
    "from": "2023-07-01T00:00:00",
    "to": "2023-12-31T23:59:59"
  },
  "module": "optional_module_name",
  "nbr_items": 50
}

Response:

{
  "items": [
    {
      "file_path": "src/core/analysis.py",
      "churn_baseline": 450,
      "churn_current": 820,
      "scores": {
        "structural": {
          "baseline": 0.45,
          "current": 0.82,
          "delta": 0.37,
          "delta_norm": 0.5,
          "norm": 0.6,
          "trend": "up"
        },
        "activity": {
          "baseline": 15,
          "current": 25,
          "delta": 10,
          "delta_norm": 0.4,
          "norm": 0.5,
          "trend": "up"
        }
      }
    }
  ]
}

File Trend History

Returns the historical development of metrics for a specific file.

URL: /analyze/file_trend
Method: POST

Request Body:

{
  "file_path": "src/core/service.py",
  "start_date": "2023-01-01T00:00:00",
  "end_date": "2023-12-31T23:59:59",
  "bucket_days": 14,
  "metric": "churn"
}

Response:

{
  "items": [
    {
      "file_path": "src/core/service.py",
      "metric": "churn",
      "from_date": "2023-01-01T00:00:00",
      "to_date": "2023-12-31T23:59:59",
      "bucket_days": 14,
      "series": [
        {
          "t": "2023-01-01T00:00:00",
          "value": 150
        },
        {
          "t": "2023-01-15T00:00:00",
          "value": 240
        }
      ]
    }
  ]
}

Module Trend History

Returns the historical development of metrics for a module.

URL: /analyze/module_trend
Method: POST

Request Body:

{
  "module_name": "src/api/",
  "start_date": "2023-01-01T00:00:00",
  "end_date": "2023-12-31T23:59:59",
  "bucket_days": 14,
  "metric": "churn"
}

Response: Same structure as File Trend History.

Quality & Risk

Hotspot Analysis (Age & Churn)

Identifies “Hotspots” based on the intersection of high churn and file age.

URL: /analyze/hotspots/churnage
Method: POST

Request Body:

{
  "from": "2023-01-01T00:00:00",
  "to": "2023-12-31T23:59:59",
  "module": "optional_module_name",
  "nbr_items": 50
}

Response:

{
  "items": [
    {
      "file_path": "src/core/logic.py",
      "age_days": 450,
      "churn": 1200,
      "hotspot_score": 0.89
    }
  ]
}

Hotspot Analysis (Complexity & Churn)

Identifies hotspots by combining cognitive complexity with churn metrics.

URL: /analyze/hotspots/complexity
Method: POST

Request Body:

{
  "start_date": "2023-01-01T00:00:00",
  "end_date": "2023-12-31T23:59:59",
  "component_name": "optional_module_name"
}

Response:

[
  {
    "file_path": "src/complex_logic.py",
    "complexity": 150,
    "churn": 2500,
    "hotspot_score": 0.85
  }
]

Structure & Logic

Combined Complexity (Files)

Returns complexity metrics (Cyclomatic, Cognitive, Efforts) combined with a trend indicator.

URL: /analysis/complexity/combined
Method: POST

Request Body:

{
  "start_date": "2023-01-01T00:00:00",
  "end_date": "2023-12-31T23:59:59",
  "module_name": "optional_module_name"
}

Response:

{
  "items": [
    {
      "file_path": "src/main.py",
      "cognitive": 12,
      "cyclomatic": 8,
      "loc": 150,
      "efforts": 450.5,
      "trend_indicator": 2.0
    }
  ]
}

Combined Complexity (Modules)

Returns aggregated complexity metrics for modules.

URL: /analysis/complexity/modules
Method: POST
Request Body: Same as Combined Complexity (Files).

Response:

{
  "items": [
    {
      "file_path": "src/core/",
      "cognitive": 120,
      "cyclomatic": 85,
      "loc": 5240,
      "efforts": 12500.0,
      "trend_indicator": 1.5
    }
  ]
}

Complexity Trend History

Returns the historical complexity trend for a specific file or module.

URL: /analyze/hotspots/complexity/trend
Method: POST

Request Body:

{
  "file_path": "src/core/service.py",
  "module_name": null,
  "start_date": "2023-01-01T00:00:00",
  "end_date": "2023-12-31T23:59:59"
}

Response:

{
  "items": [
    {
      "author_date": "2023-01-15T10:00:00",
      "complexity": 15,
      "cognitive": 12,
      "efforts": 450.0,
      "loc": 120,
      "commit_churn": 25
    }
  ]
}

Team & Knowledge

Code Ownership (Files)

Returns the number of distinct authors per file and identifies the main contributor.

URL: /analysis/contributors/files
Method: POST

Request Body:

{
  "start_date": "2023-01-01T00:00:00",
  "end_date": "2023-12-31T23:59:59",
  "module_name": "optional_module_name"
}

Code Ownership (Modules)

Returns ownership statistics aggregated by module.

URL: /analysis/contributors/modules
Method: POST
Request Body: Same as Code Ownership (Files).

Response:

{
  "items": [
    {
      "module_name": "src/api/",
      "author_count": 8,
      "main_contributor": "Jane Smith"
    }
  ]
}

Knowledge Silos (Files)

Returns all files classified as a knowledge silo — files where a single developer accounts for at least silo_threshold (default 80 %) of all commits. Results are ordered by ownership percentage descending.

URL: /v1/analysis/silos/files
Method: POST

Request Body:

{
  "start_date": "2023-01-01T00:00:00",
  "end_date": "2023-12-31T23:59:59",
  "module_name": "optional_module_name",
  "silo_threshold": 0.80,
  "min_commits": 5
}

Request Parameters
Parameter	Required	Description
`start_date`	No	ISO 8601 timestamp. Only commits on or after this date are considered.
`end_date`	No	ISO 8601 timestamp. Only commits on or before this date are considered.
`module_name`	No	Restrict analysis to a specific component name.
`silo_threshold`	No	Fractional ownership threshold (0.5–1.0). A file is a silo when the top contributor meets or exceeds this value. Default: `0.80`.
`min_commits`	No	Minimum total commits a file must have to be included. Filters out rarely touched files. Default: `5`.

Response:

{
  "items": [
    {
      "file_path": "src/core/engine.py",
      "component_name": "core",
      "silo_developer": "alice",
      "ownership_pct": 94.3,
      "total_commits": 87,
      "risk": "high"
    }
  ]
}

Response Fields
Field	Description
`file_path`	Path to the silo file.
`component_name`	The architectural component this file belongs to (`null` if unassigned).
`silo_developer`	The developer who holds sole knowledge of this file.
`ownership_pct`	Percentage of commits attributed to the silo developer (0–100).
`total_commits`	Total number of commits to this file within the filtered time window.
`risk`	Risk classification: `low` (80–89 %), `medium` (90–94 %), `high` (95–99 %), `critical` (100 %).

Knowledge Silos (Modules)

Returns the silo density for each component — the fraction of files within the module that are knowledge silos — and identifies which developer is responsible for the most silos in that module. Results are ordered by silo ratio descending.

URL: /v1/analysis/silos/modules
Method: POST
Request Body: Same as Knowledge Silos (Files).

Response:

{
  "items": [
    {
      "component_name": "core",
      "total_files": 24,
      "silo_files": 9,
      "silo_ratio": 0.375,
      "dominant_silo_developer": "alice",
      "risk": "medium"
    }
  ]
}

Response Fields
Field	Description
`component_name`	Name of the architectural component.
`total_files`	Total number of distinct files active in the module within the time window.
`silo_files`	Number of files in the module that are classified as silos.
`silo_ratio`	Fraction of files that are silos (`silo_files / total_files`).
`dominant_silo_developer`	The developer responsible for the highest number of silos within this module.
`risk`	Risk derived from `silo_ratio`: `low` (< 25 %), `medium` (25–49 %), `high` (50–74 %), `critical` (≥ 75 %).

Knowledge Silos (Developers)

Returns the silo footprint of each developer — how many files and modules they are the sole knowledge holder of. Results are ordered by silo file count descending.

URL: /v1/analysis/silos/developers
Method: POST
Request Body: Same as Knowledge Silos (Files).

Response:

{
  "items": [
    {
      "developer": "alice",
      "silo_file_count": 14,
      "silo_module_count": 3,
      "avg_ownership_pct": 91.7,
      "risk": "high"
    }
  ]
}

Response Fields
Field	Description
`developer`	Developer name.
`silo_file_count`	Number of files for which this developer is the sole knowledge holder.
`silo_module_count`	Number of distinct components containing at least one of their silo files.
`avg_ownership_pct`	Average ownership percentage across all their silo files.
`risk`	Risk derived from `silo_file_count`: `low` (1–2), `medium` (3–9), `high` (10–19), `critical` (≥ 20).

Module Ownership by Teams

Shows how much of each module is owned by different teams (Team-centric view).

URL: /analysis/alignment/modules
Method: POST

Request Body:

{
  "start_date": "2023-01-01T00:00:00",
  "end_date": "2023-12-31T23:59:59",
  "component_name": "optional_module_name"
}

Response:

{
  "items": [
    {
      "team_name": "Frontend Team",
      "module_name_1": "UI Components",
      "ratio_1": 0.85,
      "module_name_2": "Icons",
      "ratio_2": 0.10,
      "module_name_3": "Tests",
      "ratio_3": 0.05,
      "health_status": "healthy"
    }
  ]
}

Top Team Contributors

Shows the top 3 contributing teams for each module (Module-centric view).

URL: /analysis/alignment/teams
Method: POST
Request Body: Same as Module Ownership by Teams.

Response:

{
  "items": [
    {
      "component_name": "src/core/",
      "team_name_1": "Core Team",
      "ratio_1": 0.75,
      "team_name_2": "DevOps",
      "ratio_2": 0.20,
      "team_name_3": "Unassigned/Others",
      "ratio_3": 0.05,
      "health_status": "monopoly"
    }
  ]
}

Configuration

Get Modules

Returns a list of all configured modules/components.

URL: /config/modules
Method: GET

Get Analysis Start Date

Returns the configured start date for the current analysis session.

URL: /config/analysis-since
Method: GET

Response:

{
  "analysis_since": "2020-01-01T00:00:00"
}

Get Teams

Returns a list of all configured teams.

URL: /config/teams
Method: GET

Response:

{
  "items": [
    {
      "name": "Team A"
    }
  ]
}

Application Info

Health Check

Returns the current health status of the API and database.

URL: /api/health
Method: GET

API Info

Returns metadata about the currently running analysis session.

URL: /info
Method: GET