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 Required

All endpoints except /authentication/authenticate require the header Authorization: Bearer <token>. Obtain a token by calling the Authenticate endpoint first. Tokens expire and must be refreshed.

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": "example@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": "example@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

Callback-Based — No Polling Required

DrillBit processes submissions asynchronously (typically 10–15 minutes). Once analysis is complete, DrillBit sends a PUT request to your registered callback endpoint with full results. Contact support@drillbit.in to register your callback URL.

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.