Folder Management — DrillBit API Docs

REST API Reference

Drillbit Folder Management
API Documentation

Complete reference for integrating plagiarism detection, AI content analysis, and report generation into your application or platform.

Base URL https://s1.drillbitplagiarismcheck.com

🔐

Authentication

POST /authentication/authenticate Authenticate user ▶

Authenticates a user with their credentials and returns a JWT Bearer token. This is the only endpoint that does not require an existing token.

Request Body · application/json

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

{
  "username": "john.doe@university.edu",
  "password": "••••••••••••"
}

200 OK

Response Fields

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

{
  "token":    "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJqb2huLmRvZUB1...",
  "role":     "lim-admin",
  "username": "john.doe@university.edu",
  "name":     "John Doe",
  "in_flag":  false,
  "ai_flag":  false,
  "mfa":      false,
  "id":       100123,
  "con_type": null
}

💡 Store the token securely and pass it as Authorization: Bearer <token> in every subsequent request header.

📁

Folders

GET /pro/folders List folders ▶

Returns a paginated list of assignment folders sorted by the specified field.

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 /pro/folders?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
translation	string	Translation feature status
in_flag	boolean	Institution flag for this account

folders.content[ ] — Folder Object

Field	Type	Description
folder_id	integer	Unique folder identifier
folder_name	string	Display name of the folder
mail_id	string	Owner's email address
created_date	string	Folder creation timestamp
end_date	string	Folder expiry date
small_sources	string	Exclude small sources
ex_references	string	Exclude references section
ex_quotes	string	Exclude quoted text
grammar	string	Grammar check enabled
ex_phrases	string	Exclude specific phrases
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
no_of_submissions	integer	Number of papers submitted in this folder
phrases	object	Up to 15 excluded phrases (p1–p15), null if unused
email_notifications	string	Email alerts on submission completion
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",
  "translation": "no",
  "in_flag": false,
  "folders": {
    "content": [
      {
        "folder_id": 100201,
        "folder_name": "Research Papers Q1",
        "mail_id": "john.doe@university.edu",
        "created_date": "2026-01-10 09:00:00",
        "end_date": "2026-12-31 00:00:00",
        "small_sources": "NO",
        "ex_references": "NO",
        "ex_quotes": "NO",
        "grammar": "NO",
        "ex_phrases": "NO",
        "db_studentpaper": "YES",
        "db_publications": "YES",
        "db_internet": "YES",
        "institution_repository": "YES",
        "no_of_submissions": 5,
        "phrases": { "pId": 100001, "p1": null /* p2–p15 null */ },
        "email_notifications": "NO",
        "exclude_threshold": 14
      }
    ],
    "page": {
      "size": 24,
      "totalElements": 5,
      "totalPages": 1,
      "number": 0
    }
  }
}

💡 Use totalPages to paginate. Increment page from 0 up to totalPages - 1.

POST /pro/folder Create folder ▶

Creates a new assignment folder with plagiarism check configuration. All boolean fields accept "YES" or "NO".

Headers

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

Request Body · application/json

Field	Type	Description
folder_name	string	Display name for the folder
exclude_reference	string	Exclude references section from check
exclude_quotes	string	Exclude quoted text from similarity
exclude_small_sources	string	Ignore small matching sources
grammar_check	string	Enable grammar analysis
exclude_phrases	string	Exclude specific phrases from matching
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
email_notifications	string	Send email on completion
exclude_threshold	integer	Minimum word count to exclude a source

{
  "folder_name":           "Research Papers Q2",
  "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",
  "email_notifications":   "NO",
  "exclude_threshold":     14
}

201 Created

Response Fields

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

{
  "status":    201,
  "message":   "Folder has been created successfully.",
  "timeStamp": "08-04-2026 08:16:08",
  "_links": {
    "self": {
      "href": "https://s1.drillbitplagiarismcheck.com/pro/folder/100201"
    }
  }
}

PUT /pro/folder/{folder_id} Update folder ▶

Updates the name and configuration settings of an existing assignment folder.

Headers

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

Path Parameters

Parameter	Type	Required	Description
folder_id	integer	required	Unique identifier of the folder to update

Request Body · application/json

{
  "folder_name":           "Updated Folder Name",
  "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",
  "email_notifications":   "NO",
  "exclude_threshold":     14
}

201 Created

Response Fields

Field	Type	Description
status	integer	HTTP status code
message	string	Human-readable result message
timeStamp	string	Server timestamp of the operation

{
  "status":    201,
  "message":   "Folder has been updated successfully.",
  "timeStamp": "08-04-2026 08:20:32"
}

DELETE /pro/folder/{folder_id} Delete folder ▶

