{"openapi":"3.1.0","info":{"title":"Truessay Plagiarism API","version":"1.0.0","description":"Asynchronous public-web evidence checks. Quick compares returned snippets; Deep retrieves accessible source text. No private corpus or semantic paraphrase detection."},"servers":[{"url":"https://truessay.com/v1/plagiarism"}],"security":[{"bearerAuth":[]}],"paths":{"/account":{"get":{"summary":"Account balance","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"credits":{"type":"integer"},"creditDebt":{"type":"integer"},"billingHold":{"type":"boolean"},"trialClaimed":{"type":"boolean"},"trialEligible":{"type":"boolean"}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[]}},"/offers":{"get":{"summary":"Public prepaid offers","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"packs":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"priceUsd":{"type":"number"},"credits":{"type":"integer"}},"required":[]}},"wordsPerUnit":{"type":"integer"},"creditsPerUnit":{"type":"object","properties":{"quick":{"type":"integer"},"deep":{"type":"integer"}},"required":[]}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[],"security":[]}},"/quote":{"post":{"summary":"Validate text and quote credits","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"wordCount":{"type":"integer"},"units":{"type":"integer"},"credits":{"type":"integer"},"queryBudget":{"type":"integer"},"sourceBudget":{"type":"integer"},"fallbackCredits":{"type":"integer","description":"Reduced Deep charge if candidates are found but no full source text can be retrieved; two credits per started unit."}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanInput"}}}}}},"/scans":{"post":{"summary":"Submit scan","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"scan":{"$ref":"#/components/schemas/Scan"},"replayed":{"type":"boolean"}},"required":[]}}}},"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"scan":{"$ref":"#/components/schemas/Scan"},"replayed":{"type":"boolean"}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanInput"}}}}},"get":{"summary":"Paginated scan history","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"scans":{"type":"array","items":{"$ref":"#/components/schemas/Scan"}},"nextCursor":{"type":["string","null"]}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}}]}},"/scans/{id}":{"get":{"summary":"Scan status","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"scan":{"$ref":"#/components/schemas/Scan"}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]},"delete":{"summary":"Delete document and evidence","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/scans/{id}/report":{"get":{"summary":"Evidence report","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"scan":{"$ref":"#/components/schemas/Scan"},"report":{"$ref":"#/components/schemas/Report"}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/scans/{id}/cancel":{"post":{"summary":"Cancel active scan and return credits","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"scan":{"$ref":"#/components/schemas/Scan"}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/scans/{id}/webhook":{"get":{"summary":"Webhook delivery status","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"anyOf":[{"type":"null"},{"type":"object","properties":{"id":{"type":"string"},"status":{"enum":["pending","delivered","failed"]},"attempts":{"type":"integer"},"last_status":{"type":["integer","null"]},"delivered_at":{"type":["integer","null"]}},"required":[]}]}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]},"post":{"summary":"Retry failed webhook","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"boolean"}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/activity":{"get":{"summary":"Latest 50 credit events","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"delta":{"type":"integer"},"scan_id":{"type":["string","null"]},"created_at":{"type":"integer"}},"required":[]}}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[]}},"/extract":{"post":{"summary":"Extract uploaded text without scanning","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"wordCount":{"type":"integer"},"filename":{"type":"string"}},"required":[]}}}},"default":{"description":"Structured API error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Truessay-Filename","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary","description":"Max 5 MB; TXT/MD/DOCX/text PDF."}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"tp_live_ API key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Range":{"type":"object","properties":{"start":{"type":"integer","minimum":0},"end":{"type":"integer","minimum":0}},"required":["start","end"]},"ScanInput":{"type":"object","properties":{"text":{"type":"string","maxLength":160000,"description":"20–20,000 English words"},"title":{"type":"string","maxLength":160},"mode":{"enum":["quick","deep"]},"options":{"type":"object","properties":{"excludeQuotes":{"type":"boolean","default":false},"excludeReferences":{"type":"boolean","default":false}},"required":[]},"webhookUrl":{"type":"string","format":"uri","description":"Public HTTPS only."}},"required":["text","mode"]},"Scan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"mode":{"enum":["quick","deep"]},"status":{"enum":["queued","searching","retrieving","matching","complete","partial","failed","canceled"]},"wordCount":{"type":"integer"},"progress":{"type":"integer","minimum":0,"maximum":100},"creditsReserved":{"type":"integer"},"creditsCharged":{"type":"integer"},"errorCode":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"]},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","mode","status","wordCount","progress","creditsReserved","creditsCharged"]},"Match":{"type":"object","properties":{"id":{"type":"string"},"sourceId":{"type":"string"},"kind":{"enum":["exact","near_exact"]},"scope":{"enum":["snippet","full_text"]},"inputRanges":{"type":"array","items":{"$ref":"#/components/schemas/Range"}},"sourceRanges":{"type":"array","items":{"$ref":"#/components/schemas/Range"}},"inputExcerpt":{"type":"string"},"sourceExcerpt":{"type":"string"},"matchedWords":{"type":"integer"},"snippetIndex":{"type":"integer","minimum":0,"description":"Zero-based index in the owning source snippets array; snippet evidence only."}},"required":["sourceId","kind","scope","inputRanges","sourceRanges","matchedWords"]},"Source":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"snippets":{"type":"array","items":{"type":"string"}},"retrieval":{"enum":["not_requested","retrieved","blocked","failed","unsupported","budget_exhausted"]},"contentType":{"type":"string"},"matchedWords":{"type":"integer"},"retrievedAt":{"type":"string","format":"date-time"},"resolvedUrl":{"type":"string","format":"uri"},"truncated":{"type":"boolean","description":"Only the first 300,000 extracted characters were compared."},"textExtent":{"enum":["page_text","pdf_text","abstract_only","limited_text"]},"retrievalError":{"type":"string"}},"required":["id","url","retrieval"]},"Report":{"type":"object","properties":{"version":{"const":"1"},"mode":{"enum":["quick","deep"]},"title":{"type":"string"},"text":{"type":"string"},"status":{"enum":["complete","partial"]},"generatedAt":{"type":"string","format":"date-time"},"options":{"type":"object","properties":{"excludeQuotes":{"type":"boolean"},"excludeReferences":{"type":"boolean"}},"required":[]},"wordCount":{"type":"integer"},"eligibleWords":{"type":"integer"},"excludedWords":{"type":"integer"},"matchedWords":{"type":"integer"},"overlapPercent":{"type":"number","minimum":0,"maximum":100},"evidenceScope":{"enum":["snippet","mixed"]},"matches":{"type":"array","items":{"$ref":"#/components/schemas/Match"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"coverage":{"type":"object","properties":{"queriedRanges":{"type":"array","items":{"$ref":"#/components/schemas/Range"}},"queriesPlanned":{"type":"integer"},"queriesCompleted":{"type":"integer"},"paidSearchAttempts":{"type":"integer"},"sourceFetchAttempts":{"type":"integer"},"sourcesRetrieved":{"type":"integer"},"candidateSources":{"type":"integer"},"queryBudget":{"type":"integer"},"sourceBudget":{"type":"integer"},"searchQueries":{"type":"array","items":{"type":"object","properties":{"query":{"type":"string"},"start":{"type":"integer"},"end":{"type":"integer"},"kind":{"enum":["exact_phrase","broader"]},"outcome":{"enum":["completed","failed","not_run"]},"hitCount":{"type":"integer"}},"description":"Input phrase offsets, or an empty 0–0 range for source-title discovery. Failed and unexecuted work is retained."}},"evidenceLimitReached":{"type":"boolean","description":"The finding count/size limit interrupted alignment; overlap counts retained supported evidence only."},"fullTextSourcesRetrieved":{"type":"integer","minimum":0,"description":"Retrieved sources excluding known abstract-only or access-limited pages."}},"required":[]},"warnings":{"type":"array","items":{"type":"string"}},"semanticStatus":{"const":"disabled"},"versions":{"type":"object","properties":{"engine":{"type":"string"},"tokenizer":{"type":"string"},"scoring":{"type":"string"},"searchPolicy":{"type":"string"}},"required":[]}},"required":["mode","text","matchedWords","overlapPercent","matches","sources","coverage","warnings","semanticStatus"]}}},"webhooks":{"scanFinished":{"post":{"summary":"Signed terminal scan notification; deduplicate by body.id","parameters":[{"name":"Truessay-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"Truessay-Event-Id","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"const":"plagiarism.scan.finished"},"scan":{"$ref":"#/components/schemas/Scan"}},"required":["id","type","scan"]}}}},"responses":{"200":{"description":"Receiver durably accepted notification"}}}}}}