REST API Documentation

Complete REST API reference for integrating with StrataGRC platform

✓ RESTful JSON Format Authentication Required
📑 API Sections

API Overview

Base URL

https://your-domain.com/stratagrc/api/

API Format

All API requests and responses use JSON format. The StrataGRC REST API provides programmatic access to all major platform features including risks, controls, audits, findings, investigations, and more.

Available Modules

Risk Management

CRUD operations for risks, risk responses, and risk mapping

Control Library

Manage controls, control testing, and effectiveness tracking

Audit Management

Audit engagements, fieldwork, and audit planning

Investigations

IMS cases, evidence, and investigation management

API Versioning

Current API version: v1 (implicit)
All endpoints follow RESTful conventions with consistent response formats.

Authentication

Session-Based Authentication

The StrataGRC API uses session-based authentication. Users must be logged in to the web application to access API endpoints.

Authentication Requirements
  • Valid user session (logged in to web application)
  • Organization context (user must belong to an organization)
  • Appropriate permissions for the requested operation

Example Request with Authentication

// JavaScript Example (using fetch) fetch('/stratagrc/api/risks.php', { method: 'GET', credentials: 'same-origin', // Include session cookie headers: { 'Content-Type': 'application/json' } }) .then(response => response.json()) .then(data => console.log(data));

Response Codes

CodeMeaningDescription
200 Success Request completed successfully
401 Unauthorized User not logged in or session expired
403 Forbidden User lacks required permissions
404 Not Found Requested resource not found
500 Server Error Internal server error

Core Endpoints

Authentication Status

GET /api/auth.php

Check current authentication status

Response:
{ "authenticated": true, "user_id": 123, "organization_id": 1, "first_name": "John", "permissions": ["risk_view", "control_edit"] }

Dashboard Data

GET /api/get_dashboard_counts.php

Get dashboard KPI counts

Response:
{ "open_findings": 15, "overdue_findings": 3, "active_audits": 5, "avg_risk_score": 12.5 }

Chart Data

GET /api/get_chart_data.php

Get data for dashboard charts

Query Parameters:
  • chart_type - Type of chart data (findings_by_risk, audit_phases, vendors_by_risk)

Risk Management API

List Risks

GET /api/risks.php
Query Parameters:
ParameterTypeDescription
action string Must be list
category string Filter by risk category (optional)
status string Filter by risk status (optional)
Response:
[ { "id": 1, "risk_title": "Data Breach Risk", "risk_category": "Information Security", "inherent_risk_score": 20, "final_score": 12, "risk_status": "In Mitigation" } ]

Create Risk

POST /api/risks.php
Request Body:
{ "action": "create", "risk_title": "New Risk", "risk_description": "Description", "risk_category": "Category", "inherent_impact": 4, "inherent_likelihood": 5 }

Update Risk

PUT /api/risks.php
Request Body:
{ "action": "update", "risk_id": 123, "risk_status": "Monitoring", "final_score": 10 }

Delete Risk

DELETE /api/risks.php
Request Body:
{ "action": "delete", "risk_id": 123 }

Control Library API

List Controls

GET /api/controls.php?action=list
Query Parameters:
ParameterTypeDescription
action string Must be list
framework_id int Filter by framework (optional)
status string Filter by status: Active, Draft, Archived (optional)
Response:
[ { "id": 1, "control_id": "AC-001", "control_title": "Access Review Control", "control_type": "Preventive", "effectiveness_score": 4.2, "status": "Active" } ]

Get Control Details

GET /api/get_control_details.php?id={control_id}
Response:
{ "id": 1, "control_title": "Access Review", "control_description": "Description...", "linked_risks": [5, 12], "testing_history": [...], "effectiveness_score": 4.2 }

Create Control

POST /api/controls.php
Request Body:
{ "action": "create", "control_id": "AC-002", "control_title": "New Control", "control_type": "Detective", "status": "Active" }

Update Control Effectiveness

POST /api/controls.php
Request Body:
{ "action": "calculate_effectiveness", "control_id": 123 }

Audit Management API

List Engagements

GET /api/engagements.php?action=list
Query Parameters:
ParameterTypeDescription
action string Must be list
phase string Filter by phase: Planning, Fieldwork, Review, Reporting, Completed
status string Filter by status (optional)
Response:
[ { "id": 1, "title": "IT General Controls Audit", "phase": "Fieldwork", "start_date": "2025-01-15", "end_date": "2025-03-15", "findings_count": 5 } ]

Get Engagement Details

GET /api/engagements.php?action=get&id={engagement_id}
Response:
{ "id": 1, "title": "IT Audit", "objectives": "...", "scope": "...", "team_members": [...], "findings": [...], "checklist": [...] }