Permanently deletes an assignment folder and all its contents. This action is irreversible — all submissions and reports within the folder will be removed.

Headers

Authorization: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
folder_id	integer	required	Unique identifier of the folder to delete

DELETE /pro/folder/100201
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

Response Fields

Field	Type	Description
status	integer	HTTP status code
message	string	Human-readable result message
timeStamp	string	Server timestamp of the operation

{
  "status":    200,
  "message":   "Folder deleted successfully.",
  "timeStamp": "08-04-2026 08:18:07"
}

📄

Submissions

GET /pro/folder/{folder_id}/submissions List submissions ▶

Returns a paginated list of paper submissions within a specific folder.

Headers

Authorization: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
folder_id	integer	required	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	Field to sort by
orderBy	string	desc	`asc` or `desc`

GET /pro/folder/100201/submissions?page=0&size=24&field=paper_id&orderBy=desc
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

Submission Object Fields

Field	Type	Description
paper_id	integer	Unique paper identifier
folder_id	integer	Parent folder identifier
folder_name	string	Parent folder display name
name	string	Submitter's name
mail_id	string	Submitter's email
title	string	Document title
date_up	string	Upload timestamp
percent	string	Similarity percentage
total_char	string	Total characters in document
total_words	string	Total word count
total_pages	string	Total page count
file_length	string	File size (e.g. "17 Kb")
d_key	string	Report download key / token
status	string	Submission status (`active`)
original_file_name	string	Original uploaded filename
language	string	Detected document language
document_type	string	Document category (e.g. Assignment, Article)
grammar	string	Grammar score (0–100) or "--" if not checked
ai	string	AI content percentage or "--" if not checked
og_percent	string	Original similarity percentage before exclusions
ai_sup	integer	AI detection supported flag (1 = yes)
flag	integer	Error flag (0 = no error, 1 = error)

{
  "_embedded": {
    "submissionsDTOList": [
      {
        "paper_id":           200101,
        "folder_id":          100201,
        "folder_name":        "Research Papers Q1",
        "name":               "Jane Smith",
        "mail_id":            "jane.smith@university.edu",
        "title":              "Machine Learning Overview",
        "date_up":            "2026-03-10 11:20:00",
        "percent":            "18",
        "total_char":         "5420",
        "total_words":        "890",
        "total_pages":        "3",
        "file_length":        "14 Kb",
        "d_key":              "ABCDE12345FGHIJ67890",
        "status":             "active",
        "original_file_name": "ml_overview.docx",
        "language":           "English",
        "document_type":      "Assignment",
        "grammar":            "85",
        "ai":                 "12",
        "og_percent":         "18",
        "ai_sup":             1,
        "flag":               0
      }
    ]
  },
  "page": {
    "size":          24,
    "totalElements": 3,
    "totalPages":    1,
    "number":        0
  }
}

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

Returns the full details of a single paper submission including analysis results.

Headers

Authorization: Bearer <token>

Path Parameters

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

GET /pro/folder/100201/submission/200101
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

Response Fields

Field	Type	Description
paper_id	integer	Unique paper identifier
folder_id	integer	Parent folder identifier
title	string	Document title
percent	string	Similarity percentage
ai	string	AI content percentage
grammar	string	Grammar score (0–100)
d_key	string	Report download key / token
document_type	string	Document category
language	string	Detected document language
status	string	Submission status
flag	integer	Error flag (0 = no error)

{
  "paper_id":           200101,
  "folder_id":          100201,
  "folder_name":        "Research Papers Q1",
  "name":               "Jane Smith",
  "mail_id":            "jane.smith@university.edu",
  "title":              "Machine Learning Overview",
  "date_up":            "2026-03-10 11:20:00",
  "percent":            "18",
  "total_char":         "5420",
  "total_words":        "890",
  "total_pages":        "3",
  "file_length":        "14 Kb",
  "d_key":              "ABCDE12345FGHIJ67890",
  "status":             "active",
  "original_file_name": "ml_overview.docx",
  "language":           "English",
  "document_type":      "Assignment",
  "grammar":            "85",
  "ai":                 "12",
  "og_percent":         "18",
  "ai_sup":             1,
  "flag":               0
}

POST /pro/folder/{folder_id}/submission Submit paper ▶

Uploads a paper file to a folder for plagiarism analysis. Use multipart/form-data. Analysis runs asynchronously — results are delivered via webhook callback.

Headers

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

Path Parameters

Parameter	Type	Required	Description
folder_id	integer	required	Target folder for the submission

Form Fields

Field	Type	Required	Description
file	file	required	Document file (PDF, DOCX, etc.)
name	string	required	Submitter's name
title	string	required	Document title

POST /pro/folder/100201/submission
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...
Content-Type:  multipart/form-data

