API Documentation

REST API reference for Production Readiness Audit System

Base URL

https://api.production-audit.dev

All API endpoints are relative to this base URL.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Endpoints

GET/api/health

Health Check

Check API health and availability

Response:

{
  "status": "ok",
  "version": "0.1.0",
  "uptime": 123456
}
POST/api/audit

Run Audit

Queue a production readiness audit for a local project

Requires authentication

Request:

{
  "projectPath": "/path/to/project",
  "options": {
    "ux": true,
    "format": "json",
    "cache": true
  }
}

Response:

{
  "success": true,
  "auditId": "audit_abc123",
  "status": "queued",
  "message": "Audit queued successfully",
  "estimatedTime": "30s"
}
GET/api/audit/:id

Get Audit Result

Retrieve audit results by ID

Requires authentication

Response:

{
  "success": true,
  "audit": {
    "id": "audit_abc123",
    "projectPath": "/path/to/project",
    "projectName": "my-app",
    "status": "completed",
    "createdAt": "2026-01-12T14:00:00Z",
    "completedAt": "2026-01-12T14:00:30Z",
    "score": {
      "overall": 8.5,
      "dimensions": {
        "realData": 9,
        "integrations": 8,
        "features": 7.5,
        "errorHandling": 8.5,
        "testing": 9,
        "security": 9.5,
        "buildHealth": 10,
        "documentation": 7,
        "uxPolish": 8
      }
    },
    "metrics": {
      "totalFiles": 150,
      "filesScanned": 150,
      "mocksDetected": 2,
      "missingIntegrations": 3,
      "stubsFound": 1,
      "missingTests": 5,
      "buildErrors": 0,
      "securityIssues": 0,
      "uxIssues": 4
    }
  }
}
GET/api/teams

List Teams

Get all teams for the authenticated user

Requires authentication

Response:

{
  "success": true,
  "teams": [
    {
      "id": "team_123",
      "name": "Engineering Team",
      "slug": "engineering",
      "plan": "pro",
      "role": "owner",
      "memberCount": 5
    }
  ]
}
POST/api/teams

Create Team

Create a new team

Requires authentication

Request:

{
  "name": "Engineering Team",
  "description": "Our development team",
  "plan": "pro"
}

Response:

{
  "success": true,
  "team": {
    "id": "team_123",
    "name": "Engineering Team",
    "slug": "engineering-team",
    "plan": "pro",
    "maxSeats": 10
  }
}
GET/api/teams/:teamId/members

List Team Members

Get all members of a team

Requires authentication

Response:

{
  "success": true,
  "members": [
    {
      "id": "user_123",
      "email": "user@example.com",
      "fullName": "John Doe",
      "role": "developer",
      "joinedAt": "2026-01-01T00:00:00Z"
    }
  ]
}
POST/api/github/installations

Register GitHub Installation

Register a GitHub App installation

Requires authentication

Request:

{
  "installationId": 12345678,
  "setupAction": "install"
}

Response:

{
  "success": true,
  "message": "Installation registered successfully",
  "installation": {
    "id": 12345678,
    "account": "my-org",
    "repos": [
      "repo1",
      "repo2"
    ]
  }
}
POST/api/github/webhook

GitHub Webhook Handler

Receive GitHub webhook events (internal use)

Response:

{
  "success": true,
  "message": "Webhook processed"
}

Error Responses

400VALIDATION_ERROR

Request validation failed

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Invalid request: projectPath is required"
}
401UNAUTHORIZED

Missing or invalid authentication

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Authentication required"
}
403FORBIDDEN

Insufficient permissions

{
  "success": false,
  "error": "FORBIDDEN",
  "message": "You do not have permission to access this resource"
}
404NOT_FOUND

Resource not found

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Audit not found"
}
429RATE_LIMITED

Too many requests

{
  "success": false,
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded. Try again in 60 seconds."
}
500INTERNAL_ERROR

Internal server error

{
  "success": false,
  "error": "INTERNAL_ERROR",
  "message": "An unexpected error occurred"
}

Rate Limits

PlanRequests/HourAudits/Month
Free10010
Pro1,000Unlimited
Team5,000Unlimited

SDK Examples

JavaScript

import { PrasClient } from '@te-code/pras-sdk'

const client = new PrasClient({
  apiKey: process.env.PRAS_API_KEY
})

// Run an audit
const result = await client.audit.run({
  projectPath: './my-app',
  options: { ux: true, format: 'json' }
})

console.log('Audit ID:', result.auditId)

// Get audit results
const audit = await client.audit.get(result.auditId)
console.log('Score:', audit.score.overall)

Python

from pras import PrasClient

client = PrasClient(api_key=os.environ['PRAS_API_KEY'])

# Run an audit
result = client.audit.run(
    project_path='./my-app',
    options={'ux': True, 'format': 'json'}
)

print(f'Audit ID: {result.audit_id}')

# Get audit results
audit = client.audit.get(result.audit_id)
print(f'Score: {audit.score.overall}')

cURL

# Run an audit
curl -X POST https://api.production-audit.dev/api/audit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectPath": "/path/to/project",
    "options": {"ux": true, "format": "json"}
  }'

# Get audit results
curl -X GET https://api.production-audit.dev/api/audit/audit_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"