Create Engagement

POST /api/engagements.php
Request Body:
{ "action": "create", "title": "New Audit", "auditable_unit_id": 5, "start_date": "2025-02-01", "end_date": "2025-04-01", "phase": "Planning" }

Update Engagement Phase

PUT /api/engagements.php
Request Body:
{ "action": "update_phase", "engagement_id": 123, "phase": "Fieldwork" }

Findings API

List Findings

GET /api/findings.php?action=list
Query Parameters:
ParameterTypeDescription
action string Must be list
engagement_id int Filter by engagement (optional)
status string Filter by status: Open, Approved, Closed (optional)
assigned_to int Filter by assignee (optional)
Response:
[ { "id": 1, "title": "Access Control Weakness", "risk_score": 15, "status": "Approved", "engagement_id": 3, "assigned_to_id": 5 } ]

Create Finding

POST /api/findings.php
Request Body:
{ "action": "create", "engagement_id": 3, "control_id": 7, "title": "Finding Title", "criteria": "What should be", "condition": "What is", "cause": "Root cause", "implication": "Impact", "recommendation": "Recommendation", "risk_impact": 4, "risk_probability": 5, "assigned_to_id": 5 }

Update Finding Status

PUT /api/findings.php
Request Body:
{ "action": "update_status", "finding_id": 123, "status": "Closed", "review_notes": "Notes..." }

Submit Management Response

POST /api/findings.php
Request Body:
{ "action": "submit_response", "finding_id": 123, "management_response": "Response...", "action_plan": "Plan...", "estimated_completion_date": "2025-06-30" }

Investigations (IMS) API

List Cases

GET /ims/api/cases.php?action=list
Query Parameters:
ParameterTypeDescription
action string Must be list
status string Filter by status: new, assigned, in_progress, review, completed
priority string Filter by priority: low, medium, high, urgent
Response:
[ { "id": 1, "case_number": "INV-2025-0001", "title": "Fraud Investigation", "status": "in_progress", "priority": "high", "assigned_to": 5 } ]

Create Case

POST /ims/api/cases.php
Request Body:
{ "action": "create", "title": "Case Title", "description": "Description...", "complaint_type": "Fraud", "priority": "high", "assigned_to": 5 }

Upload Evidence

POST /ims/api/evidence.php
Request Body (multipart/form-data):
{ "action": "upload", "investigation_id": 123, "evidence_type": "document", "description": "Description...", "file": @/path/to/file.pdf }

KPIs & Strategy API

List KPIs

GET /api/kpis.php?action=list
Response:
[ { "id": 1, "kpi_title": "Customer Satisfaction", "target_value": 85, "actual_value": 82, "variance_percentage": -3.5, "trend_direction": "Down" } ]

Get KPI Performance History

GET /api/get_kpi_performance_history.php?kpi_id={kpi_id}
Response:
[ { "period_date": "2025-01-31", "actual_value": 82, "target_value": 85, "variance": -3 } ]

Submit KPI Performance Data

POST /api/kpis.php
Request Body:
{ "action": "submit_performance", "kpi_id": 123, "period_date": "2025-01-31", "actual_value": 82, "target_value": 85 }

Error Handling

Error Response Format

{ "success": false, "error": "Error message description", "error_code": "ERROR_CODE" }

Common Error Codes

Error CodeMeaningSolution
AUTH_REQUIRED User not authenticated Log in to the application
PERMISSION_DENIED Insufficient permissions Request required permissions from admin
NOT_FOUND Resource not found Check the resource ID
VALIDATION_ERROR Invalid input data Review request parameters
SERVER_ERROR Internal server error Contact support if persists

Best Practices

API Usage Guidelines

Use Proper HTTP Methods

Follow REST conventions:

  • GET: Retrieve data (read-only)
  • POST: Create new resources
  • PUT: Update existing resources
  • DELETE: Remove resources
Handle Errors Gracefully

Always check response status and handle errors:

  • Check HTTP status codes
  • Parse error messages
  • Implement retry logic for transient errors
  • Log errors for debugging
Respect Rate Limits

To ensure fair usage:

  • Limit request frequency
  • Batch operations when possible
  • Cache responses when appropriate
  • Use webhooks for real-time updates (future)
Secure Your Integration

Security best practices:

  • Use HTTPS in production
  • Never expose session tokens
  • Validate all input data
  • Implement proper error handling
Integration Support

For assistance with API integration:
• Review this documentation thoroughly
• Test endpoints using browser or tools like Postman
• Check browser console for error details
• Contact StrataGRC support for complex integrations