Tests Overview

The Tests API allows you to manage and access tests within your organization. You can retrieve existing tests, update the tests within your assessments, and leverage our AI to generate new ones.

Endpoints

Method	Endpoint	Description
GET	/tests/organization	Fetches all tests available to your organization.
GET	/tests/assessment/{assessment_id}	Retrieves the tests included in a specific assessment.
PUT	/tests/assessment/{assessment_id}	Updates the tests for a specific assessment.
POST	/tests/create/ai	Creates a new test using the AI test generator.

---

Retrieve All Organization Tests

This endpoint retrieves a list of all tests associated with your organization.

Response 200 OK

[
  {
    "test_id": "string",
    "name": "string",
    "description": "string",
    "skills": ["string"],
    "language": "string",
    "level": "string",
    "created_date": "datetime",
    "created_by": "string"
  }
]

---

Retrieve Tests for an Assessment

This endpoint returns the tests that are part of a specific assessment, identified by its assessment_id.

Path Parameters

Parameter	Type	Description
assessment_id	string	The unique identifier of the assessment.

Response 200 OK

[
  {
    "test_id": "string",
    "name": "string",
    "description": "string",
    "num_questions": "integer",
    "skills": ["string"],
    "language": "string",
    "level": "string",
    "relevancy": "string",
    "description_long": "string",
    "time": "integer"
  }
]

---

Update Tests in an Assessment

This endpoint updates the tests within a specific assessment.

Note: This action will replace all existing tests in the assessment with the ones provided in the request.

Path Parameters

Parameter	Type	Description
assessment_id	string	The unique identifier of the assessment to update.

Request Body

{
  "test_ids": ["string"]
}

Response 200 OK

{
  "message": "Assessment tests updated successfully."
}

---

Create a Test with AI

This endpoint generates a new multiple-choice test using AI based on your specifications.

Request Body

{
  "prompt": "string",
  "language": "string",
  "extended_thinking": "boolean"
}

---

• prompt: A detailed description of the desired test. Include the skills to be assessed, the difficulty level, and any other relevant criteria.
• language: The language for the generated test.
• extended_thinking: Set to true to enable a more advanced generation model for higher-quality test questions.

Response 201 Created

{
  "message": "Test created successfully",
  "test": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Sample Test",
    "description": "Short description",
    "num_questions": 10,
    "skills": [
      "skillA",
      "skillB"
    ],
    "language": "English",
    "level": "Intermediate",
    "relevancy": "",
    "description_long": "",
    "time": 15
  },
  "questions": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "question": "Sample question",
      "options": [
        "optionA",
        "optionB",
        "optionC",
        "optionD"
      ],
      "correct_answer": "optionA",
      "created_at": "NOW()",
      "is_question_bank": false,
      "table": "{\"headers\": [\"Header1\", \"Header2\"], \"rows\": [[\"Row1Cell1\", \"Row1Cell2\"], [\"Row2Cell1\", \"Row2Cell2\"]]}"
    }
  ]
}

---

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request.

Status Code	Description	Common Causes
404 Not Found	The requested resource could not be found.	- Invalid assessment_id or test_id.
422 Unprocessable Entity	The request was well-formed but could not be processed.	- Invalid parameters or request format.
500 Internal Server Error	An unexpected error occurred on the server.	- A system error has occurred; please contact support.