Skip to main content
The Maturity Level Reports API provides programmatic access to your organization’s autonomy maturity evaluation data.

​
Authentication

All requests require a Factory API key in the Authorization header: 
Authorization: Bearer fk-your-api-key
Generate API keys at app.factory.ai/settings/api-keys.

​
Base URL

https://app.factory.ai

​
Endpoints

​
List Maturity Reports

Retrieves maturity level reports for your organization. 
GET /api/organization/maturity-level-reports

​
Query Parameters

ParameterTypeRequiredDescription
repoIdstringNoFilter reports by repository ID
limitintegerNoMaximum number of reports to return (must be positive)
startAfterstringNoReport ID for pagination cursor

​
Response

{
  "reports": [
    {
      "reportId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": 1701792000000,
      "repoUrl": "https://github.com/org/repo",
      "apps": {
        "apps/web": {
          "description": "Main Next.js application"
        },
        "apps/api": {
          "description": "Backend API service"
        }
      },
      "report": {
        "lint_config": {
          "numerator": 2,
          "denominator": 2,
          "rationale": "ESLint configured in both applications"
        },
        "type_check": {
          "numerator": 2,
          "denominator": 2,
          "rationale": "TypeScript strict mode enabled"
        }
      },
      "commitHash": "abc123def456",
      "branch": "main",
      "hasLocalChanges": false,
      "hasNonRemoteCommits": false,
      "modelUsed": {
        "id": "claude-sonnet-4-5",
        "reasoningEffort": "high"
      },
      "droidVersion": "0.30.0"
    }
  ]
}

​
Example Request

curl -X GET "https://app.factory.ai/api/organization/maturity-level-reports?limit=10" \
  -H "Authorization: Bearer fk-your-api-key"

​
Report Schema

​
Report Object

FieldTypeDescription
reportIdstringUnique identifier for the report (UUID)
createdAtnumberUnix timestamp in milliseconds when the report was created
repoUrlstringRepository URL that was evaluated
appsobjectMap of application paths to description objects
reportobjectMap of criterion IDs to evaluation results
commitHashstring?Git commit hash at time of evaluation
branchstring?Git branch name at time of evaluation
hasLocalChangesboolean?Whether uncommitted changes existed
hasNonRemoteCommitsboolean?Whether unpushed commits existed
modelUsedobject?Model configuration used for evaluation
droidVersionstring?CLI version that generated the report

​
App Description Object

FieldTypeDescription
descriptionstringBrief description of what the application does

​
Criterion Evaluation Object

FieldTypeDescription
numeratornumberNumber of sub-applications passing the criterion (0 to denominator)
denominatornumberNumber of sub-applications on which the criterion was evaluated (minimum 1)
rationalestringExplanation of the evaluation result

​
Model Used Object

FieldTypeDescription
idstringModel identifier
reasoningEffortstringReasoning effort level (low, medium, high, off)

​
Pagination

For large result sets, use cursor-based pagination:
  1. Make initial request with desired limit
  2. Get the reportId of the last item in the response
  3. Pass that ID as startAfter in the next request
# First page
curl "https://app.factory.ai/api/organization/maturity-level-reports?limit=10"

# Next page (using last reportId from previous response)
curl "https://app.factory.ai/api/organization/maturity-level-reports?limit=10&startAfter=550e8400-e29b-41d4-a716-446655440000"

​
Use Cases

​
CI/CD Integration

Track maturity scores over time by fetching reports after each evaluation: 
# Get latest report for a specific repository
curl "https://app.factory.ai/api/organization/maturity-level-reports?repoId=123&limit=1" \
  -H "Authorization: Bearer $FACTORY_API_KEY"

​
Custom Dashboards

Build internal dashboards by fetching all reports and calculating aggregate metrics: 
const response = await fetch(
  "https://app.factory.ai/api/organization/maturity-level-reports",
  { headers: { Authorization: `Bearer ${apiKey}` } }
);
const { reports } = await response.json();

// Calculate average level
const avgLevel =
  reports.reduce((sum, r) => sum + calculateLevel(r), 0) / reports.length;

​
Automated Alerting

Set up alerts when maturity scores drop below thresholds: 
# Fetch recent reports and check for regressions
reports=$(curl -s "https://app.factory.ai/api/organization/maturity-level-reports?limit=50" \
  -H "Authorization: Bearer $FACTORY_API_KEY")

# Process and alert on regressions...

​
Error Responses

StatusDescription
400Invalid request parameters
401Missing or invalid API key
500Internal server error