{ "openapi": "3.0.3", "info": { "title": "Connect API", "version": "1.7.0", "description": "This documentation provides detailed information on how to use CENTURY Tech's Connect API to integrate with your own tools and applications. \n\nThe Connect API allows you to seamlessly access and manage data from the CENTURY Tech platform, such as assessment results, and more. This empowers you to unlock the full potential of your data and insights to understand your students better.\n\nPlease read this documentation carefully before using the Connect API. If you have any questions, please do not hesitate to [contact our customer support team](https://support.century.tech/support/solutions/articles/44001969848-contact-us) or your Account Manager.", "x-feedbackLink": { "label": "Share feedback", "url": "https://docs.google.com/forms/d/e/1FAIpQLSev5HNFWoD_MzD7iCfOLIhL8Ou-CUqv3nq_hFMIx8OaZNTKrw/viewform?usp=sharing" } }, "servers": [ { "description": "Production", "url": "https://connect.century.tech/api/v1" } ], "tags": [ { "name": "Students", "description": "The Student operations in the Connect API provide efficient tools for creating student accounts and assigning classes. These operations streamline the process of adding new students to the system and allocating them to their respective classes, ensuring a smooth and organised onboarding process." }, { "name": "Teachers", "description": "The teacher operations in the Connect API provide efficient tools for creating teacher accounts and assigning those teachers to classes. These operations streamline the process of adding new teachers to the system and allocating them to their respective classes, ensuring a smooth and organised onboarding process." }, { "name": "Users", "description": "Manage user accounts" }, { "name": "Academic Years", "description": "The Academic Year operations to list and retrieve academic years. This includes an operation to easily retrieve information for the current academic year." }, { "name": "Classes", "description": "The Classes operations in the Connect API provide a comprehensive set of tools for managing class-related data. These operations allow for the creation and retrieval of class records. You can assign and remove students or teachers to and from classes." }, { "name": "Smart IA", "description": "The Smart IA operations in the Connect API offers a robust set of operations for managing Initial Assessment sessions, cohorts, and tests. The API enables the retrieval of sessions, allowing for efficient tracking of each student's progress. Cohort operations facilitate effective group management, with features for creating cohorts, assigning users and tests, and removing them as needed.\n\n## Glossary\n\n### Smart IA Session\n\nA Session represents a test attempt by a user on a single Smart IA test. The Session contains a unique identifier, start date and the current status. There are two types of Session, an In Progress and Completed Session, the `status` field is used as a discriminator.\n\n**Schema:** SmartIaSession\n\n### Cohort\n\nGrouping of students for initial assessment\n\n**Schema:** Cohort\n\n### User\n\nThe user is the learner taking the test, the user entity contains personal details and identifiers.\n\n**Schema:** SessionUser\n\n### Test\n\nThe Test entity is the content the learner is taking, the `testId` is unique to the test. The Test entity also contains a `testVersionId`, this field identifiers the test content version.\n\n**Schema:** SessionTest, SmartIaTest\n\n### Result\n\nA `Completed` Session will contain a Result entity. The Result is the outcome of the Session, it will contain the date the result was calculated, the level and total duration of the Session.\n\n**Schema:** SmartIaSessionResult" } ], "x-topics": [ { "title": "Authentication", "content": "# Authenticating with an API Key\n\nYou can authenticate your request by sending your API key in the `x-api-key` header of your request.\n\n```\nx-api-key: YOUR-API-KEY\n```\n\nIn the following example, replace `YOUR-API-KEY` with your key:\n\n```shell\ncurl --request GET \\\n --url \"https://connect.century.tech/api/v1/smart-ia/sessions\" \\\n --header \"x-api-key: YOUR-API-KEY\"\n```\n\nIf you try to use an endpoint without a token or with a token that has insufficient permissions, you will receive a `401 Unauthorized` or `403 Forbidden` response.\n\n> info\n> **Keep your API Key Secret:** Please treat your API key like a password and avoid sharing it publicly \n> or including it in application code that is publicly accessible.\n" }, { "title": "Schema", "content": "## Response Content Type\n\nAll responses will be provided in `application/json` unless stated otherwise in the endpoint description.\n\nWhen other formats are available, a `format` parameter will be provided with a list of supported formats.\n\n## Date and Duration\n\nAll date and duration fields will be formatted using ISO 8601 format. All timestamps will use the UTC time zone.\n\nDate format `YYYY-MM-DD` example:\n\n```\n2010-10-21\n```\n\nDate and time format `YYYY-MM-DDTHH:MM:SS.SSSZ` example:\n\n```\n2023-01-25T16:20:20.000Z\n```\n\nDuration format `PnYnMnDTnHnMnS` example:\n\n```\nPT30M5S\n```\n\n## Empty Values\n\nEmpty fields will be omitted from responses except in the case of a nested object, then a `null` value will be provided.\n\n### Example:\n\n```json\n{\n \"sessionId\": \"\",\n \"startDate\": \"2023-01-25T16:20:20.000Z\",\n \"endDate\": \"2023-01-25T16:20:20.000Z\",\n \"result\": {\n \"level\": \"E3 - Lower\"\n }\n}\n```\n\nIn the example above, `endDate` and `result` can be empty. The example below shows the response when those fields are empty.\n\n```json\n{\n \"sessionId\": \"\",\n \"startDate\": \"2023-01-25T16:20:20.000Z\",\n \"result\": null\n}\n```" }, { "title": "Errors", "content": "The Connect API provides detailed error responses to help you identify and troubleshoot issues. Errors can be returned in two different formats:\n\n* Basic error response that includes status and message fields.\n\n* Problem details response type.\n\n## Basic Error Response\n\nWhen an error occurs, the API may respond with a JSON object containing the following fields:\n\n* `status`: An integer representing the HTTP status code indicating the type of error (e.g., 400 for Bad Request, 404 for Not Found, etc.).\n\n* `message`: A human-readable message providing additional details about the error.\n\n### Example: Basic error response\n\n```json\n{\n \"status\": 404,\n \"message\": \"The requested resource was not found.\"\n}\n```\n\nThe status field will match the HTTP status response.\n\n## Problem Details Response\n\nIn addition to the basic error response, the Connect API also follows the standard Problem response type as described in [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807). The Problem response provides more structured and consistent error information.\n\nThe Problem response includes the following fields:\n\n* `type`: A URI identifying the problem type. This URI helps categorise the error.\n\n* `title`: A short, human-readable summary of the problem.\n\n* `status`: An integer representing the HTTP status code.\n\n* `detail`: A human-readable explanation of the problem in more detail.\n\n* `instance`: A URI that identifies the specific occurrence of the problem. This can be useful for troubleshooting.\n\n### Example: Problem details response\n\n```json\n{\n \"type\": \"https://example.com/errors/not-found\",\n \"title\": \"Resource Not Found\",\n \"status\": 404,\n \"detail\": \"The requested resource was not found.\",\n \"instance\": \"https://example.com/api/v1/users/123\"\n}\n```" }, { "title": "Pagination", "content": "When an endpoint response includes many items the returned data set may be paginated in order to improve performance.\n\nThe reference documentation for endpoints that return a list of results will indicate if the response is paginated. All the information required to page through the results will be contained within a `pagination` field in the response.\n\nThe Connect API offers two types of pagination, basic offset pagination and cursor based pagination. Each endpoint will specify what types of pagination it supports. For more information on pagination and for examples please see the “Using Pagination” guide." }, { "title": "Timeouts", "content": "If requests to the Connect API take longer than 30 seconds to complete then the request will be terminated and the API will return a `504` status response." }, { "title": "Rate Limiting", "content": "All endpoints provided by the Connect API will be subject to rate limits, this is to protect the API from misuse such as excessive polling.\n\nIf you exceed the rate limit the API will respond with `429 Too Many Requests`." }, { "title": "Cross Origin Resource Sharing (CORS)", "content": "The Connect API supports Cross Origin Resource Sharing ([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)) for browser requests from any origin." }, { "title": "Guides", "content": "" }, { "title": "Using Pagination", "content": "The Connect API utilises cursor-based pagination to efficiently retrieve large sets of data. Cursor-based pagination provides \"next\" and \"previous\" cursors in the API response, allowing you to navigate through the dataset effectively.\n\nIn addition to cursor-based pagination, our API also supports basic offset pagination using the `limit` and `offset` fields. This method allows you to fetch data by specifying the number of items you want per page (`limit`) and the starting index of the data (`offset`) in the dataset.\n\nWhen making an API request to and endpoint that is paginated it will respond with a `data` array that includes the results and a `pagination` object tat contains the pagination metadata:\n\n* `total`: The total number of results\n\n* `limit`: The limit specified for the current request, if no limit was specified this will use the endpoint default.\n\n* `offset`: The offset specified for the current request, this will be 0 when using cursors\n\n* `previousCursor`: A cursor that represents the previous page of data. If there is no previous page, this field will be set to `null`.\n\n* `nextCursor`: A cursor that represents the next page of data. If there is no next page, this field will be set to `null`.\n\n# Cursor Pagination\n\nCursor-based pagination is a method that uses unique identifiers (cursors) to mark the position in the dataset. These cursors help you fetch the next or previous page of data as needed. Each cursor points to a specific record in the result set.\n\n## Requesting the Next Page\n\nTo request the next page of data, you should include the `nextCursor` value from the previous response in your subsequent API request. The API will use this cursor to determine where to start fetching the next set of results. If the `nextCursor` is not provided or is `null`, it means you have reached the end of the dataset, and there are no more records to fetch.\n\n## Requesting the Previous Page\n\nTo request the previous page of data, you should include the `previousCursor` value from the previous response in your subsequent API request. The API will use this cursor to determine where to start fetching the previous set of results. If the `previousCursor` is not provided or is `null`, it means you are already at the first page of the dataset, and there are no previous records to fetch.\n\n### Example API Response\n\n```json\n{\n \"data\": [\n {\n \"id\": \"123\",\n \"name\": \"Item 1\",\n \"description\": \"This is item 1\"\n },\n {\n \"id\": \"456\",\n \"name\": \"Item 2\",\n \"description\": \"This is item 2\"\n }\n // Additional items in the current page...\n ],\n \"pagination\": {\n \"total\": 300,\n \"limit\": 20,\n \"offset\": 0,\n \"nextCursor\": \"dXNlcjEwMDA=\",\n \"previousCursor\": \"dXNlcjEwMjQ=\"\n }\n}\n```\n\n### Example next page request\n\n```\nGET /api/data?cursor=dXNlcjEwMjQ=\n```\n\n# Offset Pagination\n\nWhen making an API request for data using offset pagination, you will include the `limit` and `offset` parameters in your query. The API will use these parameters to determine how many records to return (`limit`) and from which position in the dataset to start fetching the data (`offset`).\n\n## Requesting Data with Offset Pagination\n\nTo request data using basic offset pagination, include the following parameters in your API request:\n\n* `limit`: The number of items to return per page. This value must be a integer, representing the maximum number of records to include in the response.\n\n* `offset`: The starting index of the data in the dataset. This value must be a integer, indicating the position of the first record you want to retrieve.\n\n### Example API Request\n\n```\nGET /api/data?limit=10&offset=20\n```\n\nThis API request will fetch 10 records from the dataset, starting from the 21st record (zero-based index)." }, { "title": "Date Filtering", "content": "Available operators for date filtering are:\n\n* `gt` greater than\n\n* `gte` greater than or equal to\n\n* `lt` less than\n\n* `lte` less than or equal to\n\n## Multiple Operators\n\nMultiple operators can be combined to create date range filters. However `gt` and `gte` cannot be used together, and the same applies to `lt` and `lte`.\n\n## Date Formats\n\nYou can use either of the following formats for date filtering:\n\n* **ISO 8601 format**: Dates provided in the ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ) will be correctly interpreted and compared by the API.\n\n* **Unix timestamp**: Unix timestamps (seconds since January 1, 1970) can also be used for date filtering. These timestamps are represented as integers.\n\n### Example Usage\n\nTo get results that start after a specific date:\n\n```\nGET /api/data?startDate[gt]=2023-07-20T00:00:00Z\n```\n\n```\nGET /api/data?startDate[gt]=1679798400\n```\n\nCombine operators to create date range filters\n\n```\nGET /api/data?startDate[gt]=2023-01-20T00:00:00Z&startDate[lt]=2023-07-20T00:00:00Z\n```" }, { "title": "Smart IA Result Levels", "content": "The Smart IA result levels consist of a Level and a Sub-level.\n\nThe format of the level is `[Level] - [Sub-Level]` e.g. `E1 - Lower`\n\n#### Levels\n\n- E1 - Lower\n- E1 - Middle\n- E1 - Higher\n- E2 - Lower\n- E2 - Middle\n- E2 - Higher\n- E3 - Middle\n- E3 - Lower\n- E3 - Higher\n- L1 - Lower\n- L1 - Middle\n- L1 - Higher\n- L2 - Lower\n- L2 - Middle\n- L2 - Higher\n\n#### Additional Levels\n\nIn addition, there are two other outputs that may be returned for specific Initial Assessments:\n\n- NA (English Writing IA where responses have not met the marking criteria) \n- Entry - Below E3 (Digital Skills IA)\n" } ], "security": [ { "ApiKey": [] } ], "paths": { "/academic-years": { "get": { "summary": "List Academic Years", "description": "Returns a list of Academic Years", "operationId": "listAcademicYears", "tags": [ "Academic Years" ], "responses": { "200": { "description": "A list of academic years.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AcademicYear" } } }, "required": [ "data" ] }, "examples": { "ok": { "summary": "OK", "value": { "data": [ { "academicYearId": "dccd109a-08ca-4a18-a277-4653ba726316", "name": "2023/24", "startDate": "2023-08-01T00:00:00.000Z", "endDate": "2024-08-31T23:59:59.000Z" } ] } } } } } }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" } } } }, "/academic-years/current": { "get": { "summary": "Get Current Academic Year", "description": "Returns the current Academic Year", "operationId": "getCurrentAcademicYear", "tags": [ "Academic Years" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "academicYear": { "$ref": "#/components/schemas/AcademicYear" } }, "required": [ "academicYear" ] }, "examples": { "ok": { "summary": "OK", "value": { "academicYear": { "academicYearId": "dccd109a-08ca-4a18-a277-4653ba726316", "name": "2023/24", "startDate": "2023-08-01T00:00:00.000Z", "endDate": "2024-08-31T23:59:59.000Z" } } } } } } }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Academic Year not found." } } } }, "/academic-years/{academicYearId}": { "get": { "summary": "Get Academic Year", "description": "Returns an Academic Year", "operationId": "getAcademicYear", "tags": [ "Academic Years" ], "parameters": [ { "in": "path", "name": "academicYearId", "description": "Academic Year UUID.", "schema": { "$ref": "#/components/schemas/AcademicYearId" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "academicYear": { "$ref": "#/components/schemas/AcademicYear" } }, "required": [ "academicYear" ] }, "examples": { "ok": { "summary": "OK", "value": { "academicYear": { "academicYearId": "dccd109a-08ca-4a18-a277-4653ba726316", "name": "2023/24", "startDate": "2023-08-01T00:00:00.000Z", "endDate": "2024-08-31T23:59:59.000Z" } } } } } } }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Academic Year not found." } } } }, "/classes": { "get": { "summary": "List Classes", "description": "Returns a paginated list of classes", "operationId": "listClasses", "tags": [ "Classes" ], "parameters": [ { "in": "query", "name": "search", "required": false, "description": "Search by class name, exact match only and case insensitive", "schema": { "type": "string" } }, { "in": "query", "name": "academicYearId", "required": false, "description": "Filter classes by academic year ID or provide `current` for the current academic year", "schema": { "anyOf": [ { "$ref": "#/components/schemas/AcademicYearId" }, { "type": "string", "enum": [ "current" ], "description": "Alias for the current Academic Year ID", "example": "current" } ] } }, { "in": "query", "name": "limit", "description": "Specify the pagination limit, defaults to 100", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginationLimit" } ], "title": "Pagination Limit", "format": "int32", "description": "The maximum number of results to return per page.", "example": 30 } }, { "in": "query", "name": "offset", "description": "Specify the pagination offset, defaults to 0.\n\nCannot be used with `cursor`", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginationOffset" } ], "title": "Pagination Offset", "format": "int32", "description": "Indicates the starting position or index (offset)", "example": 100 } }, { "in": "query", "name": "cursor", "required": false, "description": "Provide the next or previous page cursor", "schema": { "$ref": "#/components/schemas/PaginationCursor" } } ], "responses": { "200": { "description": "A list of classes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Class" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } }, "required": [ "data", "pagination" ] }, "examples": { "ok": { "summary": "OK", "value": { "data": [ { "classId": "c81fd38c-03f6-4b68-8720-84a7233e89de", "name": "Algebra 101", "description": "An introductory course to Algebra", "academicYearId": "dccd109a-08ca-4a18-a277-4653ba726316" } ], "pagination": { "total": 300, "limit": 30, "offset": 100, "previousCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=", "nextCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" } } }, "post": { "summary": "Create Class", "description": "Create class", "operationId": "createClass", "tags": [ "Classes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "class": { "$ref": "#/components/schemas/CreateClass" } }, "required": [ "class" ], "description": "If an Academic Year ID is not provided it will default to the current Academic Year" } } } }, "responses": { "201": { "description": "Class created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "class": { "$ref": "#/components/schemas/Class" } }, "required": [ "class" ] }, "examples": { "ok": { "summary": "OK", "value": { "class": { "classId": "c81fd38c-03f6-4b68-8720-84a7233e89de", "name": "Algebra 101", "description": "An introductory course to Algebra", "academicYearId": "dccd109a-08ca-4a18-a277-4653ba726316" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "409": { "description": "Class already exists." } } } }, "/classes/{classId}": { "get": { "summary": "Get Class", "description": "Get a Class", "operationId": "getClass", "tags": [ "Classes" ], "parameters": [ { "in": "path", "name": "classId", "description": "Class UUID.", "schema": { "$ref": "#/components/schemas/ClassId" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "class": { "$ref": "#/components/schemas/Class" } }, "required": [ "class" ] }, "examples": { "ok": { "summary": "OK", "value": { "class": { "classId": "c81fd38c-03f6-4b68-8720-84a7233e89de", "name": "Algebra 101", "description": "An introductory course to Algebra", "academicYearId": "dccd109a-08ca-4a18-a277-4653ba726316" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Class not found." } } } }, "/classes/{classId}/students": { "post": { "summary": "Assign Class Students", "description": "Assign users to a class as students", "operationId": "assignClassStudents", "tags": [ "Classes" ], "parameters": [ { "in": "path", "name": "classId", "description": "Class UUID.", "schema": { "$ref": "#/components/schemas/ClassId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userIds": { "type": "array", "items": { "$ref": "#/components/schemas/UserId" }, "minItems": 1, "maxItems": 100, "description": "The list of user IDs." } }, "required": [ "userIds" ] } } } }, "responses": { "204": { "description": "Students assigned successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Class not found." } } }, "delete": { "x-draft": true, "x-scalar-stability": "experimental", "summary": "Remove Class Students", "description": "Remove students from a class", "operationId": "removeClassStudents", "tags": [ "Classes" ], "parameters": [ { "in": "path", "name": "classId", "description": "Class UUID.", "schema": { "$ref": "#/components/schemas/ClassId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userIds": { "type": "array", "items": { "$ref": "#/components/schemas/UserId" }, "description": "The list of user IDs." } }, "required": [ "userIds" ] } } } }, "responses": { "204": { "description": "Students removed successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Class not found." } } } }, "/classes/{classId}/teachers": { "post": { "summary": "Assign Class Teachers", "description": "Assign users to a class as teachers", "operationId": "assignClassTeachers", "tags": [ "Classes" ], "parameters": [ { "in": "path", "name": "classId", "description": "Class UUID.", "schema": { "$ref": "#/components/schemas/ClassId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userIds": { "type": "array", "items": { "$ref": "#/components/schemas/UserId" }, "minItems": 1, "maxItems": 100, "description": "The list of user IDs." } }, "required": [ "userIds" ] } } } }, "responses": { "204": { "description": "Teachers assigned successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Class not found." } } }, "delete": { "x-draft": true, "x-scalar-stability": "experimental", "summary": "Remove Class Teachers", "description": "Remove teachers from a class", "operationId": "removeClassTeachers", "tags": [ "Classes" ], "parameters": [ { "in": "path", "name": "classId", "description": "Class UUID.", "schema": { "$ref": "#/components/schemas/ClassId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userIds": { "type": "array", "items": { "$ref": "#/components/schemas/UserId" }, "minItems": 1, "maxItems": 100, "description": "The list of user IDs." } }, "required": [ "userIds" ] } } } }, "responses": { "204": { "description": "Teachers removed successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Class not found." } } } }, "/smart-ia/cohorts": { "get": { "summary": "List Cohorts", "description": "Returns a paginated list of Smart IA Cohorts", "operationId": "listCohorts", "tags": [ "Smart IA" ], "parameters": [ { "in": "query", "name": "search", "required": false, "description": "Search by cohort name, exact match only and case insensitive", "schema": { "type": "string" } }, { "in": "query", "name": "academicYearId", "required": false, "description": "Filter cohorts by academic year ID or provide `current` for the current academic year", "schema": { "anyOf": [ { "$ref": "#/components/schemas/AcademicYearId" }, { "type": "string", "enum": [ "current" ], "description": "Alias for the current Academic Year ID", "example": "current" } ] } }, { "in": "query", "name": "limit", "description": "Specify the pagination limit, defaults to 100", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginationLimit" } ], "title": "Pagination Limit", "format": "int32", "description": "The maximum number of results to return per page.", "example": 30 } }, { "in": "query", "name": "offset", "description": "Specify the pagination offset, defaults to 0.\n\nCannot be used with `cursor`", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginationOffset" } ], "title": "Pagination Offset", "format": "int32", "description": "Indicates the starting position or index (offset)", "example": 100 } }, { "in": "query", "name": "cursor", "required": false, "description": "Provide the next or previous page cursor", "schema": { "$ref": "#/components/schemas/PaginationCursor" } } ], "responses": { "200": { "description": "A paginated list of cohorts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Cohort" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } }, "required": [ "data", "pagination" ] }, "examples": { "ok": { "summary": "OK", "value": { "data": [ { "cohortId": "c334f818-0281-4f47-855a-3a3d0e356cfd", "name": "Cohort 2023", "description": "This cohort is for students graduating in 2023", "academicYearId": "dccd109a-08ca-4a18-a277-4653ba726316", "tests": [ { "testId": "c5a77fda-7174-446f-a4f5-0f47ccbf15ce", "testVersionId": "38444333-7450-49d5-922d-eb16a8f30589", "name": "English Initial Test", "subject": "English", "activationStatus": "active" } ] } ], "pagination": { "total": 300, "limit": 30, "offset": 100, "previousCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=", "nextCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" } } }, "post": { "summary": "Create Cohort", "description": "Create a Smart IA Cohort", "operationId": "createCohort", "tags": [ "Smart IA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cohort": { "$ref": "#/components/schemas/CreateCohort" } }, "required": [ "cohort" ], "description": "If an Academic Year ID is not provided it will default to the current Academic Year" } } } }, "responses": { "201": { "description": "Cohort created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cohort": { "$ref": "#/components/schemas/Cohort" } }, "required": [ "cohort" ] }, "examples": { "ok": { "summary": "OK", "value": { "class": { "cohortId": "c334f818-0281-4f47-855a-3a3d0e356cfd", "name": "Cohort 2023", "description": "This cohort is for students graduating in 2023", "academicYearId": "dccd109a-08ca-4a18-a277-4653ba726316", "tests": [ { "testId": "c5a77fda-7174-446f-a4f5-0f47ccbf15ce", "testVersionId": "38444333-7450-49d5-922d-eb16a8f30589", "name": "English Initial Test", "subject": "English", "activationStatus": "active" } ] } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "409": { "description": "Cohort already exists." } } } }, "/smart-ia/cohorts/{cohortId}": { "get": { "summary": "Get Cohort", "description": "Get a Smart IA Cohort", "operationId": "getCohort", "tags": [ "Smart IA" ], "parameters": [ { "in": "path", "name": "cohortId", "description": "Cohort UUID.", "schema": { "$ref": "#/components/schemas/CohortId" }, "required": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "cohort": { "$ref": "#/components/schemas/Cohort" } }, "required": [ "cohort" ] }, "examples": { "ok": { "summary": "OK", "value": { "class": { "cohortId": "c334f818-0281-4f47-855a-3a3d0e356cfd", "name": "Cohort 2023", "description": "This cohort is for students graduating in 2023", "academicYearId": "dccd109a-08ca-4a18-a277-4653ba726316", "tests": [ { "testId": "c5a77fda-7174-446f-a4f5-0f47ccbf15ce", "testVersionId": "38444333-7450-49d5-922d-eb16a8f30589", "name": "English Initial Test", "subject": "English", "activationStatus": "active" } ] } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Cohort not found." } } } }, "/smart-ia/cohorts/{cohortId}/students": { "post": { "x-draft": true, "x-scalar-stability": "experimental", "summary": "Assign Cohort Students", "description": "Assign students to a Smart IA Cohort", "operationId": "assignCohortStudents", "tags": [ "Smart IA" ], "parameters": [ { "in": "path", "name": "cohortId", "description": "Cohort UUID.", "schema": { "$ref": "#/components/schemas/CohortId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userIds": { "type": "array", "items": { "$ref": "#/components/schemas/UserId" }, "description": "The list of user IDs." } }, "required": [ "userIds" ] } } } }, "responses": { "204": { "description": "Students assigned successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Cohort not found." } } }, "delete": { "x-draft": true, "x-scalar-stability": "experimental", "summary": "Remove Cohort Students", "description": "Remove students from a Smart IA Cohort", "operationId": "removeCohortStudents", "tags": [ "Smart IA" ], "parameters": [ { "in": "path", "name": "cohortId", "description": "Cohort UUID.", "schema": { "$ref": "#/components/schemas/CohortId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userIds": { "type": "array", "items": { "$ref": "#/components/schemas/UserId" }, "description": "The list of user IDs." } }, "required": [ "userIds" ] } } } }, "responses": { "204": { "description": "Students removed successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Cohort not found." } } } }, "/smart-ia/cohorts/{cohortId}/tests": { "post": { "x-draft": true, "x-scalar-stability": "experimental", "summary": "Assign Cohort Tests", "description": "Assign Smart IA Tests to a Cohort", "operationId": "assignCohortTests", "tags": [ "Smart IA" ], "parameters": [ { "in": "path", "name": "cohortId", "description": "Cohort UUID.", "schema": { "$ref": "#/components/schemas/CohortId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "testIds": { "type": "array", "items": { "$ref": "#/components/schemas/SmartIaTestId" }, "description": "The list of Smart IA Test IDs." } }, "required": [ "testIds" ] } } } }, "responses": { "204": { "description": "Tests assigned successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Cohort not found." } } }, "delete": { "x-draft": true, "x-scalar-stability": "experimental", "summary": "Remove Cohort Tests", "description": "Remove Smart IA Tests from a Cohort", "operationId": "removeCohortTests", "tags": [ "Smart IA" ], "parameters": [ { "in": "path", "name": "cohortId", "description": "Cohort UUID.", "schema": { "$ref": "#/components/schemas/CohortId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "testIds": { "type": "array", "items": { "$ref": "#/components/schemas/SmartIaTestId" }, "description": "The list of Smart IA Test IDs." } }, "required": [ "testIds" ] } } } }, "responses": { "204": { "description": "Tests removed successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "Cohort not found." } } } }, "/smart-ia/tests": { "get": { "x-draft": true, "x-scalar-stability": "experimental", "summary": "List Smart IA Tests", "description": "Returns a list of Smart IA tests", "operationId": "listSmartIaTests", "tags": [ "Smart IA" ], "responses": { "200": { "description": "A list of Smart IA Tests.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SmartIaTest" } } }, "required": [ "data" ] }, "examples": { "ok": { "summary": "OK", "value": { "data": [ { "testId": "c5a77fda-7174-446f-a4f5-0f47ccbf15ce", "name": "English Smart Initial Assessment", "subject": "English" } ] } } } } } }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" } } } }, "/users": { "get": { "summary": "List Users", "description": "Search users\n\nA `POST` version of this endpoint is provided if a large number of filters are required.\n\nReturns a paginated list of users", "operationId": "listUsers", "tags": [ "Users" ], "parameters": [ { "in": "query", "name": "userId", "required": false, "style": "form", "explode": true, "description": "Filter the results by user ID.\n\nMultiple identifiers can be specified by repeating the query parameter. e.g. `userId=value1&userId=value2`\n\nThis parameter supports a maximum of 30 identifiers.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserId" }, "minItems": 1, "maxItems": 30 } }, { "in": "query", "name": "upn", "required": false, "style": "form", "explode": true, "description": "Filter the results by user UPN.\n\nMultiple identifiers can be specified by repeating the query parameter. e.g. `upn=value1&upn=value2`\n\nThis parameter supports a maximum of 30 identifiers.", "schema": { "type": "array", "items": { "type": "string", "example": "Y89421121401A", "description": "The Unique Pupil Number (UPN) of the user." }, "minItems": 1, "maxItems": 30 } }, { "in": "query", "name": "externalId", "required": false, "style": "form", "explode": true, "description": "Filter the results by external ID.\n\nMultiple identifiers can be specified by repeating the query parameter. e.g. `externalId=value1&externalId=value2`\n\nThis parameter supports a maximum of 30 identifiers.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "minItems": 1, "maxItems": 30 } }, { "in": "query", "name": "username", "required": false, "style": "form", "explode": true, "description": "Filter the results by username.\n\nMultiple identifiers can be specified by repeating the query parameter. e.g. `username=value1&username=value2`\n\nThis parameter supports a maximum of 30 identifiers.", "schema": { "type": "array", "items": { "type": "string", "example": "john_doe", "description": "The username of the user." }, "minItems": 1, "maxItems": 30 } }, { "in": "query", "name": "email", "required": false, "description": "Filter the results by email address.", "schema": { "type": "string", "format": "email", "example": "john.doe@email.com" } }, { "in": "query", "name": "name", "required": false, "description": "Filter the results by the user's name.", "schema": { "type": "string", "minLength": 1 } }, { "in": "query", "name": "role", "required": false, "description": "Filter the results by user role.", "schema": { "$ref": "#/components/schemas/UserRole" } }, { "in": "query", "name": "limit", "description": "Specify the pagination limit, defaults to 100", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginationLimit" } ], "title": "Pagination Limit", "format": "int32", "description": "The maximum number of results to return per page.", "example": 30 } }, { "in": "query", "name": "offset", "description": "Specify the pagination offset, defaults to 0.\n\nCannot be used with `cursor`", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginationOffset" } ], "title": "Pagination Offset", "format": "int32", "description": "Indicates the starting position or index (offset)", "example": 100 } }, { "in": "query", "name": "cursor", "required": false, "description": "Provide the next or previous page cursor", "schema": { "$ref": "#/components/schemas/PaginationCursor" } }, { "in": "query", "name": "sort", "required": false, "style": "deepObject", "explode": true, "description": "Specify the sort order of the results.\n\nThe default sort order is `sort[field]=createdAt&sort[direction]=desc`", "schema": { "$ref": "#/components/schemas/UserSort" } } ], "responses": { "200": { "description": "List of users.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } }, "required": [ "data", "pagination" ] }, "examples": { "ok": { "summary": "Paginated list of users", "value": { "data": [ { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "upn": "Y89421121401A", "roles": [ "student" ], "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01", "createdAt": "2024-01-01T12:00:00Z", "updatedAt": "2024-01-01T12:00:00Z" } ], "pagination": { "total": 300, "limit": 30, "offset": 100, "previousCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=", "nextCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" } } } }, "/users/search": { "post": { "summary": "Search Users", "description": "Returns a paginated list of users\n\nThis endpoint should be used if there are more than 30 values for any given filter.", "operationId": "searchUsers", "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "object", "properties": { "userIds": { "type": "array", "items": { "$ref": "#/components/schemas/UserId" }, "description": "List of User IDs to filter by" }, "upns": { "type": "array", "items": { "type": "string", "example": "Y89421121401A", "description": "The Unique Pupil Number (UPN) of the user." }, "description": "List of UPNs to filter by" }, "externalIds": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "description": "List of External IDs to filter by" }, "usernames": { "type": "array", "items": { "type": "string", "example": "john_doe", "description": "The username of the user." }, "description": "List of Usernames to filter by" }, "email": { "type": "string", "format": "email", "example": "john.doe@email.com", "description": "User email address to filter by" }, "name": { "type": "string", "minLength": 1, "description": "Filter the results by the user's name.", "example": "John" }, "role": { "$ref": "#/components/schemas/UserRole" } }, "title": "Sessions Search Query" }, "limit": { "$ref": "#/components/schemas/PaginationLimit" }, "offset": { "$ref": "#/components/schemas/PaginationOffset" }, "cursor": { "$ref": "#/components/schemas/PaginationCursor" }, "sort": { "$ref": "#/components/schemas/UserSort" } } } } } }, "responses": { "200": { "description": "List of users.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } }, "required": [ "data", "pagination" ] }, "examples": { "ok": { "summary": "Paginated list of users", "value": { "data": [ { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "upn": "Y89421121401A", "roles": [ "student" ], "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01", "createdAt": "2024-01-01T12:00:00Z", "updatedAt": "2024-01-01T12:00:00Z" } ], "pagination": { "total": 300, "limit": 30, "offset": 100, "previousCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=", "nextCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" } } } }, "/users/{userId}/disable": { "post": { "summary": "Disable User", "description": "Disable an existing user account.", "operationId": "disableUser", "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "userId", "description": "User UUID.", "schema": { "$ref": "#/components/schemas/UserId" }, "required": true } ], "responses": { "204": { "description": "User disabled successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "User not found." } } } }, "/users/{userId}/enable": { "post": { "summary": "Enable User", "description": "Enables an user account.", "operationId": "enableUser", "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "userId", "description": "User UUID.", "schema": { "$ref": "#/components/schemas/UserId" }, "required": true } ], "responses": { "204": { "description": "User enabled successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "User not found." } } } }, "/students": { "post": { "summary": "Create Student User", "description": "Create a new student user account and assign it to one or more classes and cohorts.", "operationId": "createStudent", "tags": [ "Students" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/CreateStudent" }, "classIds": { "type": "array", "items": { "$ref": "#/components/schemas/ClassId" }, "description": "The IDs of the classes to which the user should be assigned." }, "cohortIds": { "type": "array", "items": { "$ref": "#/components/schemas/CohortId" }, "description": "The IDs of the cohorts to which the user should be assigned." } }, "required": [ "user" ] } } } }, "responses": { "201": { "description": "Student created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ] }, "examples": { "ok": { "summary": "OK", "value": { "user": { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "upn": "Y89421121401A", "roles": [ "student" ], "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01", "createdAt": "2024-01-01T12:00:00Z", "updatedAt": "2024-01-01T12:00:00Z" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "409": { "description": "User already exists." } } } }, "/students/{userId}/classes": { "post": { "summary": "Assign Student Classes", "description": "Assign classes to a student user", "operationId": "assignStudentClasses", "tags": [ "Students" ], "parameters": [ { "in": "path", "name": "userId", "description": "User UUID.", "schema": { "$ref": "#/components/schemas/UserId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "classIds": { "type": "array", "items": { "$ref": "#/components/schemas/ClassId" }, "minItems": 1, "description": "The list of class IDs." } }, "required": [ "classIds" ] } } } }, "responses": { "204": { "description": "Classes assigned successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "User not found." } } }, "delete": { "summary": "Remove Student Classes", "description": "Remove classes from a student user", "operationId": "removeStudentClasses", "tags": [ "Students" ], "parameters": [ { "in": "path", "name": "userId", "description": "User UUID.", "schema": { "$ref": "#/components/schemas/UserId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "classIds": { "type": "array", "items": { "$ref": "#/components/schemas/ClassId" }, "minItems": 1, "description": "The list of class IDs." } }, "required": [ "classIds" ] } } } }, "responses": { "204": { "description": "Classes removed successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "User not found." } } } }, "/students/{userId}/cohorts": { "post": { "summary": "Assign Student Cohorts", "description": "Assign cohorts to a student user", "operationId": "assignStudentCohorts", "tags": [ "Students" ], "parameters": [ { "in": "path", "name": "userId", "description": "User UUID.", "schema": { "$ref": "#/components/schemas/UserId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cohortIds": { "type": "array", "items": { "$ref": "#/components/schemas/CohortId" }, "minItems": 1, "description": "The list of class IDs." } }, "required": [ "cohortIds" ] } } } }, "responses": { "204": { "description": "Cohorts assigned successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "User not found." } } } }, "/teachers": { "post": { "summary": "Create Teacher User", "description": "Create a new teacher user account and assign it to one or more class (as a teacher).", "operationId": "createTeacher", "tags": [ "Teachers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/CreateTeacher" }, "classIds": { "type": "array", "items": { "$ref": "#/components/schemas/ClassId" }, "description": "The IDs of the classes to which the user should be assigned." } }, "required": [ "user" ] } } } }, "responses": { "201": { "description": "Teacher created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ] }, "examples": { "ok": { "summary": "OK", "value": { "user": { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "upn": "Y89421121401A", "roles": [ "teacher" ], "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01", "createdAt": "2024-01-01T12:00:00Z", "updatedAt": "2024-01-01T12:00:00Z" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "409": { "description": "User already exists." } } } }, "/teachers/{userId}/classes": { "post": { "summary": "Assign Teacher Classes", "description": "Assign a user to classes as a teacher", "operationId": "assignTeacherClasses", "tags": [ "Teachers" ], "parameters": [ { "in": "path", "name": "userId", "description": "User UUID.", "schema": { "$ref": "#/components/schemas/UserId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "classIds": { "type": "array", "items": { "$ref": "#/components/schemas/ClassId" }, "minItems": 1, "description": "The list of class IDs." } }, "required": [ "classIds" ] } } } }, "responses": { "204": { "description": "Classes assigned successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "User not found." } } }, "delete": { "summary": "Remove Teacher Classes", "description": "Remove user as a teacher from classes", "operationId": "removeTeacherClasses", "tags": [ "Teachers" ], "parameters": [ { "in": "path", "name": "userId", "description": "User UUID.", "schema": { "$ref": "#/components/schemas/UserId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "classIds": { "type": "array", "items": { "$ref": "#/components/schemas/ClassId" }, "minItems": 1, "description": "The list of class IDs." } }, "required": [ "classIds" ] } } } }, "responses": { "204": { "description": "Classes removed successfully." }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "User not found." } } } }, "/users/{userId}/password": { "put": { "summary": "Update User Password", "description": "Update user password", "operationId": "updateUserPassword", "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "userId", "description": "User UUID.", "schema": { "$ref": "#/components/schemas/UserId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "minLength": 8, "description": "New user password", "format": "password" } }, "required": [ "password" ] } } } }, "responses": { "200": { "description": "User password updated succssfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ] }, "examples": { "ok": { "summary": "OK", "value": { "user": { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "upn": "Y89421121401A", "roles": [ "student" ], "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01", "createdAt": "2024-01-01T12:00:00Z", "updatedAt": "2024-01-01T12:00:00Z" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "User not found." } } } }, "/users/{userId}/name": { "put": { "summary": "Update User Name", "description": "Update user name", "operationId": "updateUserName", "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "userId", "description": "User UUID.", "schema": { "$ref": "#/components/schemas/UserId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "description": "The first name of the user.", "example": "John" }, "lastName": { "type": "string", "minLength": 1, "description": "The last name of the user.", "example": "Doe" } }, "required": [ "firstName", "lastName" ] } } } }, "responses": { "200": { "description": "User name updated succssfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ] }, "examples": { "ok": { "summary": "OK", "value": { "user": { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "upn": "Y89421121401A", "roles": [ "student" ], "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01", "createdAt": "2024-01-01T12:00:00Z", "updatedAt": "2024-01-01T12:00:00Z" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "User not found." } } } }, "/users/{userId}/emails/primary": { "put": { "summary": "Update User Primary Email", "description": "Update user's primary email address", "operationId": "updateUserPrimaryEmail", "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "userId", "description": "User UUID.", "schema": { "$ref": "#/components/schemas/UserId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "New primary email address.", "example": "john.doe@email.com" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Email updated succssfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ] }, "examples": { "ok": { "summary": "OK", "value": { "user": { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "upn": "Y89421121401A", "roles": [ "student" ], "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01", "createdAt": "2024-01-01T12:00:00Z", "updatedAt": "2024-01-01T12:00:00Z" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "User not found." } } } }, "/students/{userId}/details": { "patch": { "summary": "Update Student Details", "description": "Update the students's gender and date of birth", "operationId": "updateStudentDetails", "tags": [ "Students" ], "parameters": [ { "in": "path", "name": "userId", "description": "User UUID.", "schema": { "$ref": "#/components/schemas/UserId" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gender": { "$ref": "#/components/schemas/UserGender" }, "dateOfBirth": { "type": "string", "format": "date", "example": "2010-07-01", "description": "The date of birth of the user." } } } } } }, "responses": { "200": { "description": "Student details updated succssfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ] }, "examples": { "ok": { "summary": "OK", "value": { "user": { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "upn": "Y89421121401A", "roles": [ "student" ], "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01", "createdAt": "2024-01-01T12:00:00Z", "updatedAt": "2024-01-01T12:00:00Z" } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" }, "404": { "description": "User not found." } } } }, "/smart-ia/sessions": { "get": { "summary": "List Smart IA Sessions", "description": "Provides a general purpose endpoint to search both \"In Progress\" and \"Completed\" Smart IA Sessions\n\nA `POST` version of this endpoint is provided if a large number of filters are required.\n\nReturns a paginated list of completed and in progress sessions", "operationId": "listSmartIaSessions", "tags": [ "Smart IA" ], "parameters": [ { "$ref": "#/components/parameters/startDate" }, { "$ref": "#/components/parameters/endDate" }, { "$ref": "#/components/parameters/userId" }, { "$ref": "#/components/parameters/testId" }, { "$ref": "#/components/parameters/subject" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/cursor" }, { "in": "query", "name": "status", "required": false, "description": "Filter sessions by status", "schema": { "$ref": "#/components/schemas/SmartIaSessionStatus" } }, { "in": "query", "name": "sort", "required": false, "style": "deepObject", "explode": true, "description": "Specify the sort order of the results.\n\nThe default sort order is `sort[field]=startDate&sort[direction]=asc`", "schema": { "$ref": "#/components/schemas/SmartIaSessionSort" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SmartIaSession" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } }, "required": [ "data", "pagination" ], "title": "ListSmartIaSessionsResponse" }, "examples": { "Session List": { "summary": "A paginated list of Smart IA sessions", "value": { "data": [ [ { "sessionId": "d93ba3c3-2482-4b0d-8b99-42a20e68e11e", "startDate": "2023-07-10T14:00:00.000Z", "endDate": "2023-07-10T15:30:00.000Z", "status": "COMPLETED", "user": { "userId": "2716be03-cec0-4027-a373-46b53fb6a08d", "username": "john_doe", "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male" }, "test": { "testId": "c5a77fda-7174-446f-a4f5-0f47ccbf15ce", "testVersionId": "38444333-7450-49d5-922d-eb16a8f30589", "name": "English Smart Initial Assessment", "subject": "English" }, "result": { "createdDate": "2023-07-10T15:30:00.000Z", "level": "L1 - Lower", "duration": "PT1H30M" } }, { "sessionId": "9f8a38c6-9194-480e-bb5f-9155b7636580", "startDate": "2023-07-10T14:00:00.000Z", "status": "IN_PROGRESS", "user": { "userId": "b4334e39-0fa9-4278-8b61-c7aa7e6c8d5e", "username": "jane_doe", "fullName": "Jane Doe", "firstName": "Jane", "lastName": "Doe", "gender": "female" }, "test": { "testId": "c5a77fda-7174-446f-a4f5-0f47ccbf15ce", "testVersionId": "38444333-7450-49d5-922d-eb16a8f30589", "name": "English Smart Initial Assessment", "subject": "English" } } ] ], "pagination": { "total": 300, "limit": 30, "offset": 100, "previousCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=", "nextCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=" } } } } } } }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" } } } }, "/smart-ia/sessions/search": { "post": { "summary": "Search Smart IA Sessions", "description": "Returns a paginated list of completed and in progress sessions\n\nThis endpoint should be used if there are more than 30 values for any given filter.", "operationId": "searchSmartIaSessions", "tags": [ "Smart IA" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "object", "properties": { "startDate": { "$ref": "#/components/schemas/DateQueryOperators" }, "endDate": { "$ref": "#/components/schemas/DateQueryOperators" }, "userIds": { "type": "array", "items": { "$ref": "#/components/schemas/UserId" } }, "testIds": { "type": "array", "items": { "$ref": "#/components/schemas/SmartIaTestId" } }, "subjects": { "type": "array", "items": { "type": "string" } }, "status": { "$ref": "#/components/schemas/SmartIaSessionStatus" } }, "title": "Sessions Search Query" }, "limit": { "$ref": "#/components/schemas/PaginationLimit" }, "offset": { "$ref": "#/components/schemas/PaginationOffset" }, "cursor": { "$ref": "#/components/schemas/PaginationCursor" }, "sort": { "description": "Specify the sort order of the results.\n\nThe default sort order is `{\"field\": \"startDate\", \"direction\": \"asc\"}`", "allOf": [ { "$ref": "#/components/schemas/SmartIaSessionSort" } ] } } }, "examples": { "Completed Sessions Date Range": { "summary": "Search completed sessions within a date range", "value": { "limit": 100, "offset": 0, "search": { "endDate": { "gt": "2023-01-01T12:00:00.000Z", "lt": "2023-06-01T12:00:00.000Z" }, "status": "COMPLETED" }, "sort": { "field": "endDate", "direction": "desc" } } }, "Completed Sessions After Date": { "summary": "Search completed sessions after a given date", "value": { "limit": 100, "offset": 0, "search": { "endDate": { "gt": "2023-01-01T12:00:00.000Z" }, "status": "COMPLETED" }, "sort": { "field": "endDate", "direction": "desc" } } }, "Completed Sessions For Test": { "summary": "Search completed sessions for a given test", "value": { "limit": 100, "offset": 0, "search": { "testIds": [ "c5a77fda-7174-446f-a4f5-0f47ccbf15ce" ], "status": "COMPLETED" }, "sort": { "field": "endDate", "direction": "desc" } } }, "User Sessions": { "summary": "Search all user sessions", "value": { "limit": 100, "offset": 0, "search": { "userIds": [ "2716be03-cec0-4027-a373-46b53fb6a08d" ] }, "sort": { "field": "startDate", "direction": "desc" } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SmartIaSession" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } }, "required": [ "data", "pagination" ], "title": "SearchSmartIaSessionsResponse" }, "examples": { "Session List": { "summary": "A paginated list of Smart IA sessions", "value": { "data": [ [ { "sessionId": "d93ba3c3-2482-4b0d-8b99-42a20e68e11e", "startDate": "2023-07-10T14:00:00.000Z", "endDate": "2023-07-10T15:30:00.000Z", "status": "COMPLETED", "user": { "userId": "2716be03-cec0-4027-a373-46b53fb6a08d", "username": "john_doe", "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male" }, "test": { "testId": "c5a77fda-7174-446f-a4f5-0f47ccbf15ce", "testVersionId": "38444333-7450-49d5-922d-eb16a8f30589", "name": "English Smart Initial Assessment", "subject": "English" }, "result": { "createdDate": "2023-07-10T15:30:00.000Z", "level": "L1 - Lower", "duration": "PT1H30M" } }, { "sessionId": "9f8a38c6-9194-480e-bb5f-9155b7636580", "startDate": "2023-07-10T14:00:00.000Z", "status": "IN_PROGRESS", "user": { "userId": "b4334e39-0fa9-4278-8b61-c7aa7e6c8d5e", "username": "jane_doe", "fullName": "Jane Doe", "firstName": "Jane", "lastName": "Doe", "gender": "female" }, "test": { "testId": "c5a77fda-7174-446f-a4f5-0f47ccbf15ce", "testVersionId": "38444333-7450-49d5-922d-eb16a8f30589", "name": "English Smart Initial Assessment", "subject": "English" } } ] ], "pagination": { "total": 300, "limit": 30, "offset": 100, "previousCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=", "nextCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=" } } } } } } }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" } } } }, "/smart-ia/sessions/completed": { "get": { "summary": "List Completed Smart IA Sessions", "description": "Convenience method that only return \"Completed\" Smart IA Sessions\n\nReturns a paginated list of completed sessions", "operationId": "listCompletedSmartIaSessions", "tags": [ "Smart IA" ], "parameters": [ { "$ref": "#/components/parameters/startDate" }, { "$ref": "#/components/parameters/endDate" }, { "$ref": "#/components/parameters/userId" }, { "$ref": "#/components/parameters/testId" }, { "$ref": "#/components/parameters/subject" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/cursor" }, { "in": "query", "name": "sort", "required": false, "style": "deepObject", "explode": true, "description": "Specify the sort order of the results.\n\nThe default sort order is `sort[field]=startDate&sort[direction]=asc`", "schema": { "$ref": "#/components/schemas/SmartIaSessionSort" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompletedSmartIaSession" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } }, "required": [ "data", "pagination" ], "title": "ListCompletedSmartIaSessionsResponse" }, "examples": { "Session List": { "summary": "A paginated list of completed sessions", "value": { "data": [ { "sessionId": "d93ba3c3-2482-4b0d-8b99-42a20e68e11e", "startDate": "2023-07-10T14:00:00.000Z", "endDate": "2023-07-10T15:30:00.000Z", "status": "COMPLETED", "user": { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01" }, "test": { "testId": "c5a77fda-7174-446f-a4f5-0f47ccbf15ce", "testVersionId": "38444333-7450-49d5-922d-eb16a8f30589", "name": "English Smart Initial Assessment", "subject": "English" }, "result": { "createdDate": "2023-07-10T15:30:00.000Z", "level": "L1 - Lower", "duration": "PT1H30M" } } ], "pagination": { "total": 300, "limit": 30, "offset": 100, "previousCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=", "nextCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=" } } } } } } }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" } } } }, "/smart-ia/sessions/in-progress": { "get": { "summary": "List In Progress Smart IA Sessions", "description": "Convenience method that only return \"In Progress\" Smart IA Sessions\n\nReturns a paginated list of in progress sessions", "operationId": "listInProgressSmartIaSessions", "tags": [ "Smart IA" ], "parameters": [ { "$ref": "#/components/parameters/startDate" }, { "$ref": "#/components/parameters/userId" }, { "$ref": "#/components/parameters/testId" }, { "$ref": "#/components/parameters/subject" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/cursor" }, { "in": "query", "name": "sort", "required": false, "style": "deepObject", "explode": true, "description": "Specify the sort order of the results.\n\nThe default sort order is `sort[field]=startDate&sort[direction]=asc`", "schema": { "$ref": "#/components/schemas/SmartIaSessionSort" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/InProgressSmartIaSession" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } }, "required": [ "data", "pagination" ], "title": "ListInProgressSmartIaSessionsResponse" }, "examples": { "Session List": { "summary": "A paginated list of in progress sessions", "value": { "data": [ { "sessionId": "d93ba3c3-2482-4b0d-8b99-42a20e68e11e", "startDate": "2023-07-10T14:00:00.000Z", "status": "IN_PROGRESS", "user": { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01" }, "test": { "testId": "c5a77fda-7174-446f-a4f5-0f47ccbf15ce", "testVersionId": "38444333-7450-49d5-922d-eb16a8f30589", "name": "English Smart Initial Assessment", "subject": "English" } } ], "pagination": { "total": 300, "limit": 30, "offset": 100, "previousCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=", "nextCursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=" } } } } } } }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" } } } }, "/sessions/completed": { "get": { "summary": "List Completed Study Sessions", "description": "Provides a general purpose endpoint to search Completed Study Sessions.\n\nThe date range is limited to a maximum of 12 months, if no filters are provided it defaults to the last 12 months.\n\n**Date Range Behavior**:\n- If no date filters are provided, it defaults to the last 12 months.\n- If only `endDate[lte]` is provided, `endDate[gte]` will default to 12 months prior to `endDate[lte]`.\n- If only `endDate[gte]` is provided, `endDate[lte]` will default to 12 months after `endDate[gte]`.\n\n**Nugget Filters**:\n\nNugget filters are combined when used together. For example, specifying both `nuggetId` and a `courseId` will include nuggets from both the specified IDs and the course.\n\n**User Filters**:\n\nUser filters are combined when used together and allow you to specify users by `userId`, `externalId`, or `classId`. When using `classId`, the results will include study sessions for all users within the specified class.", "operationId": "listCompletedStudySessions", "tags": [ "Sessions" ], "parameters": [ { "in": "query", "name": "endDate", "required": false, "style": "deepObject", "explode": true, "description": "Filter the results by session end date\n\nSupports either a ISO 8601 formatted date or a Unix timestamp. \nFor example `endDate[gte]=1688200245` or `endDate[lte]=2023-07-15T12:00:00.000Z`", "examples": { "updatedSince": { "description": "Sessions completed since a specified date", "value": { "gte": "2024-06-23T14:32:45.628Z" } }, "between": { "description": "Sessions completed between a specified date range", "value": { "gte": "2024-06-23T14:32:45.628Z", "lte": "2024-07-28T16:21:13.315Z" } } }, "schema": { "$ref": "#/components/schemas/DateQuerySimpleOperators" } }, { "in": "query", "name": "userId", "required": false, "style": "form", "explode": true, "description": "Filter the results by user ID.\n\nMultiple identifiers can be specified by repeating the query parameter. e.g. `userId=value1&userId=value2`\n\nThis parameter supports a maximum of 30 identifiers.", "examples": { "single": { "description": "Filter by a single user ID", "value": [ "68f06c66-702a-4c26-b8c5-b6dc4f81f25d" ] }, "multiple": { "description": "Filter by a multiple user IDs", "value": [ "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "7e1e2623-6191-46a9-866e-5f9c30c853ad" ] } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserId" }, "minItems": 1, "maxItems": 30 } }, { "in": "query", "name": "externalId", "required": false, "style": "form", "explode": true, "description": "Filter the results by external ID.\n\nMultiple identifiers can be specified by repeating the query parameter. e.g. `externalId=value1&externalId=value2`\n\nThis parameter supports a maximum of 30 identifiers.", "examples": { "single": { "description": "Filter by a single external ID", "value": [ "External_ID_123" ] }, "multiple": { "description": "Filter by a multiple external IDs", "value": [ "External_ID_123", "External_ID_456" ] } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalId" }, "minItems": 1, "maxItems": 30 } }, { "in": "query", "name": "nuggetId", "required": false, "style": "form", "explode": true, "description": "Filter the results by nugget ID.\n\nMultiple identifiers can be specified by repeating the query parameter. e.g. `nuggetId=value1&nuggetId=value2`\n\nThis parameter supports a maximum of 30 identifiers.", "examples": { "single": { "description": "Filter by a single nugget ID", "value": [ "bc5f8904-c844-4c8a-8231-872e5c84dc8b" ] }, "multiple": { "description": "Filter by a multiple nugget IDs", "value": [ "bc5f8904-c844-4c8a-8231-872e5c84dc8b", "c043ac6a-a3c7-4d93-b300-0e88d15f3dbd" ] } }, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/NuggetId" }, "minItems": 1, "maxItems": 30 } }, { "in": "query", "name": "classId", "required": false, "description": "Filter the results by class ID.", "schema": { "$ref": "#/components/schemas/ClassId" } }, { "in": "query", "name": "courseId", "required": false, "description": "Filter the results by course ID.", "schema": { "$ref": "#/components/schemas/CourseId" } }, { "in": "query", "name": "sort", "required": false, "style": "deepObject", "explode": true, "description": "Specify the sort order of the results.\n\nThe default sort order is `sort[field]=endDate&sort[direction]=asc`", "schema": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "endDate" ], "title": "Completed Study Session Sort Field", "description": "The available sort fields.", "example": "endDate", "default": "endDate" }, "direction": { "allOf": [ { "$ref": "#/components/schemas/SortDirection" } ], "default": "asc" } } } }, { "in": "query", "name": "limit", "description": "The maximum number of sessions to return per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100, "title": "Pagination Limit", "format": "int32", "description": "The maximum number of sessions to return per page.", "example": 100 } }, { "in": "query", "name": "offset", "description": "Indicates the starting position or index (offset)", "schema": { "$ref": "#/components/schemas/PaginationOffset" } }, { "in": "query", "name": "cursor", "schema": { "$ref": "#/components/schemas/PaginationCursor" } } ], "responses": { "200": { "description": "List of Study Sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompletedStudySession" } }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } }, "required": [ "data", "pagination" ], "title": "ListCompletedStudySessionsResponse" }, "examples": { "graded": { "summary": "Graded Study Sessions", "value": { "data": [ { "studySessionId": "67bf476e17ed9cccd58c1fb4", "kind": "GRADED", "user": { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "upn": "Y89421121401A", "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01" }, "nugget": { "nuggetId": "bc5f8904-c844-4c8a-8231-872e5c84dc8b", "name": "Addition [MF1.01]", "diagnostic": false }, "startDate": "2024-23-06T12:05:23.456Z", "endDate": "2024-23-06T12:08:48.578Z", "metrics": { "questionsAnswered": 24, "correctAnswers": 13, "pointsAchieved": 13, "pointsPossible": 24, "score": 54.16666667, "completion": 90, "duration": "PT3M25S" } } ], "pagination": { "total": 1, "limit": 100, "offset": 0, "previousCursor": null, "nextCursor": null } } }, "nonGraded": { "summary": "Non-Graded Study Sessions", "value": { "data": [ { "studySessionId": "67bf476e17ed9cccd58c1fb4", "kind": "NON_GRADED", "user": { "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d", "username": "john_doe", "upn": "Y89421121401A", "externalId": "External_ID_123", "fullName": "John Doe", "firstName": "John", "lastName": "Doe", "emails": [ "john.doe@email.com" ], "gender": "male", "dateOfBirth": "2010-07-01" }, "nugget": { "nuggetId": "bc5f8904-c844-4c8a-8231-872e5c84dc8b", "name": "Addition [MF1.01]", "diagnostic": false }, "startDate": "2024-23-06T12:05:23.456Z", "endDate": "2024-23-06T12:08:48.578Z", "metrics": { "completion": 90.456, "duration": "PT3M25S" } } ], "pagination": { "total": 1, "limit": 100, "offset": 0, "previousCursor": null, "nextCursor": null } } } } } } }, "400": { "description": "Invalid request." }, "401": { "description": "Invalid authentication credentials" }, "403": { "description": "Not authorised to access this resource" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "name": "x-api-key", "in": "header" } }, "schemas": { "AcademicYear": { "type": "object", "properties": { "academicYearId": { "$ref": "#/components/schemas/AcademicYearId" }, "name": { "type": "string", "description": "The name of the Academic Year", "example": "2023/24" }, "startDate": { "$ref": "#/components/schemas/DateTime" }, "endDate": { "$ref": "#/components/schemas/DateTime" } }, "required": [ "academicYearId", "name", "startDate", "endDate" ], "title": "Academic Year" }, "AcademicYearId": { "type": "string", "format": "uuid", "title": "Academic Year ID", "description": "Academic Year UUID.", "example": "dccd109a-08ca-4a18-a277-4653ba726316" }, "DateTime": { "type": "string", "format": "date-time", "title": "ISO 8601 DateTime", "example": "2023-07-01T08:30:45.000Z" }, "PaginationLimit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "title": "Pagination Limit", "format": "int32", "description": "The maximum number of results to return per page.", "example": 30 }, "PaginationOffset": { "type": "integer", "default": 0, "title": "Pagination Offset", "format": "int32", "description": "Indicates the starting position or index (offset)", "example": 100 }, "PaginationCursor": { "type": "string", "nullable": true, "title": "Pagination Cursor", "format": "byte", "description": "The cursor for pagination. Encoded byte string used to navigate between pages.", "example": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=" }, "Class": { "type": "object", "properties": { "classId": { "$ref": "#/components/schemas/ClassId" }, "name": { "type": "string", "description": "The name of the class", "example": "Algebra 101" }, "description": { "type": "string", "description": "Optional class description", "example": "An introductory course to Algebra" }, "academicYearId": { "$ref": "#/components/schemas/AcademicYearId" } }, "required": [ "classId", "name", "academicYearId" ], "title": "Class" }, "ClassId": { "type": "string", "format": "uuid", "title": "Class ID", "description": "Class UUID.", "example": "c81fd38c-03f6-4b68-8720-84a7233e89de" }, "PaginationMetadata": { "type": "object", "properties": { "total": { "type": "integer", "format": "int32", "description": "The total number of items available.", "example": 300 }, "limit": { "$ref": "#/components/schemas/PaginationLimit" }, "offset": { "$ref": "#/components/schemas/PaginationOffset" }, "previousCursor": { "$ref": "#/components/schemas/PaginationCursor" }, "nextCursor": { "$ref": "#/components/schemas/PaginationCursor" } }, "required": [ "total", "limit", "offset", "previousCursor", "nextCursor" ], "title": "Pagination Metadata", "description": "Metadata for the current pagination position" }, "CreateClass": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the class", "example": "Algebra 101" }, "description": { "type": "string", "description": "Optional class description", "example": "An introductory course to Algebra" }, "academicYearId": { "$ref": "#/components/schemas/AcademicYearId" } }, "required": [ "name" ], "title": "Create Class", "description": "If an Academic Year ID is not provided it will default to the current Academic Year" }, "UserId": { "type": "string", "format": "uuid", "title": "User ID", "description": "User UUID.", "example": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d" }, "Cohort": { "type": "object", "properties": { "cohortId": { "$ref": "#/components/schemas/CohortId" }, "name": { "type": "string", "description": "The name of the cohort", "example": "Cohort 2023" }, "description": { "type": "string", "description": "Optional cohort description", "example": "This cohort is for students graduating in 2023" }, "academicYearId": { "$ref": "#/components/schemas/AcademicYearId" }, "tests": { "type": "array", "items": { "$ref": "#/components/schemas/CohortTest" } } }, "required": [ "cohortId", "name", "academicYearId", "tests" ], "title": "Cohort" }, "CohortId": { "type": "string", "format": "uuid", "title": "Cohort ID", "description": "Cohort UUID.", "example": "c334f818-0281-4f47-855a-3a3d0e356cfd" }, "CohortTest": { "type": "object", "properties": { "testId": { "$ref": "#/components/schemas/SmartIaTestId" }, "testVersionId": { "$ref": "#/components/schemas/SmartIaTestVersionId" }, "name": { "type": "string", "description": "The name of the Smart IA test.", "example": "English Initial Test" }, "subject": { "type": "string", "description": "The subject of the Smart IA test.", "example": "English" }, "activationStatus": { "$ref": "#/components/schemas/TestActivationStatus" } }, "required": [ "testId", "testVersionId", "name", "subject", "activationStatus" ], "title": "Cohort Test" }, "SmartIaTestId": { "type": "string", "format": "uuid", "title": "Smart IA Test ID", "description": "The Smart IA test ID", "example": "c5a77fda-7174-446f-a4f5-0f47ccbf15ce" }, "SmartIaTestVersionId": { "type": "string", "format": "uuid", "title": "Smart IA Test Version ID", "description": "The unique identifier for the Smart IA test version (UUID).", "example": "38444333-7450-49d5-922d-eb16a8f30589" }, "TestActivationStatus": { "type": "string", "enum": [ "active", "inactive", "deactivated" ], "title": "Test Activation Status", "example": "active" }, "CreateCohort": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the cohort", "example": "Cohort 2023" }, "description": { "type": "string", "description": "Optional cohort description", "example": "This cohort is for students graduating in 2023" }, "academicYearId": { "$ref": "#/components/schemas/AcademicYearId" }, "tests": { "type": "array", "items": { "type": "object", "properties": { "testId": { "$ref": "#/components/schemas/SmartIaTestId" }, "active": { "type": "boolean", "default": true, "description": "Activation status, set to true to activate the tests for Cohort users", "example": true } }, "required": [ "testId" ] } } }, "required": [ "name" ], "title": "Create Cohort", "description": "If an Academic Year ID is not provided it will default to the current Academic Year" }, "SmartIaTest": { "type": "object", "properties": { "testId": { "$ref": "#/components/schemas/SmartIaTestId" }, "name": { "type": "string", "description": "The name of the Smart IA test.", "example": "English Smart Initial Assessment" }, "subject": { "type": "string", "description": "The subject of the Smart IA test.", "example": "English" } }, "required": [ "testId", "name", "subject" ], "title": "Smart" }, "ExternalId": { "type": "string", "title": "External ID", "description": "Identifier from an external source", "example": "External_ID_123" }, "UserRole": { "type": "string", "enum": [ "manager", "editor", "leadership", "guardian", "teacher", "student" ], "title": "User Role", "description": "User roles", "example": "student" }, "UserSort": { "type": "object", "properties": { "field": { "$ref": "#/components/schemas/UserSortField" }, "direction": { "$ref": "#/components/schemas/SortDirection" } }, "title": "User Sort" }, "UserSortField": { "type": "string", "enum": [ "createdAt", "updatedAt", "firstName", "lastName" ], "title": "User Sort Field", "description": "The available sort fields.", "example": "createdAt" }, "SortDirection": { "type": "string", "enum": [ "asc", "desc" ], "title": "Sort Direction", "description": "The sort direction used for ordering the results. Can be \"asc\" (ascending) or \"desc\" (descending).", "example": "asc" }, "User": { "type": "object", "properties": { "userId": { "$ref": "#/components/schemas/UserId" }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/UserRole" } }, "username": { "type": "string", "example": "john_doe", "description": "The username of the user." }, "upn": { "type": "string", "example": "Y89421121401A", "description": "The Unique Pupil Number (UPN) of the user." }, "externalId": { "$ref": "#/components/schemas/ExternalId" }, "fullName": { "type": "string", "description": "The full name of the user.", "example": "John Doe" }, "firstName": { "type": "string", "description": "The first name of the user.", "example": "John" }, "middleName": { "type": "string", "description": "The middle name of the user." }, "lastName": { "type": "string", "description": "The last name of the user.", "example": "Doe" }, "emails": { "type": "array", "items": { "type": "string", "format": "email", "example": "john.doe@email.com" }, "description": "A list of all email addresses associated with the user." }, "gender": { "$ref": "#/components/schemas/UserGender" }, "dateOfBirth": { "type": "string", "format": "date", "example": "2010-07-01", "description": "The date of birth of the user." }, "createdAt": { "$ref": "#/components/schemas/DateTime" }, "updatedAt": { "$ref": "#/components/schemas/DateTime" } }, "required": [ "userId", "username", "fullName", "firstName", "lastName", "gender" ], "title": "User" }, "UserGender": { "type": "string", "enum": [ "male", "female", "other", "unknown" ], "description": "The gender of the user.", "default": "unknown", "example": "male" }, "CreateStudent": { "type": "object", "properties": { "firstName": { "type": "string", "description": "The first name of the user.", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the user.", "example": "Doe" }, "username": { "type": "string", "description": "The username of the user, if one is not provided it will be automatically generated", "example": "john_doe" }, "email": { "type": "string", "format": "email", "example": "john.doe@email.com", "description": "The email address of the user." }, "password": { "type": "string", "format": "password", "description": "If no password is supplied the user will need to reset their password or sign in via SSO e.g. Google, Office 365" }, "upn": { "type": "string", "example": "Y89421121401A", "description": "The Unique Pupil Number (UPN) of the user." }, "externalId": { "$ref": "#/components/schemas/ExternalId" }, "gender": { "$ref": "#/components/schemas/UserGender" }, "dateOfBirth": { "type": "string", "format": "date", "example": "2010-07-01", "description": "The date of birth of the user." } }, "required": [ "firstName", "lastName" ], "title": "Create Student", "description": "`username` or `email` must be provided" }, "CreateTeacher": { "type": "object", "properties": { "firstName": { "type": "string", "description": "The first name of the user.", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the user.", "example": "Doe" }, "username": { "type": "string", "description": "The username of the user, if one is not provided it will be automatically generated", "example": "john_doe" }, "email": { "type": "string", "format": "email", "example": "john.doe@email.com", "description": "The email address of the user." }, "password": { "type": "string", "format": "password", "description": "If no password is supplied the user will need to reset their password or sign in via SSO e.g. Google, Office 365" }, "externalId": { "$ref": "#/components/schemas/ExternalId" } }, "required": [ "firstName", "lastName" ], "title": "Create Teacher", "description": "`username` or `email` must be provided" }, "DateQueryOperators": { "type": "object", "properties": { "gt": { "$ref": "#/components/schemas/DateTimeOrTimestamp" }, "gte": { "$ref": "#/components/schemas/DateTimeOrTimestamp" }, "lt": { "$ref": "#/components/schemas/DateTimeOrTimestamp" }, "lte": { "$ref": "#/components/schemas/DateTimeOrTimestamp" } }, "title": "Date Query Operators", "description": "Use the following operators to add date Filtering. You can combine multiple filters to create a range filter. \n\nPlease see the Date Filtering guide for more details" }, "DateTimeOrTimestamp": { "oneOf": [ { "$ref": "#/components/schemas/Timestamp" }, { "$ref": "#/components/schemas/DateTime" } ], "title": "Date Time or Timestamp" }, "Timestamp": { "type": "integer", "title": "Unix Timestamp", "format": "int32", "example": 1688200245 }, "SmartIaSessionStatus": { "type": "string", "enum": [ "IN_PROGRESS", "COMPLETED" ], "title": "Smart IA Session Status", "description": "Enum value describing the status of the session" }, "SmartIaSessionSort": { "type": "object", "properties": { "field": { "$ref": "#/components/schemas/SmartIaSessionSortField" }, "direction": { "$ref": "#/components/schemas/SortDirection" } }, "title": "Smart IA Session Sort" }, "SmartIaSessionSortField": { "type": "string", "enum": [ "startDate", "endDate" ], "title": "Smart IA Session Sort Field", "description": "The available sort fields.", "example": "startDate" }, "SmartIaSession": { "oneOf": [ { "$ref": "#/components/schemas/InProgressSmartIaSession" }, { "$ref": "#/components/schemas/CompletedSmartIaSession" } ], "discriminator": { "propertyName": "status", "mapping": { "IN_PROGRESS": "#/components/schemas/InProgressSmartIaSession", "COMPLETED": "#/components/schemas/CompletedSmartIaSession" } }, "title": "Smart IA Session" }, "InProgressSmartIaSession": { "type": "object", "properties": { "sessionId": { "$ref": "#/components/schemas/SmartIaSessionId" }, "startDate": { "$ref": "#/components/schemas/DateTime" }, "status": { "type": "string", "enum": [ "IN_PROGRESS" ], "description": "The status of the Smart IA session, for in progress sessions this will always be \"IN_PROGRESS\"." }, "user": { "$ref": "#/components/schemas/SessionUser" }, "test": { "$ref": "#/components/schemas/SessionTest" } }, "required": [ "sessionId", "startDate", "status", "user", "test" ], "title": "In Progress Smart IA Session" }, "SmartIaSessionId": { "type": "string", "format": "uuid", "title": "Smart IA Session ID", "description": "The unique identifier for the Smart IA session (UUID).", "example": "d93ba3c3-2482-4b0d-8b99-42a20e68e11e" }, "SessionUser": { "type": "object", "properties": { "userId": { "$ref": "#/components/schemas/UserId" }, "username": { "type": "string", "example": "john_doe", "description": "The username of the user." }, "upn": { "type": "string", "example": "Y89421121401A", "description": "The Unique Pupil Number (UPN) of the user." }, "externalId": { "$ref": "#/components/schemas/ExternalId" }, "fullName": { "type": "string", "example": "John Doe", "description": "The full name of the user." }, "firstName": { "type": "string", "example": "John", "description": "The first name of the user." }, "middleName": { "type": "string", "description": "The middle name of the user." }, "lastName": { "type": "string", "example": "Doe", "description": "The last name of the user." }, "emails": { "type": "array", "items": { "type": "string", "format": "email", "example": "john.doe@email.com" }, "description": "A list of all email addresses associated with the user." }, "gender": { "$ref": "#/components/schemas/UserGender" }, "dateOfBirth": { "type": "string", "format": "date", "example": "2010-07-01", "description": "The date of birth of the user." } }, "required": [ "userId", "username", "fullName", "firstName", "lastName", "gender" ], "title": "Session User" }, "SessionTest": { "type": "object", "properties": { "testId": { "$ref": "#/components/schemas/SmartIaTestId" }, "testVersionId": { "$ref": "#/components/schemas/SmartIaTestVersionId" }, "name": { "type": "string", "description": "The name of the Smart IA test.", "example": "English Smart Initial Assessment" }, "subject": { "type": "string", "description": "The subject of the Smart IA test.", "example": "English" } }, "required": [ "testId", "testVersionId", "name", "subject" ], "title": "Session Test" }, "CompletedSmartIaSession": { "type": "object", "properties": { "sessionId": { "$ref": "#/components/schemas/SmartIaSessionId" }, "startDate": { "$ref": "#/components/schemas/DateTime" }, "endDate": { "$ref": "#/components/schemas/DateTime" }, "status": { "type": "string", "enum": [ "COMPLETED" ], "description": "The status of the Smart IA session, for completed sessions this will always be \"COMPLETED\"." }, "user": { "$ref": "#/components/schemas/SessionUser" }, "test": { "$ref": "#/components/schemas/SessionTest" }, "result": { "$ref": "#/components/schemas/SmartIaSessionResult" } }, "required": [ "sessionId", "startDate", "endDate", "status", "user", "test", "result" ], "title": "Completed Smart IA Session" }, "SmartIaSessionResult": { "type": "object", "properties": { "createdDate": { "$ref": "#/components/schemas/DateTime" }, "level": { "type": "string", "example": "E2 - Lower", "description": "The result outcome" }, "duration": { "$ref": "#/components/schemas/Duration" } }, "required": [ "createdDate", "level", "duration" ], "title": "Smart IA Session Result" }, "Duration": { "type": "string", "title": "Duration", "example": "PT1H30M", "format": "duration", "description": "Duration in ISO 8601 duration format" }, "DateQuerySimpleOperators": { "type": "object", "properties": { "gte": { "$ref": "#/components/schemas/DateTimeOrTimestamp" }, "lte": { "$ref": "#/components/schemas/DateTimeOrTimestamp" } }, "title": "Date Query Simple Operators", "description": "Use the following operators to add date Filtering. You can combine gte and lte filters to create a range filter. \n\nPlease see the Date Filtering guide for more details" }, "NuggetId": { "type": "string", "format": "uuid", "title": "Nugget ID", "description": "Nugget UUID.", "example": "bc5f8904-c844-4c8a-8231-872e5c84dc8b" }, "CourseId": { "type": "string", "format": "uuid", "title": "Course ID", "description": "Course UUID.", "example": "c334f818-0281-4f47-855a-3a3d0e356cfd" }, "CompletedStudySession": { "oneOf": [ { "$ref": "#/components/schemas/CompletedGradedStudySession" }, { "$ref": "#/components/schemas/CompletedNonGradedStudySession" } ], "discriminator": { "propertyName": "kind", "mapping": { "GRADED": "#/components/schemas/CompletedGradedStudySession", "NON_GRADED": "#/components/schemas/CompletedNonGradedStudySession" } }, "title": "Completed Study Session" }, "CompletedGradedStudySession": { "type": "object", "properties": { "studySessionId": { "$ref": "#/components/schemas/StudySessionId" }, "kind": { "type": "string", "enum": [ "GRADED" ] }, "user": { "$ref": "#/components/schemas/StudySessionUser" }, "nugget": { "$ref": "#/components/schemas/StudySessionNugget" }, "startDate": { "$ref": "#/components/schemas/DateTime" }, "endDate": { "$ref": "#/components/schemas/DateTime" }, "metrics": { "$ref": "#/components/schemas/StudySessionGradedMetrics" } }, "required": [ "studySessionId", "kind", "user", "nugget", "startDate", "endDate", "metrics" ], "title": "Completed Graded Study Session", "description": "A study session that has a score" }, "StudySessionId": { "type": "string", "title": "Study Session ID", "description": "Study Session UUID.", "example": "67bf476e17ed9cccd58c1fb4" }, "StudySessionUser": { "type": "object", "properties": { "userId": { "$ref": "#/components/schemas/UserId" }, "username": { "type": "string", "example": "john_doe", "description": "The username of the user." }, "upn": { "type": "string", "example": "Y89421121401A", "description": "The Unique Pupil Number (UPN) of the user." }, "externalId": { "$ref": "#/components/schemas/ExternalId" }, "fullName": { "type": "string", "example": "John Doe", "description": "The full name of the user." }, "firstName": { "type": "string", "example": "John", "description": "The first name of the user." }, "middleName": { "type": "string", "description": "The middle name of the user." }, "lastName": { "type": "string", "example": "Doe", "description": "The last name of the user." }, "emails": { "type": "array", "items": { "type": "string", "format": "email", "example": "john.doe@email.com" }, "description": "A list of all email addresses associated with the user." }, "gender": { "$ref": "#/components/schemas/UserGender" }, "dateOfBirth": { "type": "string", "format": "date", "example": "2010-07-01", "description": "The date of birth of the user." } }, "required": [ "userId", "username", "fullName", "firstName", "lastName", "gender" ], "title": "Study Session User", "description": "User that has completed the study session" }, "StudySessionNugget": { "type": "object", "properties": { "nuggetId": { "$ref": "#/components/schemas/NuggetId" }, "name": { "type": "string", "description": "Name of the nugget", "example": "Addition [MF1.01]" }, "diagnostic": { "type": "boolean", "description": "Is a diagnostic nugget", "example": false } }, "required": [ "nuggetId", "name", "diagnostic" ], "title": "Study Session Nugget", "description": "The nugget that has been completed" }, "StudySessionGradedMetrics": { "type": "object", "properties": { "questionsAnswered": { "type": "number", "example": 24, "description": "Number of questions answered" }, "correctAnswers": { "type": "number", "example": 13, "description": "Number of questions answered correctly" }, "pointsAchieved": { "type": "number", "example": 13, "description": "Number of points achieved" }, "pointsPossible": { "type": "number", "example": 24, "description": "Total number of points possible" }, "score": { "$ref": "#/components/schemas/Percentage" }, "completion": { "$ref": "#/components/schemas/Percentage" }, "duration": { "$ref": "#/components/schemas/Duration" } }, "required": [ "questionsAnswered", "correctAnswers", "pointsAchieved", "pointsPossible", "score", "completion", "duration" ], "title": "Study Session Graded Metrics", "description": "Score, completion and duration metrics", "example": { "questionsAnswered": 24, "correctAnswers": 13, "pointsAchieved": 13, "pointsPossible": 24, "score": 54.16666667, "completion": 90, "duration": "PT3M25S" } }, "Percentage": { "type": "number", "minimum": 0, "maximum": 100, "title": "Percentage", "example": 90.456, "format": "float", "description": "Percentage value between 0 and 100 floating point value" }, "CompletedNonGradedStudySession": { "type": "object", "properties": { "studySessionId": { "$ref": "#/components/schemas/StudySessionId" }, "kind": { "type": "string", "enum": [ "NON_GRADED" ] }, "user": { "$ref": "#/components/schemas/StudySessionUser" }, "nugget": { "$ref": "#/components/schemas/StudySessionNugget" }, "startDate": { "$ref": "#/components/schemas/DateTime" }, "endDate": { "$ref": "#/components/schemas/DateTime" }, "metrics": { "$ref": "#/components/schemas/StudySessionNonGradedMetrics" } }, "required": [ "studySessionId", "kind", "user", "nugget", "startDate", "endDate", "metrics" ], "title": "Completed Non-Graded Study Session", "description": "A study session for a nugget that contained no questions" }, "StudySessionNonGradedMetrics": { "type": "object", "properties": { "completion": { "$ref": "#/components/schemas/Percentage" }, "duration": { "$ref": "#/components/schemas/Duration" } }, "required": [ "completion", "duration" ], "title": "Study Session Non-Graded Metrics", "description": "Completion and duration metrics", "example": { "completion": 90.456, "duration": "PT3M25S" } } }, "parameters": { "startDate": { "in": "query", "name": "startDate", "required": false, "style": "deepObject", "explode": true, "description": "Filter the results by session start date\n\nSupports either a ISO 8601 formatted date or a Unix timestamp. \nFor example `startDate[gt]=1688200245` or `startDate[lt]=2023-07-15T12:00:00.000Z`\n\nThe following operators cannot be used together\n- `gt` and `gte`\n- `lt` and `lte`", "schema": { "$ref": "#/components/schemas/DateQueryOperators" } }, "endDate": { "in": "query", "name": "endDate", "required": false, "style": "deepObject", "explode": true, "description": "Filter the results by session end date\n\nSupports either a ISO 8601 formatted date or a Unix timestamp. \nFor example `endDate[gt]=1688200245` or `endDate[lt]=2023-07-15T12:00:00.000Z`\n\nThe following operators cannot be used together\n- `gt` and `gte`\n- `lt` and `lte`", "schema": { "$ref": "#/components/schemas/DateQueryOperators" } }, "userId": { "in": "query", "name": "userId", "required": false, "style": "form", "explode": true, "description": "Filter the results by user ID.\n\nMultiple identifiers can be specified by repeating the query parameter. e.g. `userId=value1&userId=value2`\n\nThis parameter supports a maximum of 30 identifiers.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserId" }, "minItems": 1, "maxItems": 30 } }, "testId": { "in": "query", "name": "testId", "required": false, "style": "form", "explode": true, "description": "Filter the results by test ID.\n\nMultiple identifiers can be specified by repeating the query parameter. e.g. `testId=value1&testId=value2`\n\nThis parameter supports a maximum of 30 identifiers.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SmartIaTestId" }, "minItems": 1, "maxItems": 30 } }, "subject": { "in": "query", "name": "subject", "required": false, "style": "form", "explode": true, "description": "Filter the results by test subject.\n\nMultiple identifiers can be specified by repeating the query parameter. e.g. `subject=value1&subject=value2`\n\nThis parameter supports a maximum of 30 identifiers.", "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 30 } }, "limit": { "in": "query", "name": "limit", "description": "Specify the pagination limit, defaults to 100", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginationLimit" } ], "title": "Pagination Limit", "format": "int32", "description": "The maximum number of results to return per page.", "example": 30 } }, "offset": { "in": "query", "name": "offset", "description": "Specify the pagination offset, defaults to 0.\n\nCannot be used with `cursor`", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginationOffset" } ], "title": "Pagination Offset", "format": "int32", "description": "Indicates the starting position or index (offset)", "example": 100 } }, "cursor": { "in": "query", "name": "cursor", "required": false, "description": "Provide the next or previous page cursor", "schema": { "$ref": "#/components/schemas/PaginationCursor" } } } } }