Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

08.01 API Overview

SimpleRisk's REST API exposes the platform's data and most operations as HTTP endpoints. v2 is the active surface where new endpoints land; v1 is frozen for backward compatibility. Authentication is per-user API keys via X-API-KEY header; permissions inherit from the user. OpenAPI documentation is in-product at /api/v2/documentation.php.

Why this matters

Every program eventually wants programmatic access. A weekly script that imports vendor risks from a spreadsheet, a CI pipeline that closes risks when their fix ships, a custom dashboard that renders the register for executives, a mobile app that lets approvers act from their phone — all integration patterns route through the API. The API is what makes SimpleRisk a platform rather than a destination application.

This article is the conceptual overview. For specific tasks, see the cross-references at the end of each section.

What the API exposes

The v2 API surface covers the major SimpleRisk entities and their workflows:

  • Risks — list, create, read, update, delete, plus risk-specific operations (submit, review, mitigate, close, comment).
  • Mitigations — read and write the mitigation tab data on a risk.
  • Governance — frameworks, controls, documents, exceptions.
  • Compliance — control tests, audits, audit cycles.
  • Assets — asset CRUD; integrates with the Asset Management Extra.
  • Admin — limited surface for administrative operations.
  • AI — endpoints exposed by the AI Extra (when active).
  • Reporting — read-only access to report data.
  • Security — auth-related endpoints (test, validate).
  • UI helpers — endpoints that support the web UI but are also useful for integrations.

Not everything in the UI has an API equivalent. Some configuration changes, certain bulk-operation flows, and Extra-specific surfaces (the AI processing flow, certain framework-installer operations) are UI-only or Extra-internal. For the substantial majority of integration use cases, the available endpoints suffice; for gaps, file a feature request.

Versions: v2 active, v1 frozen

SimpleRisk has two API versions:

  • v2 (/api/v2/...) is the active surface. New endpoints land here; existing endpoints are maintained and improved.
  • v1 (/api/v1/...) is frozen. No new endpoints. Existing v1 endpoints remain for backward compatibility with customer integrations built before v2 existed.
  • An unversioned dispatcher (/api/...) exists as a transitional fallback that routes to v2 when v1 is disabled.

For all new development: always use /api/v2/... explicitly. Don't use the unversioned form (it's a backward-compatibility affordance, not a recommended path), and don't use v1 (it's frozen and gated behind an admin setting that defaults to off).

The v1 toggle (api_v1) defaults to false on fresh installs. Programs that need v1 for existing customer integrations explicitly enable it; programs starting fresh leave it off.

Authentication: per-user API keys

The API authenticates with a per-user API key. Each user can have one active key; keys are generated, rotated, and revoked from User Management or the user's own profile.

Pass the key as an X-API-KEY header:

curl -H "X-API-KEY: 
  
   " https://your-simplerisk.example.com/api/v2/risks

The key inherits the user's full permission set and team membership. There's no scope-limiting on the key itself; the user account is the unit of permission. For integration accounts, create a dedicated SimpleRisk user with exactly the permissions the integration needs and generate the key for that user.

For details, see Authentication and API Keys and API Key Management.

Permissions: inherited from the user

Every API request runs as the user the key belongs to. The permission checks are the same as for that user logging into the UI: if the user can do X via the UI, they can do X via the API; if they can't, the API returns 403.

This means API integration permissions are managed via SimpleRisk user permissions, not via separate API permissions. To restrict an integration's capabilities, restrict the user's permissions; to broaden them, broaden the user's.

For the model details, see Permissions and the API and The Permission Model.

Rate limiting: none native

The v2 API has no native rate limiting. Integrations can call as fast as they want, bounded only by application performance. For programs that need enforced limits (audit requirements, integrations of unknown trust, regulatory obligations), the standard pattern is a reverse proxy (nginx, HAProxy, AWS ALB, Cloudflare) in front of SimpleRisk that enforces per-IP or per-key limits before requests reach the application.

For details, see Rate Limiting and Quotas.

Pagination: minimal native support

Most list endpoints return all matching records in one response. For large registers (tens of thousands of risks), this means large response payloads. Mitigation strategies:

  • Filter at the source via query parameters (status, team, owner, etc.).
  • Cache locally and re-fetch on a schedule.
  • Use per-record endpoints (GET /api/v2/risks/{id}) when you know the ID.

If pagination is added to specific endpoints in future versions, response shapes will gain pagination fields (next_page_token, etc.). Integrations should handle both shapes.

Response format: JSON wrapper

API responses are JSON wrapped in:

{
  "status_code": 200,
  "status_message": "OK",
  "data": { ... }
}

status_code mirrors the HTTP status; status_message is a short human-readable description; data contains the actual payload. Integrations should check status_code (or HTTP status) before processing data.

OpenAPI documentation

The API is documented via OpenAPI annotations in the codebase, rendered as Swagger UI at /api/v2/documentation.php. The Swagger UI is the canonical reference for endpoint shapes, parameters, and response formats; it's auto-generated from the running install's annotations and is always in sync.

For programs that prefer Postman over Swagger, the documentation can be exported as a Postman collection; see Using the Postman Collection.

What the API doesn't do

A few honest limitations:

  • No outbound webhooks — SimpleRisk doesn't POST to external URLs on its own events. The Jira Extra is the only inbound webhook; for outbound, see Webhook Integration.
  • No SCIM / SCIM-2.0 user provisioning — bulk user provisioning is via the API's user-management endpoints, not via SCIM.
  • No GraphQL — REST/JSON only.
  • No streaming endpoints — list endpoints return full result sets; there's no SSE or chunked-streaming surface.
  • No bulk-operation transactions — multi-record operations are typically per-record API calls; failures don't roll back prior calls.

Common patterns

The integration-pattern library:

  • Polling: a script reads the API on a schedule, dispatches changes to a downstream system. See Webhook Integration and Building a Script Against the API.
  • Bulk import: a one-shot or recurring script reads from an external source, calls POST endpoints to create records.
  • Custom UI: a custom dashboard reads from multiple endpoints, renders in a non-SimpleRisk UI for specific stakeholders.
  • Mobile/desktop client: a native app reads and writes via the API; users authenticate with their own keys.
  • CI/CD integration: pipelines update risks via PATCH calls when their fixes ship.
  • Workflow automation: tools like Zapier, Make.com, n8n connect SimpleRisk to other SaaS systems via the API.

Where to learn more

Related