Classroom Management — DrillBit API Docs

Classroom Management · REST API

Folder Management
in Classroom

Complete reference for managing folders, submitting papers, and retrieving plagiarism & AI reports within the DrillBit Classroom environment. All endpoints require JWT authentication.

Base URL https://s1.drillbitplagiarismcheck.com

🔑

Authentication

POST /authentication/authenticate Authenticate User

Authenticates a user with email and password credentials. Returns a JWT token required for all subsequent API calls, along with user role, profile details, and feature flags.

Request Body — application/json

Field	Type	Required	Description
username	string	required	Registered email address of the user
password	string	required	Account password

POST /authentication/authenticate
Content-Type: application/json

{
  "username": "admin@example.com",
  "password": "123456"
}

200 OK

Response Fields

Field	Type	Description
token	string	JWT Bearer token — include in all subsequent request headers
role	string	User role (e.g. `admin`, `teacher`)
username	string	Authenticated user's email
name	string	Display name of the authenticated user
in_flag	boolean	Institution flag for this account
ai_flag	boolean	AI detection feature enabled for account
mfa	boolean	Multi-factor authentication status
id	integer	Unique user identifier
con_type	string\|null	Connection type (null if standard login)

{
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbnRlc3Rpbmdl...",
  "role": "admin",
  "username": "admin@example.com",
  "name": "Testing Admin",
  "in_flag": false,
  "ai_flag": false,
  "mfa": false,
  "id": 22201,
  "con_type": null
}

💡 Copy the token value and pass it as Authorization: Bearer <token> in all subsequent requests.

📁

Folder Management

GET /extreme/myFolders List Folders

Returns a paginated list of all folders (assignments) belonging to the authenticated user. Each folder object includes plagiarism check settings, database options, submission count, and excluded-phrase configuration.

Headers

Authorization: Bearer <token>

Query Parameters

Parameter	Type	Default	Description
page	integer	0	Page index (0-based)
size	integer	24	Results per page
field	string	ass_id	Field to sort by
orderBy	string	desc	`asc` or `desc`

GET /extreme/myFolders?page=0&size=24&field=ass_id&orderBy=desc
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

Top-level Fields

Field	Type	Description
grammar_subscription	string	Grammar check subscription status (`YES`/`NO`)
folders	object	Paginated folder data with links, content array and page metadata

folders.content[ ] — Folder Object

Field	Type	Description
folder_id	integer	Unique folder identifier
folder_name	string	Display name of the folder
creation_date	string	Folder creation timestamp (YYYY-MM-DD HH:mm:ss)
end_date	string	Folder expiry date
excludeReferences	string	Exclude references section from check
excludeQuotes	string	Exclude quoted text from check
excludeSmallSources	string	Exclude small matching sources
excludeIncludeSources	string	Include/exclude selected sources
grammarCheck	string	Grammar check enabled for this folder
excludePhrases	string	Exclude specific phrases from matching
phrases	object	Up to 15 excluded phrases (p1–p15), null if unused
db_studentpaper	string	Check against student paper database
db_publications	string	Check against publications database
db_internet	string	Check against internet sources
institution_repository	string	Check against institution repository
repository_scope	string	Scope of repository check (e.g. `LOCAL`)
no_of_submissions	integer	Number of papers submitted in this folder
exclude_threshold	integer	Minimum word count to exclude a source

folders.page — Pagination

Field	Type	Description
size	integer	Results per page
totalElements	integer	Total number of folders
totalPages	integer	Total number of pages
number	integer	Current page index (0-based)

