{ "openapi": "3.1.1", "info": { "title": "Deadline Decoder API", "version": "1.0.0", "summary": "Find every deadline, required action and consequence in a letter or notice.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://deadlinedecoder.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Find every deadline, required action and consequence in a letter or notice.", "description": "Paste or upload an official letter, invoice, reminder or notice (English or German). Deadline Decoder extracts absolute dates and relative deadlines such as \"within 14 days\" or \"binnen eines Monats\", resolves them against the letter or receipt date, lists what you must do and what happens otherwise, and exports the deadlines as a calendar (.ics) file.\n\nMethodology:\n- The text is split into sentences (paragraph-, bullet- and abbreviation-aware; German ordinal dates like \"12. Oktober\" are not treated as sentence ends).\n- Absolute dates are matched in the formats 2026-10-12, 12.10.2026, 12/10/2026 (day/month or month/day as selected; an unambiguous day > 12 overrides), \"October 12, 2026\", \"12 Oct 2026\" and \"12. Oktober 2026\". Impossible dates (31.02.) are discarded.\n- A date counts as a deadline when its sentence contains a deadline cue (by, until, no later than, due, bis, spätestens, fällig, Frist …) or a required-action pattern; other dates are listed as \"mentioned\".\n- Relative deadlines (\"within 14 days\", \"no later than 30 days after receipt\", \"innerhalb von 2 Wochen\", \"binnen eines Monats\") are added to the reference date: days and weeks as calendar days, business days skip Saturdays and Sundays (public holidays are not considered), months/years as calendar months (clamped to the month end).\n- Required actions are sentences matching modal or request patterns (must, shall, required, please pay/submit, bitte, müssen, \"ist … zu zahlen\", \"überweisen Sie\" …). Consequences are sentences with otherwise/failure-to/fee/penalty/escalation patterns (andernfalls, sonst, Mahngebühr, Säumniszuschlag, Inkasso, Vollstreckung …).\n- Every finding quotes the exact sentence and names the rule that fired. Confidence is \"pattern-match\": nothing is guessed by an AI model.\n\nNot legal advice. Rule-based extraction can miss deadlines or misread dates, and legal deadline rules (e.g. when a letter counts as received, weekends and public holidays) differ by country and authority. Always check the original document and, if in doubt, ask the sender or an adviser.", "tags": [ "everyday" ], "x-mcp-tool": "deadline_decoder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineDecoderInput" }, "examples": { "example1": { "summary": "German payment reminder (Mahnung)", "value": { "text": "Zahlungserinnerung\nDatum: 05.10.2026\n\nSehr geehrte Frau Muster,\nleider konnten wir bis heute keinen Zahlungseingang für die Rechnung Nr. 4711 vom 01.09.2026 feststellen. Bitte überweisen Sie den offenen Betrag von 89,90 EUR bis spätestens 20. Oktober 2026 auf das unten genannte Konto. Andernfalls müssen wir eine Mahngebühr von 5,00 EUR berechnen und die Forderung an ein Inkassobüro übergeben. Gegen diesen Bescheid kann innerhalb eines Monats nach Bekanntgabe Widerspruch eingelegt werden.", "referenceDate": "2026-10-07", "referenceType": "received", "dateOrder": "DMY" } }, "example2": { "summary": "US insurance notice", "value": { "text": "Notice date: October 1, 2026\n\nWe need additional information to process your claim. You must submit the enclosed form and a copy of your medical bills within 30 days after receipt of this notice. If we do not receive the documents, your claim will be closed. Your premium payment of $142.50 is due 10/25/2026; failure to pay by the due date may result in a late fee of $15 and cancellation of your policy.", "referenceDate": "2026-10-03", "referenceType": "received", "dateOrder": "MDY" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeadlineDecoderResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "DeadlineDecoderInput": { "type": "object", "additionalProperties": false, "properties": { "text": { "title": "Letter or notice text", "description": "Paste the text here, or use one of the other options below (exactly one).", "type": "string", "maxLength": 200000 }, "file": { "title": "Or upload a file", "description": "TXT, PDF, DOCX, HTML or a photo/scan (PNG/JPG, read with OCR). Max 5 MiB. Upload as {filename, contentType?, contentBase64}. Max 5120 KiB. Accepts .txt,.pdf,.docx,.png,.jpg,.jpeg,.html.", "type": "object", "additionalProperties": false, "required": [ "filename", "contentBase64" ], "properties": { "filename": { "type": "string" }, "contentType": { "type": "string" }, "contentBase64": { "type": "string" } } }, "referenceDate": { "title": "Reference date", "description": "Date of the letter or the day you received it. Relative deadlines (\"within 14 days\") are counted from here. Defaults to today.", "type": "string", "format": "date" }, "referenceType": { "title": "The reference date is…", "type": "string", "enum": [ "received", "letter" ], "default": "received" }, "dateOrder": { "title": "Numeric dates like 03/04/2026 are", "type": "string", "enum": [ "DMY", "MDY" ], "default": "DMY" } }, "required": [] }, "DeadlineDecoderResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "referenceDate", "referenceType", "today", "deadlines", "datesMentioned", "actions", "consequences", "nextDeadline", "confidence" ], "properties": { "referenceDate": { "type": "string", "format": "date" }, "referenceType": { "type": "string", "enum": [ "letter", "received" ] }, "today": { "type": "string", "format": "date" }, "confidence": { "type": "string", "const": "pattern-match", "description": "All findings come from fixed text patterns, not from a statistical model." }, "nextDeadline": { "type": [ "object", "null" ], "description": "Earliest deadline that is today or upcoming, or null." }, "deadlines": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date", "daysRemaining", "status", "kind", "rule", "matchedText", "evidence", "action", "calculation" ], "properties": { "date": { "type": "string", "format": "date" }, "daysRemaining": { "type": "integer", "description": "Calendar days from today (negative = overdue)." }, "status": { "type": "string", "enum": [ "overdue", "today", "upcoming" ] }, "kind": { "type": "string", "enum": [ "absolute", "relative" ] }, "rule": { "type": "string" }, "matchedText": { "type": "string" }, "evidence": { "type": "string", "description": "Exact sentence the deadline was found in." }, "action": { "type": "string" }, "calculation": { "type": "string" } } } }, "datesMentioned": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date", "matchedText", "rule", "evidence" ], "properties": { "date": { "type": "string", "format": "date" }, "matchedText": { "type": "string" }, "rule": { "type": "string" }, "evidence": { "type": "string" } } } }, "actions": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "action", "rule", "evidence" ], "properties": { "action": { "type": "string" }, "rule": { "type": "string" }, "evidence": { "type": "string" } } } }, "consequences": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "rules", "amounts", "evidence" ], "properties": { "rules": { "type": "array", "items": { "type": "string" } }, "amounts": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "string" } } } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }