Agent Readiness Reports API

REST API for programmatic access to Factory agent readiness reports.

The Agent Readiness Reports API returns Factory readiness evaluations for repositories in your organization.

Authentication

All requests require a Factory API key in the Authorization header.

Authorization header

Authorization: Bearer fk-your-api-key

Generate API keys in the Factory API keys settings.

Base URL

https://app.factory.ai

List readiness reports

GET/api/organization/agent-readiness-reports

Retrieves readiness reports for your organization.

Query Parameters

repoIdstringqueryoptional

Filter reports by repository ID

limitintegerqueryoptional

Maximum number of reports to return (must be positive)

startAfterstringqueryoptional

Report ID for pagination cursor

Response

200

JSON

{
  "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-20250929",
        "reasoningEffort": "high"
      },
      "droidVersion": "0.30.0"
    }
  ]
}

Example

Bash

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

Readiness report schema

Report Object

reportIdstringrequired

Unique identifier for the report (UUID)

createdAtnumberrequired

Unix timestamp in milliseconds when the report was created

repoUrlstringrequired

Repository URL that was evaluated

appsobjectrequired

Map of application paths to description objects

reportobjectrequired

Map 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

descriptionstringrequired

Brief description of what the application does

Criterion Evaluation Object

numeratornumberrequired

Number of sub-applications passing the criterion (0 to denominator)

denominatornumberrequired

Number of sub-applications on which the criterion was evaluated (minimum 1)

rationalestringrequired

Explanation of the evaluation result

Model Used Object

idstringrequired

Model identifier

reasoningEffortstringrequired

Reasoning 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

Bash

# First page
curl "https://app.factory.ai/api/organization/agent-readiness-reports?limit=10"
 
# Next page (using last reportId from previous response)
curl "https://app.factory.ai/api/organization/agent-readiness-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:

Bash

# Get latest report for a specific repository
curl "https://app.factory.ai/api/organization/agent-readiness-reports?repoId=123&limit=1" \
  -H "Authorization: Bearer $FACTORY_API_KEY"

Custom dashboards

Build internal dashboards by fetching all reports and calculating aggregate metrics:

JavaScript

const response = await fetch(
  "https://app.factory.ai/api/organization/agent-readiness-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:

Bash

# Fetch recent reports and check for regressions
reports=$(curl -s "https://app.factory.ai/api/organization/agent-readiness-reports?limit=50" \
  -H "Authorization: Bearer $FACTORY_API_KEY")
 
# Process and alert on regressions...

Errors

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