{
  "grammar_subscription": "YES",
  "folders": {
    "links": [{ "rel": "self", "href": "https://s1.drillbitplagiarismcheck.com:8082/extreme/myFolders?..." }],
    "content": [
      {
        "folder_id": 286208,
        "folder_name": "Moodle",
        "creation_date": "2023-06-08 13:00:39",
        "end_date": "2024-07-31 00:00:00",
        "excludeReferences": "NO",
        "excludeQuotes": "YES",
        "excludeSmallSources": "YES",
        "grammarCheck": "NO",
        "db_studentpaper": "YES",
        "db_publications": "YES",
        "db_internet": "YES",
        "institution_repository": "YES",
        "repository_scope": "LOCAL",
        "no_of_submissions": 28,
        "exclude_threshold": 15
      }
    ],
    "page": {
      "size": 24,
      "totalElements": 18,
      "totalPages": 1,
      "number": 0
    }
  }
}

POST /extreme/folder Create Folder

Creates a new folder (assignment) under the authenticated user's classroom. Returns the new folder ID and a link to the created resource.

Headers

Authorization: Bearer <token>
Content-Type: application/json

POST /extreme/folder
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

Field	Type	Description
status	integer	HTTP status code
message	string	Success confirmation message
timeStamp	string	Server timestamp of the operation
_links.self.href	string	URL of the newly created folder resource

{
  "status": 200,
  "message": "Folder has been created successfully.",
  "timeStamp": "08-04-2026 11:24:10",
  "_links": {
    "self": {
      "href": "https://s1.drillbitplagiarismcheck.com:8082/extreme/classes/29022/assignments/620232"
    }
  }
}

💡 Save the folder_id (e.g. 620232) from the _links.self.href — you will need it for update, delete, and submission operations.

PUT /extreme/folder/{folder_id} Update Folder

Updates an existing folder's name and plagiarism check settings, including database sources, exclusion options, and similarity threshold. All fields in the payload are applied on save.

Headers

Authorization: Bearer <token>
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
folder_id	integer	required	The ID of the folder to update

Request Body Fields

Field	Type	Description
assignment_name	string	New folder/assignment name
exclude_reference	string	Exclude references (`YES`/`NO`)
exclude_quotes	string	Exclude quoted text
exclude_small_sources	string	Exclude small sources
grammar_check	string	Enable grammar checking
exclude_phrases	string	Enable phrase exclusion
db_studentpaper	string	Check against student paper DB
db_publications	string	Check against publications DB
db_internet	string	Check against internet sources
institution_repository	string	Check against institution repository
exclude_threshold	integer	Minimum word threshold to exclude a source match

PUT /extreme/folder/620232
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

{
  "assignment_name": "API Docs",
  "exclude_reference": "NO",
  "exclude_quotes": "NO",
  "exclude_small_sources": "NO",
  "grammar_check": "NO",
  "exclude_phrases": "NO",
  "db_studentpaper": "YES",
  "db_publications": "YES",
  "db_internet": "YES",
  "institution_repository": "YES",
  "exclude_threshold": 14
}

200 OK

{
  "status": 200,
  "message": "Folder has been updated successfully. ",
  "timeStamp": "08-04-2026 12:04:17",
  "_links": {
    "self": {
      "href": "https://s1.drillbitplagiarismcheck.com:8082/extreme/classes/29022/assignments/620232"
    }
  }
}

DELETE /extreme/folder?id={folder_id} Delete Folder

Permanently deletes a folder and all associated submissions. This action is irreversible. Ensure you back up any required data before calling this endpoint.

Headers

Authorization: Bearer <token>

Query Parameters

Parameter	Type	Required	Description
id	integer	required	The folder ID to delete

DELETE /extreme/folder?id=620232
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

{
  "status": 200,
  "message": "Folders and all the associated submissions has been deleted successfully.",
  "timeStamp": "08-04-2026 12:08:43"
}

⚠️ This action is irreversible. All submissions inside the folder will be permanently removed. There is no undo.

📄

Submissions

GET /extreme/myFolder/{folder_id}/submissions List Submissions

Returns a paginated list of all paper submissions in a specific folder. Each submission includes the plagiarism percentage, document metadata, word/character/sentence counts, file size, AI detection score, and grammar check URL.

Headers

Authorization: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
folder_id	integer	required	The folder to list submissions from

Query Parameters