file=@research_paper.pdf&name=Jane+Smith&title=ML+Overview

200 OK

Response Fields

Field	Type	Description
status	integer	HTTP status code
message	string	Upload result message
timeStamp	string	Server timestamp of the upload
submissions.paper_id	integer	Newly assigned paper identifier
submissions.d_key	string	Report download key (available after analysis)
submissions.percent	string	"--" while analysis is pending
submissions.to_pages	string	Total pages in uploaded document
submissions.links	array	HATEOAS links to self and parent submissions list

{
  "status":    200,
  "message":   "File uploaded successfully.",
  "timeStamp": "08-04-2026 08:39:10",
  "submissions": {
    "paper_id":   200102,
    "name":       "Jane Smith",
    "title":      "ML Overview",
    "date_up":    "2026-04-08 08:39:10",
    "percent":    "--",
    "to_pages":   "12",
    "file_length":"980 Kb",
    "d_key":      "ZFULUO1RBBXZCMDQNI7Y",
    "status":     "active",
    "ai":         "--",
    "grammar":    "--",
    "links": [
      { "rel": "self",        "href": "…/pro/folder/100201/submission/200102" },
      { "rel": "submissions", "href": "…/pro/folder/100201/submissions" }
    ]
  }
}

💡 Analysis runs asynchronously. Fields like percent, ai and grammar show "--" until complete. Results are pushed to your registered webhook callback.

DELETE /pro/folder/{folder_id}/submissions?paperId={paper_id} Delete paper ▶

Permanently removes a submitted paper from a folder. This action is irreversible.

Headers

Authorization: Bearer <token>

Path & Query Parameters

Parameter	Type	Required	Description
folder_id	integer	required	Folder containing the paper
paperId	integer	required	ID of the paper to permanently delete

DELETE /pro/folder/100201/submissions?paperId=200101
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

Response Fields

Field	Type	Description
status	integer	HTTP status code
message	string	Human-readable result message
timeStamp	string	Server timestamp of the operation

{
  "status":    200,
  "message":   "Submission(s) deleted successfully.",
  "timeStamp": "08-04-2026 08:42:59"
}

🔔

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}/{report_token} Similarity report ▶

Downloads the full plagiarism similarity report for a submitted paper. Returns a PDF file as a binary stream.

Headers

Authorization: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
paper_id	integer	required	Unique paper identifier
report_token	string	required	Secure token (`d_key`) returned with the submission

GET /analysis-gateway/api/download2/200101/ABCDE12345FGHIJ67890
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

PDF binary stream — similarity report

💡 The response is a raw PDF file. Set Content-Disposition: attachment on your client to trigger a download, or pipe the stream directly to a file.

GET /analysis-gateway/api/ai/download2/{paper_id}/{report_token} AI report ▶

Downloads the AI-generated content detection report PDF. Identifies sections potentially written by AI tools.

Headers

Authorization: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
paper_id	integer	required	Unique paper identifier
report_token	string	required	Secure token (`d_key`) returned with the submission

GET /analysis-gateway/api/ai/download2/200101/ABCDE12345FGHIJ67890
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

PDF binary stream — AI detection report

💡 The response is a raw PDF file. Pipe the binary stream to a file or trigger a browser download using Content-Disposition: attachment.

GET /analysis-gateway/api/download/summary/{paper_id}/{report_token} Summary report ▶

Downloads a concise summary report PDF with key plagiarism metrics and match percentages.

Headers

Authorization: Bearer <token>

Path Parameters

Parameter	Type	Required	Description
paper_id	integer	required	Unique paper identifier
report_token	string	required	Secure token (`d_key`) returned with the submission

GET /analysis-gateway/api/download/summary/200101/ABCDE12345FGHIJ67890
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

PDF binary stream — summary report

💡 The response is a raw PDF file. Pipe the binary stream to a file or trigger a browser download.

GET /analysis-gateway/api/quality/download/{paper_id} Grammar report ▶

Downloads the grammar quality report PDF for a submitted paper. Returns a detailed analysis of grammatical errors, style issues, and writing quality metrics.

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/200101
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

200 OK

PDF binary stream — grammar quality report

💡 Only the paper_id is required — no report_token needed for grammar reports.

⚠️

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, wrong content type
`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 report_token
`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 an error or message field. For persistent 5XX errors, contact support@drillbit.com.

That's all for Folder Management

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

Back to all products

Drillbit Folder Management
API Documentation

Authentication Required for All Endpoints

Callback-Based — No Polling Required

That's all for Folder Management

Drillbit Folder ManagementAPI Documentation

Authentication Required for All Endpoints

Callback-Based — No Polling Required

That's all for Folder Management

Drillbit Folder Management
API Documentation