{ "components": { "securitySchemes": { "bearerAuth": { "bearerFormat": "JWT", "scheme": "bearer", "type": "http" } } }, "info": { "description": "REST API for the LimaCharlie SOC cases extension. Provides case CRUD, dashboard counts, SOC reporting, and org configuration.", "title": "LimaCharlie Cases API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/api/v1/assignees": { "get": { "description": "Returns a sorted list of unique assignee emails observed on cases across all accessible orgs (or specific OIDs). Only users who have been assigned at least one case are included. Requires investigation.get permission.", "operationId": "listAssignees", "parameters": [ { "description": "Comma-separated organization IDs (optional, defaults to all accessible)", "in": "query", "name": "oids", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "assignees": { "items": { "type": "string" }, "type": "array" } }, "required": [ "assignees" ], "type": "object" } } }, "description": "Sorted unique list of assignee emails" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "List assignees", "tags": [ "Cases" ] } }, "/api/v1/cases": { "get": { "description": "Cross-org case listing. Returns cases from all requested OIDs the user has access to. Requires investigation.get permission.", "operationId": "listCases", "parameters": [ { "description": "Comma-separated organization IDs to query", "in": "query", "name": "oids", "required": true, "schema": { "type": "string" } }, { "description": "Filter by status (comma-separated): new, in_progress, resolved, closed", "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "description": "Filter by severity (comma-separated): critical, high, medium, low, info", "in": "query", "name": "severity", "required": false, "schema": { "type": "string" } }, { "description": "Filter by classification (comma-separated): pending, true_positive, false_positive", "in": "query", "name": "classification", "required": false, "schema": { "type": "string" } }, { "description": "Filter by assignee email (matches any entry in the assignees array)", "in": "query", "name": "assignee", "required": false, "schema": { "type": "string" } }, { "description": "Search in detection_cat and hostname across linked detections", "in": "query", "name": "search", "required": false, "schema": { "type": "string" } }, { "description": "Filter to cases with any detection from this sensor ID", "in": "query", "name": "sid", "required": false, "schema": { "type": "string" } }, { "description": "Filter by tags (comma-separated, AND logic — cases must have ALL specified tags)", "in": "query", "name": "tag", "required": false, "schema": { "type": "string" } }, { "description": "Sort field: created_at (default), severity, case_number", "in": "query", "name": "sort", "required": false, "schema": { "type": "string" } }, { "description": "Sort order: desc (default) or asc", "in": "query", "name": "order", "required": false, "schema": { "type": "string" } }, { "description": "Results per page (default 50, max 200)", "in": "query", "name": "page_size", "required": false, "schema": { "type": "integer" } }, { "description": "Cursor for next page", "in": "query", "name": "page_token", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cases": { "items": { "properties": { "acknowledged_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "assignees": { "items": { "type": "string" }, "type": "array" }, "case_id": { "type": "string" }, "case_number": { "type": "integer" }, "classification": { "enum": [ "pending", "true_positive", "false_positive" ] }, "closed_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "conclusion": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "detection_cats": { "items": { "type": "string" }, "type": "array" }, "detection_count": { "type": "integer" }, "group_key": { "type": "string" }, "last_updated_at": { "format": "date-time", "type": "string" }, "last_updated_by": { "type": "string" }, "merged_into_case_id": { "type": "string" }, "oid": { "type": "string" }, "resolved_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "severity": { "enum": [ "critical", "high", "medium", "low", "info" ] }, "sids": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "new", "in_progress", "resolved", "closed" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "tta_seconds": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "ttr_seconds": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "oid", "case_id", "case_number", "status", "severity", "classification", "created_at" ], "type": "object" }, "type": "array" }, "next_page_token": { "type": "string" }, "total_counts": { "additionalProperties": { "type": "integer" }, "type": "object" } }, "required": [ "cases" ], "type": "object" } } }, "description": "Case listing with pagination and counts" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "List cases", "tags": [ "Cases" ] } }, "/api/v1/cases/bulk-update": { "post": { "description": "Batch update multiple cases in one org. Useful for shift handoff or bulk acknowledge. Requires investigation.set permission.", "operationId": "bulkUpdateCases", "requestBody": { "content": { "application/json": { "schema": { "properties": { "case_numbers": { "items": { "type": "integer" }, "type": "array" }, "oid": { "type": "string" }, "update": { "properties": { "classification": { "enum": [ "pending", "true_positive", "false_positive" ] }, "status": { "enum": [ "new", "in_progress", "resolved", "closed" ] } }, "type": "object" } }, "required": [ "oid", "case_numbers", "update" ], "type": "object" } } }, "description": "Bulk update payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "failed": { "type": "integer" }, "updated": { "type": "integer" } }, "required": [ "updated", "failed" ], "type": "object" } } }, "description": "Bulk update results" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "Bulk update cases", "tags": [ "Cases" ] } }, "/api/v1/cases/merge": { "post": { "description": "Merge source cases into a target c. Source cases are closed with merged_into_case_id set. Requires investigation.set permission.", "operationId": "mergeCases", "requestBody": { "content": { "application/json": { "schema": { "properties": { "oid": { "type": "string" }, "source_case_numbers": { "items": { "type": "integer" }, "type": "array" }, "target_case_number": { "type": "integer" } }, "required": [ "oid", "target_case_number", "source_case_numbers" ], "type": "object" } } }, "description": "Merge payload", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "case": { "properties": { "acknowledged_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "assignees": { "items": { "type": "string" }, "type": "array" }, "case_id": { "type": "string" }, "case_number": { "type": "integer" }, "classification": { "enum": [ "pending", "true_positive", "false_positive" ] }, "closed_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "conclusion": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "detection_cats": { "items": { "type": "string" }, "type": "array" }, "detection_count": { "type": "integer" }, "group_key": { "type": "string" }, "last_updated_at": { "format": "date-time", "type": "string" }, "last_updated_by": { "type": "string" }, "merged_into_case_id": { "type": "string" }, "oid": { "type": "string" }, "resolved_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "severity": { "enum": [ "critical", "high", "medium", "low", "info" ] }, "sids": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "new", "in_progress", "resolved", "closed" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "tta_seconds": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "ttr_seconds": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "oid", "case_id", "case_number", "status", "severity", "classification", "created_at" ], "type": "object" }, "events": { "items": { "properties": { "case_id": { "type": "string" }, "event_at": { "format": "date-time", "type": "string" }, "event_by": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "oid": { "type": "string" } }, "required": [ "event_id", "event_type", "event_at", "event_by" ], "type": "object" }, "type": "array" } }, "required": [ "case", "events" ], "type": "object" } } }, "description": "Target case after merge with events" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid merge request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Case not found" } }, "summary": "Merge cases", "tags": [ "Cases" ] } }, "/api/v1/cases/{caseNumber}": { "get": { "description": "Returns a single case with its full event timeline. Requires investigation.get permission.", "operationId": "getCase", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "case": { "properties": { "acknowledged_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "assignees": { "items": { "type": "string" }, "type": "array" }, "case_id": { "type": "string" }, "case_number": { "type": "integer" }, "classification": { "enum": [ "pending", "true_positive", "false_positive" ] }, "closed_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "conclusion": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "detection_cats": { "items": { "type": "string" }, "type": "array" }, "detection_count": { "type": "integer" }, "group_key": { "type": "string" }, "last_updated_at": { "format": "date-time", "type": "string" }, "last_updated_by": { "type": "string" }, "merged_into_case_id": { "type": "string" }, "oid": { "type": "string" }, "resolved_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "severity": { "enum": [ "critical", "high", "medium", "low", "info" ] }, "sids": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "new", "in_progress", "resolved", "closed" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "tta_seconds": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "ttr_seconds": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "oid", "case_id", "case_number", "status", "severity", "classification", "created_at" ], "type": "object" }, "events": { "items": { "properties": { "case_id": { "type": "string" }, "event_at": { "format": "date-time", "type": "string" }, "event_by": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "oid": { "type": "string" } }, "required": [ "event_id", "event_type", "event_at", "event_by" ], "type": "object" }, "type": "array" } }, "required": [ "case", "events" ], "type": "object" } } }, "description": "Case with event timeline" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Case not found" } }, "summary": "Get case", "tags": [ "Cases" ] }, "patch": { "description": "Update case fields: status, assignees, classification. Status transitions are validated against the state machine. Requires investigation.set permission.", "operationId": "updateCase", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "assignees": { "items": { "type": "string" }, "type": "array" }, "classification": { "enum": [ "pending", "true_positive", "false_positive" ] }, "conclusion": { "type": "string" }, "status": { "enum": [ "new", "in_progress", "resolved", "closed" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "Case update fields (all optional)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "case": { "properties": { "acknowledged_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "assignees": { "items": { "type": "string" }, "type": "array" }, "case_id": { "type": "string" }, "case_number": { "type": "integer" }, "classification": { "enum": [ "pending", "true_positive", "false_positive" ] }, "closed_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "conclusion": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "detection_cats": { "items": { "type": "string" }, "type": "array" }, "detection_count": { "type": "integer" }, "group_key": { "type": "string" }, "last_updated_at": { "format": "date-time", "type": "string" }, "last_updated_by": { "type": "string" }, "merged_into_case_id": { "type": "string" }, "oid": { "type": "string" }, "resolved_at": { "oneOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "severity": { "enum": [ "critical", "high", "medium", "low", "info" ] }, "sids": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "new", "in_progress", "resolved", "closed" ] }, "summary": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "tta_seconds": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "ttr_seconds": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "oid", "case_id", "case_number", "status", "severity", "classification", "created_at" ], "type": "object" }, "events": { "items": { "properties": { "case_id": { "type": "string" }, "event_at": { "format": "date-time", "type": "string" }, "event_by": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "oid": { "type": "string" } }, "required": [ "event_id", "event_type", "event_at", "event_by" ], "type": "object" }, "type": "array" } }, "required": [ "case", "events" ], "type": "object" } } }, "description": "Updated case with events" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request or transition" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Case not found" } }, "summary": "Update case", "tags": [ "Cases" ] } }, "/api/v1/cases/{caseNumber}/artifacts": { "get": { "description": "Returns all artifact references for a case. Requires investigation.get permission.", "operationId": "listArtifacts", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "artifacts": { "items": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "added_by": { "type": "string" }, "artifact_id": { "type": "string" }, "artifact_type": { "type": "string" }, "note": { "type": "string" }, "oid": { "type": "string" }, "path": { "type": "string" }, "sid": { "type": "string" }, "source": { "type": "string" }, "ts": { "format": "date-time", "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "artifact_id", "ts", "path", "source" ], "type": "object" }, "type": "array" } }, "required": [ "artifacts" ], "type": "object" } } }, "description": "List of artifact references" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "List artifacts", "tags": [ "Investigation" ] }, "post": { "description": "Attach a forensic artifact reference to a case. Requires investigation.set permission.", "operationId": "addArtifact", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "artifact_type": { "type": "string" }, "note": { "type": "string" }, "path": { "type": "string" }, "source": { "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "path", "source" ], "type": "object" } } }, "description": "Artifact to add", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "artifact": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "added_by": { "type": "string" }, "artifact_id": { "type": "string" }, "artifact_type": { "type": "string" }, "note": { "type": "string" }, "oid": { "type": "string" }, "path": { "type": "string" }, "sid": { "type": "string" }, "source": { "type": "string" }, "ts": { "format": "date-time", "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "artifact_id", "ts", "path", "source" ], "type": "object" } }, "required": [ "artifact" ], "type": "object" } } }, "description": "Created artifact reference" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "Add artifact", "tags": [ "Investigation" ] } }, "/api/v1/cases/{caseNumber}/artifacts/{artifactID}": { "delete": { "description": "Remove an artifact reference from a case. Requires investigation.set permission.", "operationId": "removeArtifact", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Artifact UUID", "in": "path", "name": "artifactID", "required": true, "schema": { "type": "string" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "type": "boolean" } }, "type": "object" } } }, "description": "Artifact removed" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Artifact not found" } }, "summary": "Remove artifact", "tags": [ "Investigation" ] } }, "/api/v1/cases/{caseNumber}/detections": { "get": { "description": "Returns all detections linked to a case. Requires investigation.get permission.", "operationId": "getCaseDetections", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "detections": { "items": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "added_by": { "type": "string" }, "detect_id": { "type": "string" }, "detection_cat": { "type": "string" }, "detection_priority": { "type": "integer" }, "detection_source": { "type": "string" }, "hostname": { "type": "string" }, "note": { "type": "string" }, "oid": { "type": "string" }, "sid": { "type": "string" }, "ts": { "format": "date-time", "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "detect_id", "ts" ], "type": "object" }, "type": "array" } }, "required": [ "detections" ], "type": "object" } } }, "description": "List of linked detections" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "Get case detections", "tags": [ "Cases" ] }, "post": { "description": "Manually link a detection to a case. Returns 409 if the detection is already linked to a case in this org. Requires investigation.set permission.", "operationId": "addDetection", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "detection": { "type": "object" } }, "required": [ "detection" ], "type": "object" } } }, "description": "Detection to link", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "detection": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "added_by": { "type": "string" }, "detect_id": { "type": "string" }, "detection_cat": { "type": "string" }, "detection_priority": { "type": "integer" }, "detection_source": { "type": "string" }, "hostname": { "type": "string" }, "note": { "type": "string" }, "oid": { "type": "string" }, "sid": { "type": "string" }, "ts": { "format": "date-time", "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "detect_id", "ts" ], "type": "object" } }, "required": [ "detection" ], "type": "object" } } }, "description": "Linked detection" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Case not found" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Detection already linked" } }, "summary": "Add detection", "tags": [ "Investigation" ] } }, "/api/v1/cases/{caseNumber}/detections/{detectionID}": { "delete": { "description": "Unlink a detection from a case. Requires investigation.set permission.", "operationId": "removeDetection", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Detection ID", "in": "path", "name": "detectionID", "required": true, "schema": { "type": "string" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "type": "boolean" } }, "type": "object" } } }, "description": "Detection removed" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Detection not found" } }, "summary": "Remove detection", "tags": [ "Investigation" ] } }, "/api/v1/cases/{caseNumber}/entities": { "get": { "description": "Returns all entities/IOCs for a case. Requires investigation.get permission.", "operationId": "listEntities", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "entities": { "items": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "added_by": { "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "enum": [ "ip", "domain", "hash", "url", "user", "email", "file", "process", "registry", "other" ] }, "entity_value": { "type": "string" }, "note": { "type": "string" }, "oid": { "type": "string" }, "sid": { "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "entity_id", "entity_type", "entity_value" ], "type": "object" }, "type": "array" } }, "required": [ "entities" ], "type": "object" } } }, "description": "List of entities" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "List entities", "tags": [ "Investigation" ] }, "post": { "description": "Add an IOC/entity to a case. Requires investigation.set permission.", "operationId": "addEntity", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "entity_type": { "enum": [ "ip", "domain", "hash", "url", "user", "email", "file", "process", "registry", "other" ] }, "entity_value": { "type": "string" }, "note": { "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "entity_type", "entity_value" ], "type": "object" } } }, "description": "Entity to add", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "entity": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "added_by": { "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "enum": [ "ip", "domain", "hash", "url", "user", "email", "file", "process", "registry", "other" ] }, "entity_value": { "type": "string" }, "note": { "type": "string" }, "oid": { "type": "string" }, "sid": { "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "entity_id", "entity_type", "entity_value" ], "type": "object" } }, "required": [ "entity" ], "type": "object" } } }, "description": "Created entity" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Duplicate entity" } }, "summary": "Add entity", "tags": [ "Investigation" ] } }, "/api/v1/cases/{caseNumber}/entities/{entityID}": { "delete": { "description": "Remove an entity from a case. Requires investigation.set permission.", "operationId": "removeEntity", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Entity UUID", "in": "path", "name": "entityID", "required": true, "schema": { "type": "string" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "type": "boolean" } }, "type": "object" } } }, "description": "Entity removed" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Entity not found" } }, "summary": "Remove entity", "tags": [ "Investigation" ] }, "patch": { "description": "Update an entity's verdict, context, or other mutable fields. Requires investigation.set permission.", "operationId": "updateEntity", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Entity UUID", "in": "path", "name": "entityID", "required": true, "schema": { "type": "string" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "note": { "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "type": "object" } } }, "description": "Entity update fields", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "entity": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "added_by": { "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "enum": [ "ip", "domain", "hash", "url", "user", "email", "file", "process", "registry", "other" ] }, "entity_value": { "type": "string" }, "note": { "type": "string" }, "oid": { "type": "string" }, "sid": { "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "entity_id", "entity_type", "entity_value" ], "type": "object" } }, "required": [ "entity" ], "type": "object" } } }, "description": "Updated entity" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Entity not found" } }, "summary": "Update entity", "tags": [ "Investigation" ] } }, "/api/v1/cases/{caseNumber}/notes": { "post": { "description": "Add a free-text note to a case's event timeline. Requires investigation.set permission.", "operationId": "addNote", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "content": { "maxLength": 8192, "type": "string" }, "is_public": { "type": "boolean" }, "note_type": { "enum": [ "general", "analysis", "remediation", "escalation", "handoff", "to_stakeholder", "from_stakeholder" ] } }, "required": [ "content" ], "type": "object" } } }, "description": "Note content", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "event": { "properties": { "case_id": { "type": "string" }, "event_at": { "format": "date-time", "type": "string" }, "event_by": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "oid": { "type": "string" } }, "required": [ "event_id", "event_type", "event_at", "event_by" ], "type": "object" } }, "required": [ "event" ], "type": "object" } } }, "description": "Created note event" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "Add note", "tags": [ "Cases" ] } }, "/api/v1/cases/{caseNumber}/notes/{eventID}": { "patch": { "description": "Update note properties (e.g. public visibility). Requires investigation.set permission.", "operationId": "updateNote", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Event ID of the note", "in": "path", "name": "eventID", "required": true, "schema": { "type": "string" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "is_public": { "type": "boolean" } }, "type": "object" } } }, "description": "Note update", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "event": { "properties": { "case_id": { "type": "string" }, "event_at": { "format": "date-time", "type": "string" }, "event_by": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string" }, "metadata": { "additionalProperties": true, "type": "object" }, "oid": { "type": "string" } }, "required": [ "event_id", "event_type", "event_at", "event_by" ], "type": "object" } }, "required": [ "event" ], "type": "object" } } }, "description": "Updated note event" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Note not found" } }, "summary": "Update note", "tags": [ "Cases" ] } }, "/api/v1/cases/{caseNumber}/telemetry": { "get": { "description": "Returns all telemetry event references for a case. Requires investigation.get permission.", "operationId": "listTelemetry", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "telemetry": { "items": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "added_by": { "type": "string" }, "atom": { "type": "string" }, "event_type": { "type": "string" }, "note": { "type": "string" }, "oid": { "type": "string" }, "sid": { "type": "string" }, "telemetry_id": { "type": "string" }, "ts": { "format": "date-time", "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "telemetry_id", "ts", "atom" ], "type": "object" }, "type": "array" } }, "required": [ "telemetry" ], "type": "object" } } }, "description": "List of telemetry references" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "List telemetry", "tags": [ "Investigation" ] }, "post": { "description": "Attach an LC telemetry event reference to a case. Requires investigation.set permission.", "operationId": "addTelemetry", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "event": { "type": "object" }, "note": { "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "event" ], "type": "object" } } }, "description": "Telemetry event to add", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "telemetry": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "added_by": { "type": "string" }, "atom": { "type": "string" }, "event_type": { "type": "string" }, "note": { "type": "string" }, "oid": { "type": "string" }, "sid": { "type": "string" }, "telemetry_id": { "type": "string" }, "ts": { "format": "date-time", "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "telemetry_id", "ts", "atom" ], "type": "object" } }, "required": [ "telemetry" ], "type": "object" } } }, "description": "Created telemetry reference" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "Add telemetry", "tags": [ "Investigation" ] } }, "/api/v1/cases/{caseNumber}/telemetry/{telemetryID}": { "delete": { "description": "Remove a telemetry reference from a case. Requires investigation.set permission.", "operationId": "removeTelemetry", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Telemetry UUID", "in": "path", "name": "telemetryID", "required": true, "schema": { "type": "string" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "deleted": { "type": "boolean" } }, "type": "object" } } }, "description": "Telemetry removed" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Telemetry not found" } }, "summary": "Remove telemetry", "tags": [ "Investigation" ] }, "patch": { "description": "Update a telemetry reference's verdict, summary, or relevance. Requires investigation.set permission.", "operationId": "updateTelemetry", "parameters": [ { "description": "Case number (per-org integer)", "in": "path", "name": "caseNumber", "required": true, "schema": { "type": "integer" } }, { "description": "Telemetry UUID", "in": "path", "name": "telemetryID", "required": true, "schema": { "type": "string" } }, { "description": "Organization ID", "in": "query", "name": "oid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "note": { "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "type": "object" } } }, "description": "Telemetry update fields", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "telemetry": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "added_by": { "type": "string" }, "atom": { "type": "string" }, "event_type": { "type": "string" }, "note": { "type": "string" }, "oid": { "type": "string" }, "sid": { "type": "string" }, "telemetry_id": { "type": "string" }, "ts": { "format": "date-time", "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "telemetry_id", "ts", "atom" ], "type": "object" } }, "required": [ "telemetry" ], "type": "object" } } }, "description": "Updated telemetry reference" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Telemetry not found" } }, "summary": "Update telemetry", "tags": [ "Investigation" ] } }, "/api/v1/config/{oid}": { "get": { "description": "Returns the cases configuration for an organization. Requires org.conf.get permission.", "operationId": "getConfig", "parameters": [ { "description": "Organization ID", "in": "path", "name": "oid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "auto_close_resolved_after_days": { "type": "integer" }, "auto_grouping_enabled": { "type": "boolean" }, "retention_days": { "type": "integer" }, "severity_mapping": { "properties": { "critical_min": { "type": "integer" }, "high_min": { "type": "integer" }, "medium_min": { "type": "integer" } }, "required": [ "critical_min", "high_min", "medium_min" ], "type": "object" }, "sla_config": { "properties": { "critical": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "high": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "info": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "low": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "medium": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" } }, "type": "object" } }, "required": [ "severity_mapping", "retention_days", "auto_close_resolved_after_days" ], "type": "object" } } }, "description": "Tenant configuration" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "No access to org" } }, "summary": "Get org config", "tags": [ "Configuration" ] }, "put": { "description": "Updates the cases configuration for an organization. Requires org.conf.set permission.", "operationId": "updateConfig", "parameters": [ { "description": "Organization ID", "in": "path", "name": "oid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "auto_close_resolved_after_days": { "type": "integer" }, "auto_grouping_enabled": { "type": "boolean" }, "retention_days": { "type": "integer" }, "severity_mapping": { "properties": { "critical_min": { "type": "integer" }, "high_min": { "type": "integer" }, "medium_min": { "type": "integer" } }, "required": [ "critical_min", "high_min", "medium_min" ], "type": "object" }, "sla_config": { "properties": { "critical": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "high": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "info": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "low": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "medium": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" } }, "type": "object" } }, "required": [ "severity_mapping", "retention_days", "auto_close_resolved_after_days" ], "type": "object" } } }, "description": "Updated configuration", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "auto_close_resolved_after_days": { "type": "integer" }, "auto_grouping_enabled": { "type": "boolean" }, "retention_days": { "type": "integer" }, "severity_mapping": { "properties": { "critical_min": { "type": "integer" }, "high_min": { "type": "integer" }, "medium_min": { "type": "integer" } }, "required": [ "critical_min", "high_min", "medium_min" ], "type": "object" }, "sla_config": { "properties": { "critical": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "high": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "info": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "low": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" }, "medium": { "properties": { "mtta_minutes": { "type": "integer" }, "mttr_minutes": { "type": "integer" } }, "required": [ "mtta_minutes", "mttr_minutes" ], "type": "object" } }, "type": "object" } }, "required": [ "severity_mapping", "retention_days", "auto_close_resolved_after_days" ], "type": "object" } } }, "description": "Updated configuration" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid configuration" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "No access to org" } }, "summary": "Update org config", "tags": [ "Configuration" ] } }, "/api/v1/dashboard/counts": { "get": { "description": "Real-time case counts per org for dashboard widgets. Queries Spanner directly for speed. Requires investigation.get permission.", "operationId": "getDashboardCounts", "parameters": [ { "description": "Comma-separated organization IDs", "in": "query", "name": "oids", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "by_org": { "additionalProperties": { "properties": { "severity_counts": { "additionalProperties": { "additionalProperties": { "type": "integer" }, "type": "object" }, "type": "object" }, "status_counts": { "additionalProperties": { "type": "integer" }, "type": "object" } }, "type": "object" }, "type": "object" }, "totals": { "additionalProperties": { "type": "integer" }, "type": "object" } }, "type": "object" } } }, "description": "Dashboard counts by org and totals" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "Get dashboard counts", "tags": [ "Dashboard" ] } }, "/api/v1/entities/search": { "get": { "description": "Search for entities/IOCs across cases in accessible orgs. Results are dynamically filtered by the caller's permissions. Requires investigation.get permission.", "operationId": "searchEntities", "parameters": [ { "description": "Entity type to search for", "in": "query", "name": "entity_type", "required": true, "schema": { "enum": [ "ip", "domain", "hash", "url", "user", "email", "file", "process", "registry", "other" ] } }, { "description": "Entity value to search for", "in": "query", "name": "entity_value", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated organization IDs (optional, defaults to all accessible)", "in": "query", "name": "oids", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "results": { "items": { "properties": { "case_number": { "type": "integer" }, "case_status": { "enum": [ "new", "in_progress", "resolved", "closed" ] }, "entity": { "properties": { "added_at": { "format": "date-time", "type": "string" }, "added_by": { "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "enum": [ "ip", "domain", "hash", "url", "user", "email", "file", "process", "registry", "other" ] }, "entity_value": { "type": "string" }, "note": { "type": "string" }, "oid": { "type": "string" }, "sid": { "type": "string" }, "verdict": { "enum": [ "malicious", "suspicious", "benign", "unknown", "informational" ] } }, "required": [ "entity_id", "entity_type", "entity_value" ], "type": "object" }, "oid": { "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "results" ], "type": "object" } } }, "description": "Search results with case context" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "Search entities", "tags": [ "Investigation" ] } }, "/api/v1/reports/summary": { "get": { "description": "Returns SOC metrics (MTTA, MTTR, classification rates, volume) for the given orgs and date range. Requires investigation.get permission.", "operationId": "getReportSummary", "parameters": [ { "description": "Comma-separated organization IDs", "in": "query", "name": "oids", "required": true, "schema": { "type": "string" } }, { "description": "Start of date range (RFC 3339)", "in": "query", "name": "from", "required": true, "schema": { "format": "date-time", "type": "string" } }, { "description": "End of date range (RFC 3339)", "in": "query", "name": "to", "required": true, "schema": { "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "period": { "properties": { "from": { "format": "date-time", "type": "string" }, "to": { "format": "date-time", "type": "string" } }, "type": "object" }, "summary": { "additionalProperties": true, "type": "object" } }, "type": "object" } } }, "description": "Summary report with per-org and aggregate metrics" }, "400": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Invalid request parameters" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "Get report summary", "tags": [ "Reports" ] } }, "/api/v1/tags": { "get": { "description": "Returns a sorted list of unique tags observed on cases across all accessible orgs (or specific OIDs). Requires investigation.get permission.", "operationId": "listTags", "parameters": [ { "description": "Comma-separated organization IDs (optional, defaults to all accessible)", "in": "query", "name": "oids", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "tags": { "items": { "type": "string" }, "type": "array" } }, "required": [ "tags" ], "type": "object" } } }, "description": "Sorted unique list of tags" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": true, "type": "object" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" } }, "required": [ "error" ], "type": "object" } } }, "description": "Unauthorized" } }, "summary": "List tags", "tags": [ "Cases" ] } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "/" } ], "tags": [ { "name": "Cases" }, { "name": "Configuration" }, { "name": "Dashboard" }, { "name": "Investigation" }, { "name": "Reports" } ] }