Skip to content

API.md

Latest commit

 

History

History
507 lines (385 loc) · 6.93 KB

API.md

File metadata and controls

507 lines (385 loc) · 6.93 KB
Raw

API Documentation

Last Updated: Auto-generated by Autonomous Full-Stack Guardian
Base URL: https://your-app.vercel.app/api (production) or http://localhost:3000/api (development)

Authentication

All API routes (except public endpoints) require authentication via Supabase JWT token.

Headers

Authorization: Bearer <supabase-jwt-token>
Content-Type: application/json

Getting a Token

  1. Authenticate via Supabase Auth
  2. Get token from session
  3. Include token in Authorization header

API Routes

Health & Monitoring

GET /api/health

Check application health.

Response:

{
  "status": "ok",
  "timestamp": "2025-01-XXT00:00:00Z"
}

GET /api/monitoring/health

Detailed health check.

Response:

{
  "status": "ok",
  "database": "connected",
  "supabase": "connected",
  "timestamp": "2025-01-XXT00:00:00Z"
}

GET /api/metrics

Get application metrics.

Response:

{
  "requests": 1000,
  "errors": 5,
  "avgLatency": 120
}

Telemetry & Events

POST /api/telemetry/ingest

Ingest telemetry event.

Request:

{
  "userId": "uuid",
  "app": "web",
  "type": "file_created",
  "path": "/path/to/file",
  "meta": {}
}

Response:

{
  "ok": true,
  "id": "event-uuid"
}

GET /api/telemetry

Get telemetry events.

Query Parameters:

  • userId (required) - User ID
  • limit (optional) - Number of events (default: 50)
  • offset (optional) - Pagination offset

Response:

{
  "events": [
    {
      "id": "uuid",
      "userId": "uuid",
      "type": "file_created",
      "path": "/path/to/file",
      "timestamp": "2025-01-XXT00:00:00Z"
    }
  ],
  "total": 100,
  "limit": 50,
  "offset": 0
}

Privacy & Consent

GET /api/privacy/consent

Get user privacy consent status.

Response:

{
  "consentGiven": true,
  "dataRetentionDays": 14,
  "monitoringEnabled": true
}

POST /api/privacy/consent

Update privacy consent.

Request:

{
  "consentGiven": true,
  "dataRetentionDays": 14,
  "monitoringEnabled": true
}

Response:

{
  "ok": true
}

POST /api/privacy/export

Export user data.

Response:

{
  "downloadUrl": "https://...",
  "expiresAt": "2025-01-XXT00:00:00Z"
}

POST /api/privacy/delete

Delete user data.

Response:

{
  "ok": true,
  "deletedAt": "2025-01-XXT00:00:00Z"
}

Patterns & Insights

GET /api/insights

Get user insights.

Query Parameters:

  • userId (required) - User ID
  • timeRange (optional) - Time range (7d, 30d, 90d)

Response:

{
  "patterns": [
    {
      "fileExtension": ".tsx",
      "count": 150,
      "lastUsed": "2025-01-XXT00:00:00Z"
    }
  ],
  "suggestions": [
    {
      "type": "integration",
      "title": "Consider using TypeScript",
      "description": "..."
    }
  ]
}

GET /api/insights/comparison

Compare patterns over time.

Query Parameters:

  • userId (required) - User ID
  • period1 (required) - First period
  • period2 (required) - Second period

Response:

{
  "period1": {
    "totalFiles": 100,
    "patterns": [...]
  },
  "period2": {
    "totalFiles": 150,
    "patterns": [...]
  },
  "changes": [...]
}

AI & Recommendations

POST /api/ai/chat

Chat with AI assistant.

Request:

{
  "message": "What files should I focus on?",
  "context": {}
}

Response:

{
  "response": "Based on your patterns...",
  "suggestions": [...]
}

GET /api/ai/recommendations

Get AI-powered recommendations.

Query Parameters:

  • userId (required) - User ID

Response:

{
  "recommendations": [
    {
      "type": "tool",
      "title": "Consider using ESLint",
      "reason": "You're using TypeScript frequently",
      "priority": "high"
    }
  ]
}

Cron Jobs

POST /api/privacy/cron/cleanup

Privacy cleanup cron job (requires CRON_SECRET).

Headers:

Authorization: Bearer <CRON_SECRET>

Response:

{
  "success": true,
  "deleted": 50,
  "timestamp": "2025-01-XXT00:00:00Z"
}

GET /api/metrics/collect

Metrics collection cron job (requires CRON_SECRET).

Headers:

Authorization: Bearer <CRON_SECRET>

Response:

{
  "ok": true,
  "collected": 100,
  "timestamp": "2025-01-XXT00:00:00Z"
}

Integrations

GET /api/integrations

List available integrations.

Response:

{
  "integrations": [
    {
      "id": "zapier",
      "name": "Zapier",
      "enabled": true,
      "connected": false
    }
  ]
}

POST /api/integrations/:id/connect

Connect an integration.

Request:

{
  "credentials": {
    "apiKey": "..."
  }
}

Response:

{
  "ok": true,
  "integrationId": "zapier"
}

Error Responses

All errors follow this format:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

Error Codes

  • UNAUTHORIZED - Authentication required
  • FORBIDDEN - Insufficient permissions
  • NOT_FOUND - Resource not found
  • VALIDATION_ERROR - Invalid input
  • INTERNAL_ERROR - Server error

Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

Rate Limiting

API routes are rate-limited:

  • 60 requests per minute per IP
  • 1000 requests per hour per IP

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995200

Webhooks

Zapier Webhooks

POST /api/etl/meta

Meta Ads ETL webhook (requires ZAPIER_SECRET).

Headers:

Authorization: Bearer <ZAPIER_SECRET>

Request:

{
  "data": {}
}

POST /api/etl/tiktok

TikTok Ads ETL webhook (requires ZAPIER_SECRET).

Headers:

Authorization: Bearer <ZAPIER_SECRET>

Request:

{
  "data": {}
}

Examples

cURL Examples

# Get health status
curl https://your-app.vercel.app/api/health

# Ingest telemetry event
curl -X POST https://your-app.vercel.app/api/telemetry/ingest \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "uuid",
    "type": "file_created",
    "path": "/path/to/file"
  }'

# Get insights
curl https://your-app.vercel.app/api/insights?userId=uuid \
  -H "Authorization: Bearer <token>"

JavaScript Examples

// Using fetch
const response = await fetch('https://your-app.vercel.app/api/insights?userId=uuid', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Changelog

  • 2025-01-XX - Initial API documentation
  • All endpoints subject to change

Support

For API issues or questions:

  • Check health reports in /reports
  • Review error logs
  • Create an issue on GitHub