Assessment API Documentation
Overview
This API provides endpoints to manage and interact with assessments and submissions in the system. Each API request requires an API token (assessment_api_token) which is associated with a partner in the system. The token must be provided in the Authorization header as a Bearer token.
Base URL
Authentication
All API requests must include the following header:
Authorization: Bearer <assessment_api_token>If the token is invalid or missing, the API will respond with a 401 Unauthorized error.
Endpoints
1. Get All Assessments
Endpoint: /api/assessments
Method: GET
Description: Retrieves a paginated list of all assessments.
Query Parameters:
- page (optional): Page number (default: 1).
- per_page (optional): Number of records per page (default: 20).
{ "total_count": 100, "page": 1, "per_page": 20, "records": [ { "title": "Assessment 1", "description": "Description of assessment", "state": "draft", "uuid": "1234-5678", "price": 50.0 }, ... ] }
2. Get a Single Assessment
Endpoint: /api/assessment/<assessment_uuid>
Method: GET
Description: Retrieves details of a single assessment.
Path Parameters:
- assessment_uuid (string): Unique identifier for the assessment.
Response:
{ "title": "Assessment 1", "description": "Description of assessment", "state": "draft", "uuid": "1234-5678", "price": 50.0, "time_limit": 30, "category_name": "Category 1", "questions": [ { "title": "Question 1", "description": "Description of question", "question_type": "multiple_choice", "difficulty_level": "easy" }, ... ] }
3. Invite Participants to an Assessment
Endpoint: /api/assessment/<assessment_uuid>/invite
Method: POST
Description: Sends an assessment invitation to a list of email addresses.
Path Parameters:
- assessment_uuid (string): Unique identifier for the assessment.
Body Parameters:
- emails (string): Comma-separated list of email addresses (required).
- deadline (string): Deadline for the assessment in ISO 8601 format (YYYY-MM-DDTHH:MM) (optional).
Response:
{ "total_count": 50, "page": 1, "per_page": 20, "records": [ { "email": "user@example.com", "state": "completed", "scoring_percentage": 85, "access_token": "submission-token" }, ... ] }
5. Get a Single Submission
Endpoint: /api/submission/<submission_uuid>
Method: GET
Description: Retrieves details of a single submission.
Path Parameters:
- submission_uuid (string): Unique identifier for the submission.
{
"assessment_id": "1234-5678",
"email": "user@example.com",
"state": "completed",
"scoring_percentage": 85,
"scoring_total": 42,
"total_possible_score": 50,
"scoring_success": true,
"access_token": "submission-token",
"difficulty_level": "medium",
"assessment_state": "open",
"lou": null,
"strengths": "Analytical thinking",
"weaknesses": "Time management",
"areas_for_improvement": "Communication",
"recommendations": "Focus on time-bound tasks",
"analysis": "Detailed feedback here..."
}
Error Responses
Common Errors:
- 401 Unauthorized: Invalid or missing API token.
- 404 Not Found: Resource not found (e.g., invalid assessment_uuid or submission_uuid).
- 429 Too Many Requests: Rate limit exceeded.
- 500 Internal Server Error: Unexpected error on the server.
Rate Limiting
- Each API key is subject to rate limits to prevent abuse:
- Per Minute Limit: Requests exceeding this limit will receive a 429 Too Many Requests error.
- Per Hour Limit: Similar behavior for hourly limits.
Logging
Each API request is logged with the following details:
- Request method
- Request path
- Request body
- Request headers
- Remote address