{ "openapi": "3.1.0", "info": { "title": "Case Management API", "version": "1.0.0", "description": "Exposes the agency case management system through a governed, versioned API. Supports case lookup, status transitions with full history, and linking of documents and notes. Every call is authorized against the caller's scopes and recorded in the Audit Log API.\n\nReference design by Iron Brick LLC. Not an official government system; endpoints and data models are adapted to each agency's systems of record during implementation.", "contact": { "name": "Iron Brick LLC", "email": "info@ironbrick.us", "url": "https://dev.ironbrick.us" } }, "servers": [ { "url": "https://dev.ironbrick.us/sandbox/cases/v1", "description": "Iron Brick sandbox (synthetic data; free developer account)" }, { "url": "https://{agency-gateway}/cases/v1", "description": "Agency deployment (behind the agency API gateway)" } ], "security": [ { "oauth2": [ "cases:read", "cases:write" ] } ], "paths": { "/cases": { "get": { "operationId": "listCases", "summary": "Search cases", "tags": [ "Cases" ], "description": "Returns cases matching the filters, newest first. Results contain no personal identifiers beyond party IDs.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by status." }, { "name": "caseType", "in": "query", "schema": { "type": "string" }, "description": "Filter by case type." }, { "name": "updatedSince", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only cases updated at or after this time." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor from a previous response." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Maximum items to return." } ], "responses": { "200": { "description": "A page of cases", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Case" } }, "page": { "$ref": "#/components/schemas/Page" } } }, "example": { "data": [ { "caseId": "CASE-2026-004817", "caseType": "benefit_request", "status": "in_review", "priority": "standard", "receivedDate": "2026-08-14", "office": "Field Office 12", "lastUpdated": "2026-09-30T14:22:05Z", "version": 7 } ], "page": { "nextCursor": null, "limit": 50 } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cases/{caseId}": { "get": { "operationId": "getCase", "summary": "Get a case", "tags": [ "Cases" ], "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Case identifier." } ], "responses": { "200": { "description": "The case", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "updateCaseStatus", "summary": "Change case status", "tags": [ "Cases" ], "description": "Applies a status transition. Invalid transitions return 422. Requires `If-Match` with the current version.", "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Case identifier." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Current case version." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "example": "decided" }, "reasonCode": { "type": "string", "example": "approved" }, "note": { "type": "string", "example": "All evidence received." } } }, "example": { "status": "decided", "reasonCode": "approved", "note": "All evidence received." } } } }, "responses": { "200": { "description": "Updated case", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict (duplicate or stale version)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Business rule violation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cases/{caseId}/events": { "get": { "operationId": "listCaseEvents", "summary": "Get case history", "tags": [ "Cases" ], "description": "Chronological status and activity history for a case.", "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Case identifier." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor from a previous response." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 }, "description": "Maximum items to return." } ], "responses": { "200": { "description": "Case events", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CaseEvent" } }, "page": { "$ref": "#/components/schemas/Page" } } } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/cases/{caseId}/documents": { "get": { "operationId": "listCaseDocuments", "summary": "List linked documents", "tags": [ "Cases" ], "description": "Document references linked to the case. Retrieve content through the Document Services API.", "parameters": [ { "name": "caseId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Case identifier." } ], "responses": { "200": { "description": "Linked documents", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "documentId": { "type": "string", "example": "DOC-551920" }, "category": { "type": "string", "example": "supporting_evidence" }, "linkedAt": { "type": "string", "format": "date-time" } } } } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Caller lacks the required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth 2.0 client credentials for system-to-system calls. Agency deployments federate with the agency identity provider (PIV/CAC-backed for user-delegated access).", "flows": { "clientCredentials": { "tokenUrl": "https://dev.ironbrick.us/oauth/token", "scopes": { "cases:read": "Read case records and history", "cases:write": "Update case status and notes" } } } } }, "headers": { "X-Request-Id": { "description": "Unique request identifier; include it when contacting support.", "schema": { "type": "string", "format": "uuid" } } }, "schemas": { "Error": { "type": "object", "required": [ "code", "message", "requestId" ], "properties": { "code": { "type": "string", "example": "validation_error" }, "message": { "type": "string", "example": "status must be one of: received, in_review, decided, closed" }, "requestId": { "type": "string", "format": "uuid", "example": "3f1c9a52-7c1e-4f3e-9d2a-0b8e5f6a1c44" }, "details": { "type": "array", "items": { "type": "object" } } } }, "Page": { "type": "object", "properties": { "nextCursor": { "type": "string", "nullable": true, "example": "eyJvZmZzZXQiOjUwfQ" }, "limit": { "type": "integer", "example": 50 } } }, "Case": { "type": "object", "required": [ "caseId", "caseType", "status", "receivedDate" ], "properties": { "caseId": { "type": "string", "example": "CASE-2026-004817" }, "caseType": { "type": "string", "example": "benefit_request" }, "status": { "type": "string", "enum": [ "received", "in_review", "rfe_issued", "decided", "closed" ], "example": "in_review" }, "priority": { "type": "string", "enum": [ "standard", "expedited" ], "example": "standard" }, "receivedDate": { "type": "string", "format": "date", "example": "2026-08-14" }, "office": { "type": "string", "example": "Field Office 12" }, "assignedTo": { "type": "string", "nullable": true, "example": "adjudicator-0442" }, "partyIds": { "type": "array", "items": { "type": "string" }, "example": [ "PTY-88120" ] }, "lastUpdated": { "type": "string", "format": "date-time", "example": "2026-09-30T14:22:05Z" }, "version": { "type": "integer", "description": "Optimistic-concurrency version; send in If-Match when updating.", "example": 7 } } }, "CaseEvent": { "type": "object", "properties": { "eventId": { "type": "string", "example": "EVT-77311" }, "caseId": { "type": "string", "example": "CASE-2026-004817" }, "type": { "type": "string", "enum": [ "status_changed", "note_added", "document_linked", "assigned" ], "example": "status_changed" }, "from": { "type": "string", "nullable": true, "example": "received" }, "to": { "type": "string", "nullable": true, "example": "in_review" }, "actor": { "type": "string", "example": "adjudicator-0442" }, "occurredAt": { "type": "string", "format": "date-time", "example": "2026-09-30T14:22:05Z" } } } } } }