Parameter	Type	Default	Description
page	integer	0	Page index (0-based)
size	integer	24	Results per page
field	string	paper_id	Sort field
orderBy	string	desc	`asc` or `desc`

GET /extreme/myFolder/61625/submissions?page=0&size=24&field=paper_id&orderBy=desc
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

submissionsList[ ] — Submission Object

Field	Type	Description
paper_id	integer	Unique paper identifier
name	string	Author/submitter name
mail_id	string	Submitter's email address
title	string	Document title
date_up	string	Upload timestamp
percent	string	Similarity percentage (or `NA` if pending)
d_key	string	Report download key (used in report URLs)
to_char / to_words / to_sens / to_pages	string	Character, word, sentence, and page counts
file_length	string	File size with unit (e.g. `22 Kb`)
original_fn	string	Original uploaded filename
doc_type	string	Document type (e.g. Thesis, Article, Assignment)
lang / lang1	string	Primary and secondary language of the document
grammar_url	string	Grammar report URL (or `NA`)
ai	string	AI-generated content percentage
og_percent	string	Original similarity score before exclusions
status	string	Submission status (`active` / `deleted`)

{
  "_embedded": {
    "submissionsList": [
      {
        "paper_id": 228306,
        "name": "sathish",
        "title": "test",
        "date_up": "2021-02-19 11:23:57",
        "percent": "NA",
        "d_key": "NA",
        "original_fn": "google.docx",
        "doc_type": "Assignment",
        "ai": "0",
        "status": "active"
      }
    ]
  },
  "page": {
    "size": 24,
    "totalElements": 2,
    "totalPages": 1,
    "number": 0
  }
}

POST /files/myFolder/{folder_id}/singleFile Submit Paper

Uploads a single paper file to a specified folder and queues it for plagiarism and/or grammar analysis. Submit as multipart/form-data. Returns full submission metadata including the new paper_id and report links.

Headers

Authorization: Bearer <token>
Content-Type: multipart/form-data

Path Parameters

Parameter	Type	Required	Description
folder_id	integer	required	The folder to submit the paper into

Form Fields (multipart/form-data)

Field	Type	Required	Description
authorName	string	required	Name of the paper author
title	string	required	Title of the document
documentType	string	required	Type: `Article`, `Thesis`, `Assignment`, etc.
plagiarismCheck	string	required	`YES` or `NO`
grammarCheck	string	required	`YES` or `NO`
language	string	required	Document language (e.g. `English`)
guide_email	string	optional	Guide's email address
guide_name	string	optional	Guide's name
file	binary	required	The document file to upload (PDF, DOCX, etc.)

POST /files/myFolder/61625/singleFile
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...
Content-Type: multipart/form-data

authorName:       api docs
title:            api docs
documentType:     Article
plagiarismCheck:  YES
grammarCheck:     NO
language:         English
guide_email:      (empty)
guide_name:       (empty)
file:             (binary)

200 OK

submissions — Submission Object

Field	Type	Description
paper_id	integer	Newly assigned unique paper ID
name	string	Author name as submitted
title	string	Document title
date_up	string	Upload timestamp
percent	string	Similarity score (`--` while processing)
to_pages	string	Total pages in document
d_key	string	Report key used to download reports
original_fn	string	Original uploaded filename
links	array	HATEOAS links — self URL and submissions list URL

{
  "submissions": {
    "paper_id": 5443188,
    "name": "api docs",
    "title": "api docs",
    "date_up": "2026-04-08 12:15:16",
    "percent": "--",
    "to_pages": "37",
    "file_length": "5983 Kb",
    "d_key": "AWBLRRKK0HCWGSODRBD0",
    "original_fn": "journal.pone.0323724.pdf",
    "doc_type": "Article",
    "ai": "--",
    "links": [
      { "rel": "self", "href": "https://s1.drillbitplagiarismcheck.com/extreme/myFolder/61625/submissions/5443188" },
      { "rel": "submissions", "href": "https://s1.drillbitplagiarismcheck.com/extreme/myFolder/61625/submissions" }
    ]
  },
  "status": 200,
  "message": "File uploaded successfully.",
  "timeStamp": "08-04-2026 12:15:16"
}

