{ "openapi": "3.1.0", "info": { "title": "RecovAI API", "version": "2026-10-15", "description": "Create recovery cases, upload documents, record recoveries and manage tasks. Guides: https://apidocs.recovai.ai/" }, "servers": [ { "url": "https://api.recovai.ai" } ], "security": [ { "apiKey": [] }, { "bearer": [] } ], "tags": [ { "name": "Cases", "description": "Recovery cases: one account in recovery each." }, { "name": "Notes and timeline", "description": "Notes and the append-only audit timeline of a case." }, { "name": "Documents", "description": "Documents attached to a case." }, { "name": "Recoveries", "description": "A case's recovery ledger." }, { "name": "Tasks", "description": "Work items for your team." }, { "name": "Background jobs", "description": "Long-running work started by other requests." } ], "paths": { "/cases": { "post": { "tags": [ "Cases" ], "operationId": "createCase", "summary": "Create a case", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "business_name" ], "properties": { "business_name": { "type": "string", "maxLength": 300 }, "dba": { "type": "string", "maxLength": 300 }, "legal_entity": { "type": "string", "maxLength": 100 }, "industry": { "type": "string", "maxLength": 200 }, "product": { "type": "string", "maxLength": 200 }, "collateral_type": { "type": "string", "maxLength": 200 }, "ucc_filing_number": { "type": "string", "maxLength": 100 }, "balance": { "type": "number", "exclusiveMinimum": 0, "description": "Amount owed, USD." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "business_address": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": false, "properties": { "line1": { "type": "string" }, "street": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" } } } ] }, "business_identifiers": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } }, "external_reference": { "type": "string" }, "source": { "type": "string", "enum": [ "manual", "external_sync", "import", "bulk_upload", "folder_upload" ] }, "source_system": { "type": "string" }, "source_record_id": { "type": "string" }, "client_id": { "type": "string", "format": "uuid" }, "assignee_id": { "type": "string", "format": "uuid" }, "assignee_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "$ref": "#/components/schemas/Case" }, "duplicates": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } }, "get": { "tags": [ "Cases" ], "operationId": "listCases", "summary": "List cases", "parameters": [ { "name": "closure", "in": "query", "schema": { "type": "string", "enum": [ "open", "closed", "all" ], "default": "open" } }, { "name": "readiness", "in": "query", "schema": { "type": "string", "enum": [ "draft", "needs_core_documents", "ready_for_extraction", "extraction_in_review", "ready_for_compliance_priority_review", "ready_for_target_discovery", "strategy_ready", "targets_ready", "ready_to_submit", "submitted", "response_received", "no_response", "resolution_pending", "blocked", "duplicate_review", "failed_processing" ] } }, { "name": "q", "in": "query", "description": "Search text.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "take", "in": "query", "description": "Page size, up to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "skip", "in": "query", "description": "Number of items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A page of cases.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cases": { "type": "array", "items": { "$ref": "#/components/schemas/Case" } }, "total": { "type": "integer" }, "skip": { "type": "integer" }, "take": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/cases/{id}": { "get": { "tags": [ "Cases" ], "operationId": "getCase", "summary": "Get a case", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The full case.", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "$ref": "#/components/schemas/Case" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Cases" ], "operationId": "updateCase", "summary": "Update a case", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "expected_row_version" ], "properties": { "expected_row_version": { "type": "integer", "minimum": 1 }, "business_name": { "type": "string", "maxLength": 300 }, "dba": { "type": "string", "maxLength": 300 }, "legal_entity": { "type": "string", "maxLength": 100 }, "industry": { "type": "string", "maxLength": 200 }, "product": { "type": "string", "maxLength": 200 }, "collateral_type": { "type": "string", "maxLength": 200 }, "ucc_filing_number": { "type": "string", "maxLength": 100 }, "balance": { "type": "number", "exclusiveMinimum": 0, "description": "Amount owed, USD." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "business_address": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": false, "properties": { "line1": { "type": "string" }, "street": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" } } } ] }, "readiness": { "type": "string", "enum": [ "draft", "needs_core_documents", "ready_for_extraction", "extraction_in_review", "ready_for_compliance_priority_review", "ready_for_target_discovery", "strategy_ready", "targets_ready", "ready_to_submit", "submitted", "response_received", "no_response", "resolution_pending", "blocked", "duplicate_review", "failed_processing" ] }, "status_note": { "type": "string", "maxLength": 1000 }, "main_blocker": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ], "maxLength": 500 }, "assignee_id": { "type": [ "string", "null" ], "format": "uuid" }, "assignee_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "client_id": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "case": { "$ref": "#/components/schemas/Case" }, "tasks_moved": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/cases/{id}/advance": { "post": { "tags": [ "Cases" ], "operationId": "runPipeline", "summary": "Run the pipeline", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "already_running": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/cases/import-csv": { "post": { "tags": [ "Cases" ], "operationId": "importCases", "summary": "Import cases in bulk", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rows" ], "properties": { "rows": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "business_name" ], "properties": { "business_name": { "type": "string" }, "dba": { "type": "string" }, "ucc_filing_number": { "type": "string" }, "balance": { "type": "string" }, "industry": { "type": "string" }, "product": { "type": "string" }, "client_name": { "type": "string" }, "ein": { "type": "string" }, "state": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "Per-row results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "case_number": { "type": "string" }, "business_name": { "type": "string" }, "action": { "type": "string", "enum": [ "created", "created_duplicate_review", "skipped" ] }, "reason": { "type": "string" } } } }, "created": { "type": "integer" }, "skipped": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/cases/{id}/notes": { "post": { "tags": [ "Notes and timeline" ], "operationId": "addNote", "summary": "Add a note", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 4000 } } } } } }, "responses": { "201": { "description": "Added.", "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "$ref": "#/components/schemas/Event" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/cases/{id}/events": { "get": { "tags": [ "Notes and timeline" ], "operationId": "listEvents", "summary": "List timeline events", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "take", "in": "query", "description": "Page size, up to 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "skip", "in": "query", "description": "Number of items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A page of events, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "total": { "type": "integer" }, "skip": { "type": "integer" }, "take": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/cases/{id}/documents": { "post": { "tags": [ "Documents" ], "operationId": "uploadDocument", "summary": "Upload a document", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "type" ], "properties": { "file": { "type": "string", "contentMediaType": "application/octet-stream", "description": "PDF, PNG, JPEG or TIFF, up to 25 MB." }, "type": { "type": "string", "enum": [ "ucc_filing", "contract", "bank_statement", "billing_statement", "generated_notice", "letter_of_representation", "letter_of_agency", "proof_of_assignment", "redacted_packet", "state_disclosure", "transaction_history", "correspondence", "return_receipt", "other" ] } } } } } }, "responses": { "201": { "description": "Uploaded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "doc": { "$ref": "#/components/schemas/Document" }, "duplicate_of_case_id": { "type": [ "string", "null" ], "format": "uuid" }, "readiness": { "type": "string", "enum": [ "draft", "needs_core_documents", "ready_for_extraction", "extraction_in_review", "ready_for_compliance_priority_review", "ready_for_target_discovery", "strategy_ready", "targets_ready", "ready_to_submit", "submitted", "response_received", "no_response", "resolution_pending", "blocked", "duplicate_review", "failed_processing" ] } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "413": { "$ref": "#/components/responses/Error" }, "415": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } }, "get": { "tags": [ "Documents" ], "operationId": "listDocuments", "summary": "List a case's documents", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Active documents, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/documents/{docId}/file": { "get": { "tags": [ "Documents" ], "operationId": "downloadDocument", "summary": "Download a document", "parameters": [ { "name": "docId", "in": "path", "required": true, "description": "Document ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "download", "in": "query", "description": "`1` to receive the file as an attachment.", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "The file.", "content": { "application/octet-stream": {} } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/cases/{id}/recoveries": { "get": { "tags": [ "Recoveries" ], "operationId": "getLedger", "summary": "Read the ledger", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The ledger.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ledger" } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Recoveries" ], "operationId": "addLedgerEntry", "summary": "Add an entry", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "type", "amount" ], "properties": { "type": { "type": "string", "enum": [ "funds_identified", "freeze", "redirect", "payment_plan", "settlement", "partial_recovery", "full_recovery", "cost", "remittance" ] }, "amount": { "type": "number", "minimum": 0.01, "multipleOf": 0.01 }, "currency": { "type": "string", "const": "USD" }, "occurred_at": { "type": "string", "format": "date-time" }, "payment_method": { "type": "string", "enum": [ "ach", "wire", "check", "card", "processor_transfer", "other" ] }, "reference": { "type": "string", "maxLength": 200 }, "counterparty": { "type": "string", "maxLength": 200 }, "note": { "type": "string", "maxLength": 4000 }, "evidence_document_id": { "type": [ "string", "null" ], "format": "uuid" }, "submission_id": { "type": [ "string", "null" ], "format": "uuid" }, "idempotency_key": { "type": "string", "minLength": 8, "maxLength": 100 } } } } } }, "responses": { "200": { "description": "Replayed: the entry already recorded under this idempotency key.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ledger" }, { "type": "object", "properties": { "entry": { "$ref": "#/components/schemas/RecoveryEntry" }, "replayed": { "type": "boolean" } } } ] } } } }, "201": { "description": "Recorded.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ledger" }, { "type": "object", "properties": { "entry": { "$ref": "#/components/schemas/RecoveryEntry" } } } ] } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/recoveries/{id}/reverse": { "post": { "tags": [ "Recoveries" ], "operationId": "reverseLedgerEntry", "summary": "Reverse an entry", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ledger entry ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 2000 } } } } } }, "responses": { "201": { "description": "Reversed.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Ledger" }, { "type": "object", "properties": { "entry": { "$ref": "#/components/schemas/RecoveryEntry" } } } ] } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/tasks": { "get": { "tags": [ "Tasks" ], "operationId": "listTasks", "summary": "List tasks", "parameters": [ { "name": "status", "in": "query", "description": "Comma-separated statuses.", "schema": { "type": "string" } }, { "name": "case_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "assigned_to", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "priority", "in": "query", "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] } }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 200 } }, { "name": "take", "in": "query", "description": "Page size, up to 250.", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } }, { "name": "skip", "in": "query", "description": "Number of items to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "A page of tasks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" } }, "total": { "type": "integer" }, "skip": { "type": "integer" }, "take": { "type": "integer" }, "has_more": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Tasks" ], "operationId": "createTask", "summary": "Create a task", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 4000 }, "case_id": { "type": [ "string", "null" ], "format": "uuid" }, "assigned_to": { "type": [ "string", "null" ], "format": "uuid" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "default": "normal" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/Task" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/tasks/{id}": { "get": { "tags": [ "Tasks" ], "operationId": "getTask", "summary": "Get a task", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Task ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The task and its history.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/Task" }, "history": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "tags": [ "Tasks" ], "operationId": "updateTask", "summary": "Update a task", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Task ID.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_row_version" ], "minProperties": 2, "properties": { "expected_row_version": { "type": "integer", "minimum": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 4000 }, "assigned_to": { "type": [ "string", "null" ], "format": "uuid" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "status": { "type": "string", "enum": [ "open", "in_progress", "completed", "cancelled" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "snoozed_until": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "responses": { "200": { "description": "Updated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "$ref": "#/components/schemas/Task" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/jobs/{jobId}": { "get": { "tags": [ "Background jobs" ], "operationId": "getJob", "summary": "Get a job", "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "Job ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/Job" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/jobs/{jobId}/cancel": { "post": { "tags": [ "Background jobs" ], "operationId": "cancelJob", "summary": "Cancel a job", "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "Job ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cancelled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/Job" } } } } } }, "202": { "description": "Cancellation requested for a running job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/Job" }, "cancellation_requested": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/jobs/{jobId}/retry": { "post": { "tags": [ "Background jobs" ], "operationId": "retryJob", "summary": "Retry a job", "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "Job ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Requeued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "$ref": "#/components/schemas/Job" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "A workspace API key (`rk_…`)." }, "bearer": { "type": "http", "scheme": "bearer", "description": "The same API key as a bearer token." } }, "responses": { "Error": { "description": "An error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "details": { "type": "string" } } }, "ValidationError": { "type": "object", "properties": { "error": { "type": "string", "const": "validation_error" }, "details": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "field": { "type": "string" } } } } } }, "Case": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "case_number": { "type": "string" }, "business_name": { "type": "string", "maxLength": 300 }, "dba": { "type": "string", "maxLength": 300 }, "legal_entity": { "type": "string", "maxLength": 100 }, "industry": { "type": "string", "maxLength": 200 }, "product": { "type": "string", "maxLength": 200 }, "collateral_type": { "type": "string", "maxLength": 200 }, "ucc_filing_number": { "type": "string", "maxLength": 100 }, "balance": { "type": [ "string", "null" ], "description": "Exact decimal amount, as a string." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "business_address": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": false, "properties": { "line1": { "type": "string" }, "street": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" } } } ] }, "readiness": { "type": "string", "enum": [ "draft", "needs_core_documents", "ready_for_extraction", "extraction_in_review", "ready_for_compliance_priority_review", "ready_for_target_discovery", "strategy_ready", "targets_ready", "ready_to_submit", "submitted", "response_received", "no_response", "resolution_pending", "blocked", "duplicate_review", "failed_processing" ] }, "main_blocker": { "type": [ "string", "null" ] }, "external_reference": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "assignee_id": { "type": [ "string", "null" ], "format": "uuid" }, "client_id": { "type": [ "string", "null" ], "format": "uuid" }, "row_version": { "type": "integer" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Document": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "case_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "ucc_filing", "contract", "bank_statement", "billing_statement", "generated_notice", "letter_of_representation", "letter_of_agency", "proof_of_assignment", "redacted_packet", "state_disclosure", "transaction_history", "correspondence", "return_receipt", "other" ] }, "status": { "type": "string" }, "verified": { "type": "boolean" }, "original_file_name": { "type": [ "string", "null" ] }, "mime_type": { "type": [ "string", "null" ] }, "file_size_bytes": { "type": [ "integer", "null" ] }, "ocr_status": { "type": "string" }, "extraction_status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "Event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "case_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "RecoveryEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "case_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "funds_identified", "freeze", "redirect", "payment_plan", "settlement", "partial_recovery", "full_recovery", "cost", "remittance", "reversal" ] }, "label": { "type": "string" }, "amount": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "status": { "type": [ "string", "null" ] }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "details": { "type": [ "object", "null" ] }, "idempotency_key": { "type": [ "string", "null" ] }, "reverses_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } }, "Ledger": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/RecoveryEntry" } }, "summary": { "type": "object", "properties": { "identified": { "type": "number" }, "frozen": { "type": "number" }, "redirected": { "type": "number" }, "committed": { "type": "number" }, "recovered": { "type": "number" }, "costs": { "type": "number" }, "remitted": { "type": "number" }, "net_recovered": { "type": "number" }, "awaiting_remittance": { "type": "number" }, "remaining_balance": { "type": "number" }, "recovery_rate": { "type": "number" }, "active_entries": { "type": "number" }, "reversal_count": { "type": "number" } } }, "currency": { "type": "string" } } }, "Task": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "open", "in_progress", "completed", "cancelled" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "source": { "type": "string" }, "case_id": { "type": [ "string", "null" ], "format": "uuid" }, "assigned_to": { "type": [ "string", "null" ], "format": "uuid" }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "snoozed_until": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "sla_state": { "type": "string", "enum": [ "on_track", "at_risk", "breached", "snoozed", "unscheduled", "completed", "cancelled" ] }, "row_version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } } }, "Job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "retry_wait", "done", "failed", "dead_letter", "cancelled" ] }, "progress": { "type": [ "object", "null" ] }, "result": {}, "error": { "type": [ "string", "null" ] }, "attempt": { "type": "integer" }, "max_attempts": { "type": "integer" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished": { "type": "boolean" }, "cancellable": { "type": "boolean" }, "retryable": { "type": "boolean" } } } } } }