DocSpry Match API · Preview
Match API reference.
Preview.
Preview
Not open to customers yet. DocSpry has no API keys, and these routes accept only a signed-in DocSpry session: they are the routes the DocSpry Match app calls. Endpoints and fields may change before API access opens.
Create a check, upload a class’s Word files, run it and read the report: flagged pairs per question, with scores, the longest shared run and a word-level difference.
Authentication and base URL
Every request carries a DocSpry bearer token. Today the only token these routes accept is a signed-in DocSpry session’s, which the Match app sends for you: there are no API keys, and a connected assistant’s token is refused.
Authorization: Bearer <token>
Base URL: https://api.docspry.comA check belongs to the account that created it. Every route answers 401 without a valid token and 404 for a check that is not yours, so ids cannot be probed. Requests and responses are JSON in camelCase, except file uploads (multipart/form-data). Errors other than 401 are {"error": "<code>", "message": "<sentence>"}.
Examples use the fictional sample class. Ids, times and sizes are placeholders.
Quick start
Create, upload, run, then read the report: five calls. There is no webhook: poll the check until it has finished. The examples read a bearer token from DOCSPRY_TOKEN; until API keys exist, there is no supported way to get one outside the Match app.
curl
API=https://api.docspry.com
AUTH="Authorization: Bearer $DOCSPRY_TOKEN"
# 1. Create a check (default settings)
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
-d '{"name":"Science unit test"}' $API/match/checks
# 201 {"checkId":"…","status":"draft", …}
CHECK=<checkId from the answer>
# 2. Upload the answer files: many per request, in a field named "files"
curl -H "$AUTH" -F files=@student-01.docx -F files=@student-02.docx \
$API/match/checks/$CHECK/files
# 3. Run the check
curl -X POST -H "$AUTH" $API/match/checks/$CHECK/run
# 202 {"jobId":"…","filesToCharge":6,"aiFilesToCharge":0,"estimatedTokens":300}
# 4. Wait: poll until check.status is "completed" or "failed"
curl -H "$AUTH" $API/match/checks/$CHECK
# 5. Read the report
curl -H "$AUTH" $API/match/checks/$CHECK/reportPython
import glob, os, time
import requests
API = "https://api.docspry.com"
HEADERS = {"Authorization": "Bearer " + os.environ["DOCSPRY_TOKEN"]}
# 1. Create a check with the default settings
check = requests.post(f"{API}/match/checks", headers=HEADERS,
json={"name": "Science unit test"}).json()
check_id = check["checkId"]
# 2. Upload the class's answer files in one request
paths = sorted(glob.glob("answers/*.docx"))
files = [("files", (os.path.basename(p), open(p, "rb"))) for p in paths]
upload = requests.post(f"{API}/match/checks/{check_id}/files", headers=HEADERS, files=files).json()
for rejected in upload["rejected"]:
print("Not added:", rejected["name"], "-", rejected["reason"])
# 3. Run it (402 means not enough tokens)
run = requests.post(f"{API}/match/checks/{check_id}/run", headers=HEADERS)
run.raise_for_status()
# 4. Wait for the run to finish
while True:
detail = requests.get(f"{API}/match/checks/{check_id}", headers=HEADERS).json()
if detail["check"]["status"] in ("completed", "failed"):
break
time.sleep(5)
# 5. Read the report: flagged pairs, question by question
report = requests.get(f"{API}/match/checks/{check_id}/report", headers=HEADERS).json()
names = {f["fileId"]: f["name"] for f in report["files"]}
for question in report["questions"]:
for pair in question["pairs"]:
print(question["questionNumber"], names[pair["fileA"]], names[pair["fileB"]],
pair["score"], pair["reason"], pair["longestRunWords"])C# (HttpClient)
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
var http = new HttpClient { BaseAddress = new Uri("https://api.docspry.com") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
"Bearer", Environment.GetEnvironmentVariable("DOCSPRY_TOKEN"));
// 1. Create a check with the default settings
using var created = await http.PostAsJsonAsync("/match/checks", new { name = "Science unit test" });
created.EnsureSuccessStatusCode();
var checkId = (await created.Content.ReadFromJsonAsync<JsonElement>()).GetProperty("checkId").GetString();
// 2. Upload the class's answer files in one request
using var form = new MultipartFormDataContent();
foreach (var path in Directory.GetFiles("answers", "*.docx"))
form.Add(new ByteArrayContent(await File.ReadAllBytesAsync(path)), "files", Path.GetFileName(path));
(await http.PostAsync($"/match/checks/{checkId}/files", form)).EnsureSuccessStatusCode();
// 3. Run it (402 means not enough tokens)
(await http.PostAsync($"/match/checks/{checkId}/run", null)).EnsureSuccessStatusCode();
// 4. Wait for the run to finish
string? status;
do
{
await Task.Delay(TimeSpan.FromSeconds(5));
var detail = await http.GetFromJsonAsync<JsonElement>($"/match/checks/{checkId}");
status = detail.GetProperty("check").GetProperty("status").GetString();
} while (status is "queued" or "running");
// 5. Read the report: flagged pairs, question by question
var report = await http.GetFromJsonAsync<JsonElement>($"/match/checks/{checkId}/report");
foreach (var question in report.GetProperty("questions").EnumerateArray())
foreach (var pair in question.GetProperty("pairs").EnumerateArray())
Console.WriteLine($"Q{question.GetProperty("questionNumber")}: {pair.GetProperty("score")}% {pair.GetProperty("reason")}");JavaScript (fetch)
// Node 18 or later. Keep the token on your server, never in a web page.
import { readdir, readFile } from 'node:fs/promises';
const API = 'https://api.docspry.com';
const headers = { Authorization: `Bearer ${process.env.DOCSPRY_TOKEN}` };
const json = async response => {
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
return response.json();
};
// 1. Create a check with the default settings
const { checkId } = await json(await fetch(`${API}/match/checks`, {
method: 'POST', headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ name: 'Science unit test' })
}));
// 2. Upload the class's answer files in one request
const form = new FormData();
for (const name of (await readdir('answers')).filter(n => n.endsWith('.docx')))
form.append('files', new Blob([await readFile(`answers/${name}`)]), name);
await json(await fetch(`${API}/match/checks/${checkId}/files`, { method: 'POST', headers, body: form }));
// 3. Run it (402 means not enough tokens)
await json(await fetch(`${API}/match/checks/${checkId}/run`, { method: 'POST', headers }));
// 4. Wait for the run to finish
let status;
do {
await new Promise(resolve => setTimeout(resolve, 5000));
({ check: { status } } = await json(await fetch(`${API}/match/checks/${checkId}`, { headers })));
} while (status === 'queued' || status === 'running');
// 5. Read the report: flagged pairs, question by question
const report = await json(await fetch(`${API}/match/checks/${checkId}/report`, { headers }));
for (const question of report.questions)
for (const pair of question.pairs)
console.log(question.questionNumber, pair.fileA, pair.fileB, pair.score, pair.reason);A real response, trimmed
Question 3 of the sample, as the report’s questions list carries it. In the sample, file ids are the file names; the API uses generated ids and lists the names in the report’s files.
{
"questionKey": "3",
"questionNumber": "3",
"questionText": "Describe an experiment that shows a leaf needs light to make starch.",
"answeredCount": 6,
"groups": [
{
"groupId": 1,
"fileIds": [
"student-01.docx",
"student-03.docx"
]
}
],
"pairs": [
{
"pairId": "54505353f4bf2f12",
"fileA": "student-01.docx",
"fileB": "student-03.docx",
"score": 92,
"reason": "wholeAnswer",
"coverageA": 100,
"coverageB": 93,
"longestRunWords": 25,
"diff": [
{
"op": "equal",
"text": "Keep a potted plant in the dark for two days to remove its starch. Cover part of one leaf with black paper and leave the plant in sunlight for a day. Test the leaf with iodine: only the uncovered part turns blue-black, so starch was made only where light reached the leaf."
},
{
"op": "insert",
"text": " This proves light is needed."
}
]
}
],
"omittedPairs": 0
}Checks
POST /match/checks
Creates a check: one class, one paper. Settings are optional; the defaults are DocSpry Match’s rules.
| Parameter | In | Description |
|---|---|---|
name | body | 1 to 120 characters. |
settings | body | Optional. See the settings below. |
Request
curl -H "Authorization: Bearer $DOCSPRY_TOKEN" -H "Content-Type: application/json" \
-d '{"name":"Science unit test"}' \
https://api.docspry.com/match/checksResponse: 201 Created
{
"checkId": "<checkId>",
"name": "Science unit test",
"status": "draft",
"createdAt": "<UTC time>",
"updatedAt": "<UTC time>",
"completedAt": null,
"jobId": null,
"progressPercent": null,
"fileCount": 0,
"readFileCount": 0,
"questionCount": 0,
"flaggedPairCount": 0,
"lastError": null,
"settings": {
"template": "auto",
"wholeAnswerPercent": 70,
"sharedRunWords": 5,
"paragraphPercent": 95,
"paragraphMinWords": 10,
"minAnswerWords": 5,
"ignoreQuestionText": true,
"commonTextShare": 0.5,
"commonTextMinAnswers": 6,
"aiReport": false
}
}Status codes
201Created.400bad_request: the name is missing or too long.401No valid token.409too_many: the account already has 100 checks.
Settings
| Setting | What it does |
|---|---|
template | auto (default): the question table when the file has one, else the whole document. table: a Word table of question rows (Q1, Question 2…) each followed by an answer row (A1, Answer, Your Answer…). document: the whole document is one answer. |
wholeAnswerPercent | Flag when whole answers are at least this similar, 50 to 100. Default 70. |
sharedRunWords | Flag when answers share a run of at least this many content words, 3 to 50. Default 5. |
paragraphPercent, paragraphMinWords | Flag when a paragraph pair of at least 10 words (3 to 200) is at least 95% similar (50 to 100). |
minAnswerWords | Answers with fewer content words are flagged only when identical, and not when three or more students gave the same one. Default 5. |
ignoreQuestionText | Leave the question’s own words out. Default true. |
commonTextShare, commonTextMinAnswers | Text in at least this share of the answers (default 0.5) is class-common and not counted, once at least 6 files answered. |
aiReport | Default false. The AI report is coming soon and is not available yet: leave this off. A run that asks for it gets an ai block with status unavailable and is not charged for it, but its estimate, and the balance check before the run, still count it. |
Values out of range are brought into range, not refused.
GET /match/checks
Your own checks, most recently updated first.
Status codes
200A list of checks, each shaped like the one above.401No valid token.
GET /match/checks/{checkId}
One check and its files. While a run is on, status is queued or running and progressPercent shows how far it has got. Poll this until status is completed or failed.
| Parameter | In | Description |
|---|---|---|
checkId | path | The check’s id. |
Response (one of the six files shown)
{
"check": {
"checkId": "<checkId>",
"name": "Science unit test",
"status": "completed",
"createdAt": "<UTC time>",
"updatedAt": "<UTC time>",
"completedAt": "<UTC time>",
"jobId": "<jobId>",
"progressPercent": null,
"fileCount": 6,
"readFileCount": 6,
"questionCount": 3,
"flaggedPairCount": 2,
"lastError": null,
"settings": {
"template": "auto",
"wholeAnswerPercent": 70,
"sharedRunWords": 5,
"paragraphPercent": 95,
"paragraphMinWords": 10,
"minAnswerWords": 5,
"ignoreQuestionText": true,
"commonTextShare": 0.5,
"commonTextMinAnswers": 6,
"aiReport": false
}
},
"files": [
{
"fileId": "<fileId>",
"originalName": "student-01.docx",
"sizeBytes": "<bytes>",
"status": "read",
"questionCount": 3,
"warnings": [],
"uploadedAt": "<UTC time>",
"charged": true
}
]
}Status codes
200The check.401No valid token.404not_found.
PUT /match/checks/{checkId}
Renames a check or changes its settings. Leave a field out to keep it. A report keeps the settings it was made with; run again to use the new ones.
| Parameter | In | Description |
|---|---|---|
name | body | Optional. |
settings | body | Optional. |
Request
curl -H "Authorization: Bearer $DOCSPRY_TOKEN" -X PUT -H "Content-Type: application/json" \
-d '{"settings":{"wholeAnswerPercent":80}}' \
https://api.docspry.com/match/checks/$CHECKStatus codes
200The check.400bad_request.404not_found.409check_busy: a run is on.
DELETE /match/checks/{checkId}
Deletes the check, its files and its report now.
Status codes
204Deleted.404not_found.409check_busy.
Files
POST /match/checks/{checkId}/files
Adds students’ Word files: many per request, each in a form field named files. Each file is accepted or rejected on its own, and the answer lists both. A file’s type is checked from its own first bytes, whatever its name says.
| Parameter | In | Description |
|---|---|---|
files | form (file, repeated) | .docx or .doc, up to 20 MB each, 300 per check. |
Request
curl -H "Authorization: Bearer $DOCSPRY_TOKEN" \
-F files=@student-01.docx -F files=@student-02.docx -F files=@notes.pdf \
https://api.docspry.com/match/checks/$CHECK/filesResponse
{
"files": [
{
"fileId": "<fileId>",
"originalName": "student-01.docx",
"sizeBytes": "<bytes>",
"status": "uploaded",
"questionCount": 0,
"warnings": [],
"uploadedAt": "<UTC time>",
"charged": false
}
],
"rejected": [
{
"name": "notes.pdf",
"reason": "Only Word files (.docx, .doc) can be checked."
}
]
}Status codes
200Read: seefilesandrejected. Reasons include “The file is larger than 20 MB.” and “A check holds 300 files at most.”400bad_request: not multipart, or no usable boundary.404not_found.409check_busy, orstorage_full: your Match files already use all 2 GB.413too_large: too much for one request. Send fewer files at a time.
DELETE /match/checks/{checkId}/files/{fileId}
Removes one file. The check goes back to draft, because its report listed that file. Tokens a run charged for the file are not given back.
Status codes
204Removed.404not_found: no such check or file.409check_busy.
Runs and reports
POST /match/checks/{checkId}/run
Starts the comparison. One check of an account runs at a time. The wallet is asked first for the most the run can cost; files already charged in this check are not charged again.
Request
curl -H "Authorization: Bearer $DOCSPRY_TOKEN" -X POST https://api.docspry.com/match/checks/$CHECK/runResponse: 202 Accepted (the six-file sample)
{
"jobId": "<jobId>",
"filesToCharge": 6,
"aiFilesToCharge": 0,
"estimatedTokens": 300
}Status codes
202Queued.402Not enough tokens, or today’s limit is used. The body carrieserror(insufficient_balance,daily_limit_exceeded…),cost,balance,dailyUsed,dailyLimitand amessage.404not_found.409check_busy;run_in_progress: another of your checks is queued or running;no_files. (ai_limitandai_retry_limitbelong to the AI report, which is not available yet.)
GET /match/checks/{checkId}/report
The report of the last run. The example is the sample class, with its questions cut to the most strongly flagged one.
Response
{
"reportVersion": 1,
"checkId": "<checkId>",
"engineVersion": "<engine version>",
"generatedUtc": "<UTC time>",
"durationMs": "<ms>",
"settings": {
"template": "auto",
"wholeAnswerPercent": 70,
"sharedRunWords": 5,
"paragraphPercent": 95,
"paragraphMinWords": 10,
"minAnswerWords": 5,
"ignoreQuestionText": true,
"commonTextShare": 0.5,
"commonTextMinAnswers": 6,
"aiReport": false
},
"files": [
{
"fileId": "student-01.docx",
"name": "student-01.docx",
"status": "read",
"questionCount": 3,
"warnings": []
},
{
"fileId": "student-02.docx",
"name": "student-02.docx",
"status": "read",
"questionCount": 3,
"warnings": []
},
{
"fileId": "student-03.docx",
"name": "student-03.docx",
"status": "read",
"questionCount": 3,
"warnings": []
},
{
"fileId": "student-04.docx",
"name": "student-04.docx",
"status": "read",
"questionCount": 3,
"warnings": []
},
{
"fileId": "student-05.docx",
"name": "student-05.docx",
"status": "read",
"questionCount": 3,
"warnings": []
},
{
"fileId": "student-06.docx",
"name": "student-06.docx",
"status": "read",
"questionCount": 3,
"warnings": []
}
],
"questions": [
{
"questionKey": "3",
"questionNumber": "3",
"questionText": "Describe an experiment that shows a leaf needs light to make starch.",
"answeredCount": 6,
"groups": [
{
"groupId": 1,
"fileIds": [
"student-01.docx",
"student-03.docx"
]
}
],
"pairs": [
{
"pairId": "54505353f4bf2f12",
"fileA": "student-01.docx",
"fileB": "student-03.docx",
"score": 92,
"reason": "wholeAnswer",
"coverageA": 100,
"coverageB": 93,
"longestRunWords": 25,
"diff": [
{
"op": "equal",
"text": "Keep a potted plant in the dark for two days to remove its starch. Cover part of one leaf with black paper and leave the plant in sunlight for a day. Test the leaf with iodine: only the uncovered part turns blue-black, so starch was made only where light reached the leaf."
},
{
"op": "insert",
"text": " This proves light is needed."
}
]
}
],
"omittedPairs": 0
}
],
"summary": {
"files": 6,
"readFiles": 6,
"questions": 3,
"flaggedQuestions": 2,
"flaggedPairs": 2,
"filesInvolved": 4
},
"ai": null
}Status codes
200The report.404not_found, orno_reportbefore the first run or after a file was removed.
Report fields
| Field | What it holds |
|---|---|
settings | The settings the run used. |
files[] | fileId, name, status (read or unreadable), questionCount, warnings. |
questions[] | Every question at least two files answered: questionKey, questionNumber, questionText, answeredCount, groups, pairs and omittedPairs. Questions with nothing flagged are listed too. |
questions[].groups[] | Students linked by flagged pairs, largest group first. |
questions[].pairs[] | pairId (stable across runs), fileA, fileB, score 0 to 100, reason (identical, wholeAnswer, paragraph, sharedRun), coverageA, coverageB, longestRunWords and diff. Highest score first, at most 400 a question. |
questions[].omittedPairs | Flagged pairs not listed because the question had more than 400. The groups still name every flagged student. |
questions[].pairs[].diff[] | Spans from A’s answer to B’s: equal (both wrote it), delete (only A), insert (only B). |
summary | files, readFiles, questions, flaggedQuestions, flaggedPairs, filesInvolved. |
ai | Null unless the run asked for the AI report, which is not available yet. Such a run gets status unavailable here. |
GET /match/checks/{checkId}/verdicts
The teacher’s rulings on the check’s flagged pairs: cleared (looked at, not copying) or followUp, each with an optional note. A pair keeps its id across runs, so a verdict survives a re-run.
Status codes
200A list of verdicts, each shaped like the one below.404not_found.
PUT /match/checks/{checkId}/verdicts/{pairId}
Sets the verdict on one flagged pair of the current report, also while a run is on. An empty verdict clears it.
| Parameter | In | Description |
|---|---|---|
pairId | path | From the report. |
verdict | body | cleared, followUp, or empty. |
note | body | Optional, up to 1,000 characters. |
Request
curl -H "Authorization: Bearer $DOCSPRY_TOKEN" -X PUT -H "Content-Type: application/json" \
-d '{"verdict":"followUp","note":"Talk to both students"}' \
https://api.docspry.com/match/checks/$CHECK/verdicts/54505353f4bf2f12Response
{
"pairId": "54505353f4bf2f12",
"verdict": "followUp",
"note": "Talk to both students",
"at": "<UTC time>"
}Status codes
200The verdict.400bad_request: not a pair id, an unknown verdict, or a note too long.404not_found, orunknown_pair: the current report does not list that pair.409too_many: the check holds 5,000 verdicts.
GET /match/checks/{checkId}/report/download-link
A short-lived link (15 minutes) that downloads the report, with the verdicts as they are now, as HTML, or the pairs as CSV. The link itself needs no token.
| Parameter | In | Description |
|---|---|---|
format | query | html (default) or csv. |
Request
curl -H "Authorization: Bearer $DOCSPRY_TOKEN" "https://api.docspry.com/match/checks/$CHECK/report/download-link?format=csv"Response
{
"url": "<download link>",
"expiresAt": "<UTC time>"
}Status codes
200The link.400bad_request: an unknown format.404not_foundorno_report.413too_large: the report is too large for one file. Read it withGET …/report.
Errors
| Status | What it means | What to do |
|---|---|---|
400 | bad_request: a field is missing or not valid. | Read message, fix the request. |
401 | No valid bearer token. | Sign in again: the Match app sends the token for you. |
402 | Not enough tokens for the run, or today’s plan limit is used. The body says which, with the cost and your balance. | Top up, or run the check tomorrow. |
404 | not_found: no such check (or file) in your account; another account’s check also answers 404. no_report: the check has no report yet. unknown_pair: the report does not list that pair. | Check the id; run the check first; reload the report. |
409 | check_busy: the check is running. run_in_progress: another of your checks is running. no_files: nothing to run. storage_full: your Match files use all 2 GB. too_many: 100 checks already, or too many verdicts on one check. | Wait for the run to finish, add files first, or delete a check you no longer need. |
413 | too_large: the upload is too large for one request, or a report too large to download as one file. A single file over 20 MB is not a 413: it comes back in the upload answer’s rejected list. | Send fewer files per request; read a very large report with GET …/report. |
Limits and pricing
| Call | Price |
|---|---|
POST /match/checks/{checkId}/run | 50 tokens per file read (₹0.50 worth on a paid monthly plan, before tax), charged once per file per check. Files Match cannot open are free. The AI report is not available yet and is not charged. |
| Every other route | Free |
- 300 files per check; 20 MB per file;
.docxand.doconly. - Check names of 1 to 120 characters; file names up to 255.
- 100 checks per account, and 2 GB of Match files per account.
- One run at a time per account.
- 5,000 verdicts per check; notes up to 1,000 characters.
- A check, its files and its report are deleted 15 days after last use, or after the retention period chosen under Settings → Privacy, like other documents.
- Tokens come from your DocSpry wallet; plan allowances and daily limits apply. See plans.
Use DocSpry Match today.
The Match app does all of this for you: sign in, create a check and add your students’ files. 50 tokens a file.