Readiness Reports API - Factory Documentation

The Readiness Reports API provides programmatic access to your organization’s agent readiness 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 Readiness Reports

Retrieves readiness reports for your organization.

GET /api/organization/maturity-level-reports

Query Parameters

Parameter	Type	Required	Description
`repoId`	string	No	Filter reports by repository ID
`limit`	integer	No	Maximum number of reports to return (must be positive)
`startAfter`	string	No	Report 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"

Readiness Report Schema

Report Object

Field	Type	Description
`reportId`	string	Unique identifier for the report (UUID)
`createdAt`	number	Unix timestamp in milliseconds when the report was created
`repoUrl`	string	Repository URL that was evaluated
`apps`	object	Map of application paths to description objects
`report`	object	Map of criterion IDs to evaluation results
`commitHash`	string?	Git commit hash at time of evaluation
`branch`	string?	Git branch name at time of evaluation
`hasLocalChanges`	boolean?	Whether uncommitted changes existed
`hasNonRemoteCommits`	boolean?	Whether unpushed commits existed
`modelUsed`	object?	Model configuration used for evaluation
`droidVersion`	string?	CLI version that generated the report

App Description Object

Field	Type	Description
`description`	string	Brief description of what the application does

Criterion Evaluation Object

Field	Type	Description
`numerator`	number	Number of sub-applications passing the criterion (0 to denominator)
`denominator`	number	Number of sub-applications on which the criterion was evaluated (minimum 1)
`rationale`	string	Explanation of the evaluation result

Model Used Object

Field	Type	Description
`id`	string	Model identifier
`reasoningEffort`	string	Reasoning effort level (`low`, `medium`, `high`, `off`)

Pagination

For large result sets, use cursor-based pagination:

Make initial request with desired limit
Get the reportId of the last item in the response
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 readiness 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 readiness 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

Status	Description
`400`	Invalid request parameters
`401`	Missing or invalid API key
`500`	Internal server error

​Authentication

​Base URL

​Endpoints

​List Readiness Reports

​Query Parameters

​Response

​Example Request

​Readiness Report Schema

​Report Object

​App Description Object

​Criterion Evaluation Object

​Model Used Object

​Pagination

​Use Cases

​CI/CD Integration

​Custom Dashboards

​Automated Alerting

​Error Responses