💡 The percent and d_key fields show -- immediately after upload while processing. Poll the Get Submission endpoint until a numeric percent value appears before downloading reports.

GET /pro/folder/{folder_id}/submission/{paper_id} Get Submission

Retrieves detailed metadata and analysis results for a single submission, including the final similarity percentage, AI detection score, word/character counts, and language information.

Headers

Authorization: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
folder_id	integer	required	Folder containing the submission
paper_id	integer	required	Unique paper identifier

GET /pro/folder/61625/submission/5443188
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

Field	Type	Description
paper_id	integer	Unique paper identifier
folder_id	integer	Containing folder ID
folder_name	string	Folder display name
percent	string	Final similarity percentage
total_char / total_words	string	Total character and word counts
total_pages	string	Total page count
ai	string	AI-generated content percentage
og_percent	string	Similarity score before exclusions applied
d_key	string	Report download key for report endpoints
document_type	string	Document classification type
language / language1	string	Primary and secondary languages
original_file_name	string	Original uploaded filename
exclude_references / exclude_quotes / small_sources	string	Applied exclusion flags for this submission

{
  "paper_id": 5443188,
  "folder_id": 61625,
  "folder_name": "Testing",
  "title": "api docs",
  "percent": "98",
  "total_char": "117668",
  "total_words": "17149",
  "total_pages": "37",
  "d_key": "AWBLRRKK0HCWGSODRBD0",
  "document_type": "Article",
  "language": "English",
  "original_file_name": "journal.pone.0323724 (1).pdf",
  "ai": "3",
  "og_percent": "98",
  "ai_sup": 1
}

DELETE /extreme/myFolder/{folder_id}/submissions?paperId={paper_id} Delete Paper

Permanently deletes a specific paper submission from a folder, including all associated reports. This action cannot be undone.

Headers

Authorization: Bearer <token>

Path & Query Parameters

Parameter	Type	Required	Description
folder_id	integer	required	The folder containing the paper (path param)
paperId	integer	required	The paper to delete (query param)

DELETE /extreme/myFolder/61625/submissions?paperId=5443188
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

{
  "status": 200,
  "message": "File(s) deleted successfully.",
  "timeStamp": "08-04-2026 12:50:54"
}

🔔

Webhooks

PUT {your_callback_endpoint} Analysis complete callback

When plagiarism analysis is complete, DrillBit sends a PUT request to your registered callback URL. Your endpoint must accept this payload and return 200 OK.

Workflow

① Upload file

② DrillBit processes
(10–15 min)

③ PUT callback sent
to your endpoint

Callback Payload Fields

Field	Type	Description
paper_id	integer	Unique identifier for the processed document
similarity	string	Similarity percentage (e.g. `"23%"`)
download_url	string	URL to download the similarity report
flag	integer	Error flag — `1` = error, `0` = no error

PUT https://partner-api.example.com/drillbit/callback
Content-Type: application/json

{
  "paper_id":       200101,
  "similarity":     "18%",
  "download_url":   "https://s1.drillbitplagiarismcheck.com/reports/200101",
  "flag":           0
}

Expected Response from Your Endpoint

Status Code	Meaning
200 OK	Payload received — DrillBit considers delivery complete
4XX / 5XX	Error — DrillBit will treat the callback as failed

💡 Your endpoint must respond with 200 OK within a reasonable timeout. No specific response body is required.

📊

Reports

GET /analysis-gateway/api/download2/{paper_id}/{d_key} Similarity Report

Downloads the full similarity/plagiarism report PDF for a submitted paper. The d_key is the report download key returned in the submission response.

Headers

Authorization: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
paper_id	integer	required	Unique paper identifier
d_key	string	required	Report download key from submission response

