# 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.

```bash
Authorization: Bearer fk-your-api-key
```

[Factory API keys settings](https://app.factory.ai/settings/api-keys)

---

## Base URL

`https://app.factory.ai`

---

## List readiness reports

<Endpoint method="GET" path="/api/organization/agent-readiness-reports">

Retrieves readiness reports for your organization.

<ApiSection title="Query Parameters">
  <ApiField name="repoId" type="string" location="query">Filter reports by repository ID</ApiField>
  <ApiField name="limit" type="integer" location="query">Maximum number of reports to return (must be positive)</ApiField>
  <ApiField name="startAfter" type="string" location="query">Report ID for pagination cursor</ApiField>
</ApiSection>

<ApiSection title="Response">

<StatusBadge status="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"
    }
  ]
}
```

</ApiSection>

<ApiSection title="Example">

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

</ApiSection>

</Endpoint>

---

## Readiness report schema

<ApiSection title="Report Object">
  <ApiField name="reportId" type="string" required>Unique identifier for the report (UUID)</ApiField>
  <ApiField name="createdAt" type="number" required>Unix timestamp in milliseconds when the report was created</ApiField>
  <ApiField name="repoUrl" type="string" required>Repository URL that was evaluated</ApiField>
  <ApiField name="apps" type="object" required>Map of application paths to description objects</ApiField>
  <ApiField name="report" type="object" required>Map of criterion IDs to evaluation results</ApiField>
  <ApiField name="commitHash" type="string">Git commit hash at time of evaluation</ApiField>
  <ApiField name="branch" type="string">Git branch name at time of evaluation</ApiField>
  <ApiField name="hasLocalChanges" type="boolean">Whether uncommitted changes existed</ApiField>
  <ApiField name="hasNonRemoteCommits" type="boolean">Whether unpushed commits existed</ApiField>
  <ApiField name="modelUsed" type="object">Model configuration used for evaluation</ApiField>
  <ApiField name="droidVersion" type="string">CLI version that generated the report</ApiField>
</ApiSection>

<ApiSection title="App Description Object">
  <ApiField name="description" type="string" required>Brief description of what the application does</ApiField>
</ApiSection>

<ApiSection title="Criterion Evaluation Object">
  <ApiField name="numerator" type="number" required>Number of sub-applications passing the criterion (0 to denominator)</ApiField>
  <ApiField name="denominator" type="number" required>Number of sub-applications on which the criterion was evaluated (minimum 1)</ApiField>
  <ApiField name="rationale" type="string" required>Explanation of the evaluation result</ApiField>
</ApiSection>

<ApiSection title="Model Used Object">
  <ApiField name="id" type="string" required>Model identifier</ApiField>
  <ApiField name="reasoningEffort" type="string" required>Reasoning effort level (`low`, `medium`, `high`, `off`)</ApiField>
</ApiSection>

---

## 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      |