API Endpoints Reference

Complete reference for all API endpoints in the AI Store application.

Base URL

All API endpoints are prefixed with /api/.

Authentication

Most endpoints require authentication. Include authentication token in headers:

Authorization: Bearer <token>

Endpoints

Analytics

POST /api/analytics

Track analytics events.

Request Body:

{
  "event": "page_view",
  "properties": {
    "page": "/home",
    "userId": "user-123"
  }
}

Response:

{
  "success": true,
  "eventId": "event-123"
}

Status Codes:

• 200: Success
• 400: Invalid request
• 429: Rate limit exceeded

Errors

POST /api/errors

Log application errors.

Request Body:

{
  "error": {
    "message": "Error message",
    "stack": "Error stack trace"
  },
  "severity": "high",
  "context": {
    "userId": "user-123",
    "page": "/home"
  }
}

Response:

{
  "success": true,
  "errorId": "error-123"
}

Status Codes:

• 200: Success
• 400: Invalid request
• 429: Rate limit exceeded

Events

POST /api/events

Track custom events.

Request Body:

{
  "name": "button_click",
  "category": "interaction",
  "properties": {
    "buttonId": "submit-button",
    "page": "/form"
  }
}

Response:

{
  "success": true,
  "eventId": "event-123"
}

Status Codes:

• 200: Success
• 400: Invalid request
• 429: Rate limit exceeded

Metrics

POST /api/metrics

Record performance metrics.

Request Body:

{
  "name": "page_load_time",
  "value": 1500,
  "unit": "ms",
  "tags": {
    "page": "/home"
  }
}

Response:

{
  "success": true,
  "remaining": 199
}

Status Codes:

• 200: Success
• 400: Invalid request
• 429: Rate limit exceeded

Rate Limiting

All endpoints are rate-limited:

• Default: 100 requests per minute per IP
• Analytics: 200 requests per minute
• Errors: 50 requests per minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Error Responses

Standard Error Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

Error Codes

• INVALID_REQUEST: Invalid request format
• UNAUTHORIZED: Authentication required
• FORBIDDEN: Insufficient permissions
• NOT_FOUND: Resource not found
• RATE_LIMIT_EXCEEDED: Too many requests
• INTERNAL_ERROR: Server error

Request/Response Examples

cURL Examples

# Track analytics event
curl -X POST https://your-domain.com/api/analytics \
  -H "Content-Type: application/json" \
  -d '{
    "event": "page_view",
    "properties": {"page": "/home"}
  }'

# Log error
curl -X POST https://your-domain.com/api/errors \
  -H "Content-Type: application/json" \
  -d '{
    "error": {
      "message": "Error message",
      "stack": "Stack trace"
    },
    "severity": "high"
  }'

JavaScript Examples

// Track event
const response = await fetch('/api/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'button_click',
    category: 'interaction',
  }),
});

const data = await response.json();

Webhooks

Webhook Events

• error.occurred: When an error is logged
• metric.recorded: When a metric is recorded
• event.tracked: When an event is tracked

Webhook Payload

{
  "event": "error.occurred",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "errorId": "error-123",
    "message": "Error message",
    "severity": "high"
  }
}

Testing

Test Endpoints

Use the test environment for development:

https://test.your-domain.com/api/

Mock Responses

For testing, endpoints return mock data when X-Test-Mode: true header is present.

Versioning

API versioning is handled through headers:

API-Version: v1

Current version: v1

Support

For API issues:

1. Check Troubleshooting Guide
2. Review API Documentation
3. Open an issue on GitHub