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 Required for All Endpoints

Every API request (except the authenticate call itself) must include a valid JWT Bearer token in the Authorization header. Obtain your token by calling POST /authentication/authenticate first. Pass it as Authorization: Bearer <token> in all subsequent requests.

🔐
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

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.com 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
ai_score integer AI-generated content likelihood score
ai_download_url string URL to download the AI detection report 
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,
  "ai_score":       12,
  "ai_download_url":"https://s1.drillbitplagiarismcheck.com/ai-reports/200101"
}
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. P ipe 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.