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.com

A 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/report

Python

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.

ParameterInDescription
namebody1 to 120 characters.
settingsbodyOptional. 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/checks

Response: 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

  • 201 Created.
  • 400 bad_request: the name is missing or too long.
  • 401 No valid token.
  • 409 too_many: the account already has 100 checks.

Settings

SettingWhat it does
templateauto (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.
wholeAnswerPercentFlag when whole answers are at least this similar, 50 to 100. Default 70.
sharedRunWordsFlag when answers share a run of at least this many content words, 3 to 50. Default 5.
paragraphPercent, paragraphMinWordsFlag when a paragraph pair of at least 10 words (3 to 200) is at least 95% similar (50 to 100).
minAnswerWordsAnswers with fewer content words are flagged only when identical, and not when three or more students gave the same one. Default 5.
ignoreQuestionTextLeave the question’s own words out. Default true.
commonTextShare, commonTextMinAnswersText in at least this share of the answers (default 0.5) is class-common and not counted, once at least 6 files answered.
aiReportDefault 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

  • 200 A list of checks, each shaped like the one above.
  • 401 No 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.

ParameterInDescription
checkIdpathThe 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

  • 200 The check.
  • 401 No valid token.
  • 404 not_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.

ParameterInDescription
namebodyOptional.
settingsbodyOptional.

Request

curl -H "Authorization: Bearer $DOCSPRY_TOKEN" -X PUT -H "Content-Type: application/json" \
     -d '{"settings":{"wholeAnswerPercent":80}}' \
     https://api.docspry.com/match/checks/$CHECK

Status codes

  • 200 The check.
  • 400 bad_request.
  • 404 not_found.
  • 409 check_busy: a run is on.

DELETE /match/checks/{checkId}

Deletes the check, its files and its report now.

Status codes

  • 204 Deleted.
  • 404 not_found.
  • 409 check_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.

ParameterInDescription
filesform (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/files

Response

{
  "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

  • 200 Read: see files and rejected. Reasons include “The file is larger than 20 MB.” and “A check holds 300 files at most.”
  • 400 bad_request: not multipart, or no usable boundary.
  • 404 not_found.
  • 409 check_busy, or storage_full: your Match files already use all 2 GB.
  • 413 too_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

  • 204 Removed.
  • 404 not_found: no such check or file.
  • 409 check_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/run

Response: 202 Accepted (the six-file sample)

{
  "jobId": "<jobId>",
  "filesToCharge": 6,
  "aiFilesToCharge": 0,
  "estimatedTokens": 300
}

Status codes

  • 202 Queued.
  • 402 Not enough tokens, or today’s limit is used. The body carries error (insufficient_balance, daily_limit_exceeded…), cost, balance, dailyUsed, dailyLimit and a message.
  • 404 not_found.
  • 409 check_busy; run_in_progress: another of your checks is queued or running; no_files. (ai_limit and ai_retry_limit belong 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

  • 200 The report.
  • 404 not_found, or no_report before the first run or after a file was removed.

Report fields

FieldWhat it holds
settingsThe 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[].omittedPairsFlagged 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).
summaryfiles, readFiles, questions, flaggedQuestions, flaggedPairs, filesInvolved.
aiNull 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

  • 200 A list of verdicts, each shaped like the one below.
  • 404 not_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.

ParameterInDescription
pairIdpathFrom the report.
verdictbodycleared, followUp, or empty.
notebodyOptional, 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/54505353f4bf2f12

Response

{
  "pairId": "54505353f4bf2f12",
  "verdict": "followUp",
  "note": "Talk to both students",
  "at": "<UTC time>"
}

Status codes

  • 200 The verdict.
  • 400 bad_request: not a pair id, an unknown verdict, or a note too long.
  • 404 not_found, or unknown_pair: the current report does not list that pair.
  • 409 too_many: the check holds 5,000 verdicts.

Errors

StatusWhat it meansWhat to do
400bad_request: a field is missing or not valid.Read message, fix the request.
401No valid bearer token.Sign in again: the Match app sends the token for you.
402Not 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.
404not_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.
409check_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.
413too_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

CallPrice
POST /match/checks/{checkId}/run50 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 routeFree
  • 300 files per check; 20 MB per file; .docx and .doc only.
  • 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.

Open DocSpry Match