GET /analysis-gateway/api/download2/5443527/6AJGFYOG4AIK7W6OOKRE
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

PDF binary stream — similarity/plagiarism report

GET /analysis-gateway/api/ai/download2/{paper_id}/{d_key} AI Detection Report

Downloads the AI-generated content detection report PDF for a submitted paper. Identifies sections likely written by AI language models and provides an overall AI percentage score.

Headers

Authorization: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
paper_id	integer	required	Unique paper identifier
d_key	string	required	Report download key from submission response

GET /analysis-gateway/api/ai/download2/5443527/6AJGFYOG4AIK7W6OOKRE
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

PDF binary stream — AI detection report

💡 AI detection is available only when ai_sup is 1 in the submission response. Confirm the ai field is a numeric value (not --) before downloading.

GET /analysis-gateway/api/download/summary/{paper_id}/{d_key} Summary Report

Downloads the one-page summary report PDF for a submitted paper. Provides a concise overview of the similarity analysis, source breakdown, and key metrics.

Headers

Authorization: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
paper_id	integer	required	Unique paper identifier
d_key	string	required	Report download key from submission response

GET /analysis-gateway/api/download/summary/5443527/6AJGFYOG4AIK7W6OOKRE
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

PDF binary stream — summary report

GET /analysis-gateway/api/quality/download/{paper_id} Grammar Quality Report

Downloads the grammar quality report PDF for a submitted paper. Returns a detailed analysis of grammatical errors, style issues, and writing quality metrics. Only available when grammar check was enabled for the submission.

Headers

Authorization: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
paper_id	integer	required	Unique paper identifier returned on submission

GET /analysis-gateway/api/quality/download/5443527
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK — Report Available

PDF binary stream — grammar quality report

400 Bad Request — Report Not Available

{
  "status": 400,
  "description": "BAD_REQUEST",
  "timestamp": "08-04-2026 01:07:09",
  "message": "The quality report is either not yet ready or not available.",
  "debugMessage": "The quality report is either not yet ready or not available.",
  "subErrors": null,
  "path": "/analysis-gateway/api/quality/download/5443527"
}

💡 Only the paper_id is required — no d_key needed for grammar reports. A 400 response means grammar check was not enabled for that submission or the report is still processing.

⚠️

Error Codes

Status Code	Error	Description	Common Cause
`200 OK`	Success	Request completed successfully.	—
`400 Bad Request`	Bad Request	The request was malformed or missing required fields.	Missing payload fields, grammar report not ready
`401 Unauthorized`	Unauthorized	Authentication token is missing, expired, or invalid.	Missing or expired JWT token
`403 Forbidden`	Forbidden	The user does not have permission to access this resource.	Accessing another user's folder or paper
`404 Not Found`	Not Found	The requested resource does not exist.	Invalid folder_id, paper_id, or d_key
`409 Conflict`	Conflict	The request conflicts with the current state of the server.	Duplicate submission or folder name
`413 Payload Too Large`	Payload Too Large	The uploaded file exceeds the maximum allowed size.	File too large for single upload
`422 Unprocessable`	Unprocessable Entity	Request was well-formed but contains semantic errors.	Invalid field values or unsupported file type
`429 Too Many Requests`	Rate Limited	Too many requests sent in a short period.	Exceeded API rate limit
`500 Server Error`	Internal Server Error	An unexpected error occurred on the DrillBit server.	Contact support if this persists
`503 Unavailable`	Service Unavailable	The server is temporarily unable to handle requests.	Maintenance or high server load

💡 All error responses include a JSON body with a message or description field. For persistent 5XX errors, contact support@drillbit.in.

That's all for Classroom Management

Explore other DrillBit API products — Folder Management and LMS Integration.

Back to all products

Folder Management
in Classroom

🔐 Authentication Required

Callback-Based — No Polling Required

That's all for Classroom Management

Folder Managementin Classroom

🔐 Authentication Required

Callback-Based — No Polling Required

That's all for Classroom Management

Folder Management
in Classroom