> ## Documentation Index
> Fetch the complete documentation index at: https://docs.feedback-ai.futureflow-tech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Complete REST API reference for FeedbackAI platform

## Welcome to FeedbackAI API

The FeedbackAI API provides comprehensive programmatic access to all platform features including user management, question sets, test assignments, AI evaluations, and interview sessions.

### Base URL

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

For local development:

```
http://localhost:3000/api
```

### Key Features

<CardGroup cols={2}>
  <Card title="User Management" icon="users">
    Create and manage users with role-based permissions (Admin, Interviewer, Candidate)
  </Card>

  <Card title="Question Sets" icon="list">
    Create and manage mixed question types including coding and short answer questions
  </Card>

  <Card title="Test Assignments" icon="clipboard-check">
    Assign tests to candidates and track progress and results
  </Card>

  <Card title="AI Evaluation" icon="brain">
    Leverage OpenAI for intelligent code evaluation and feedback generation
  </Card>
</CardGroup>

## Authentication

The FeedbackAI API uses Clerk for authentication. Most endpoints require authentication via session tokens.

### Getting Started

1. **Sign Up**: Create an account through the web interface
2. **Get Session Token**: Authenticate via Clerk to receive a session token
3. **Include Token**: Include the token in the Authorization header

```javascript theme={null}
fetch('/api/users', {
  headers: {
    'Authorization': `Bearer ${sessionToken}`,
    'Content-Type': 'application/json'
  }
})
```

### Role-Based Access

API endpoints enforce role-based permissions:

| Role            | Permissions                                          |
| --------------- | ---------------------------------------------------- |
| **Admin**       | Full access to all endpoints                         |
| **Interviewer** | Question management, test assignment, result viewing |
| **Candidate**   | Limited to assigned tests and personal results       |

## Rate Limiting

API requests are rate-limited to ensure fair usage:

* **Free Tier**: 1000 requests/hour
* **Pro Tier**: 10000 requests/hour
* **Enterprise**: Custom limits

## Error Handling

All API responses follow a consistent error format:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "email",
      "issue": "Must be a valid email address"
    }
  }
}
```

### Common Error Codes

* `UNAUTHORIZED` (401): Invalid or missing authentication
* `FORBIDDEN` (403): Insufficient permissions
* `NOT_FOUND` (404): Resource not found
* `VALIDATION_ERROR` (400): Invalid request data
* `RATE_LIMITED` (429): Too many requests

## Response Format

Successful API responses follow this structure:

```json theme={null}
{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100
  }
}
```