API Overview
Understanding programmatic access to Govula data and functionality.
This section is intended for: Technical Team. Unauthorised access is restricted.
Why APIs Exist
The Govula API provides programmatic access to compliance data and functionality. This enables:
- Integration with existing GRC tools and workflows
- Custom dashboards and reporting
- Automated evidence collection from external systems
- Bulk data operations for large-scale implementations
- CI/CD integration for compliance-as-code workflows
Common Integration Use Cases
SIEM/SOAR Integration
Security tools can query compliance status to enrich alerts with compliance context. When an incident affects a system, the integration can identify which controls are impacted.
GRC Platform Sync
Organizations using multiple GRC tools can synchronize data between systems. Control status, evidence, and assessments can flow bidirectionally.
Evidence Automation
Scripts can automatically collect evidence from configuration management tools, cloud providers, and security tools, then upload it to Govula with appropriate control associations.
Executive Dashboards
Business intelligence tools can consume compliance data to build custom executive views integrated with other organizational metrics.
Ticketing Integration
Remediation recommendations can be pushed to ticketing systems (Jira, ServiceNow) for tracking and assignment. Status updates can flow back to update control status.
Read vs. Write Operations
API operations are categorized by their impact on data:
Read Operations
Retrieve data without modification. Safe to call repeatedly.
- List organizations
- Get compliance snapshots
- Retrieve control status
- Download reports
- Query audit log
- List frameworks and controls
Write Operations
Modify data. Require appropriate permissions and audit logging.
- Update control status
- Upload evidence
- Modify applicability decisions
- Create organizations
- Update organizational context
- Approve/reject review items
Authentication
API access is authenticated using API keys. Each key is:
- Scoped to an organization: Keys can only access data for their associated organization
- Permission-bound: Keys are associated with a role that determines what operations are allowed
- Audited: All API calls are logged with the key identifier
- Revocable: Keys can be disabled immediately if compromised
Key Types
API Design Principles
The API follows RESTful conventions for predictability:
- Resource-oriented: Endpoints represent resources (organizations, controls, evidence)
- HTTP methods: GET for read, POST for create, PUT for update, DELETE for remove
- JSON responses: All responses are JSON with consistent structure
- Pagination: List endpoints support pagination for large datasets
- Filtering: Query parameters for filtering and sorting results
Core Endpoints
| Resource | Description | Operations |
|---|---|---|
| /organizations | Organization management | List, Get, Create, Update |
| /frameworks | Framework library | List, Get |
| /controls | Control definitions and status | List, Get, Update |
| /evidence | Evidence management | List, Get, Upload, Delete |
| /compliance | Compliance state and snapshots | Get, Snapshots |
| /reports | Report generation | Generate, Download |
| /audit-log | Audit trail access | List, Query |
Rate Limiting
API requests are rate-limited to ensure fair usage and system stability:
- Standard tier1,000 requests per minute
- Enterprise tier10,000 requests per minute
- Bulk operations100 requests per minute (heavier endpoints)
Error Handling
The API uses standard HTTP status codes with structured error responses:
- 200Successful request
- 201Resource created
- 400Invalid request (validation error)
- 401Authentication required
- 403Permission denied
- 404Resource not found
- 429Rate limit exceeded
- 500Server error