---
title: 08.01 API Overview
description: 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…
---
[Skip to content](https://support.simplerisk.com/kb/08-01-api-overview#main-content)
English
Show submenu for translations
[Customer portal](https://support.simplerisk.com/tickets?hsLang=en)
[](https://www.simplerisk.com/)
Open main navigation
Close main navigation
- English
Show submenu for translations
- [Customer portal](https://support.simplerisk.com/tickets)
- [Contact us](https://www.simplerisk.com/about-us/contact-us)
[Contact us](https://www.simplerisk.com/about-us/contact-us)
How can we help you?
- There are no suggestions because the search field is empty.
1. [SimpleRisk Knowledge Base](https://support.simplerisk.com/kb?hsLang=en)
2. [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en)
3. [08 The API](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#08-the-api)
# 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: {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](https://support.simplerisk.com/kb/08-02-authentication-and-api-keys?hsLang=en) and [API Key Management](https://support.simplerisk.com/kb/04-07-api-key-management?hsLang=en).
## 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](https://support.simplerisk.com/kb/08-03-permissions-and-the-api?hsLang=en) and [The Permission Model](https://support.simplerisk.com/kb/03-02-the-permission-model?hsLang=en).
## 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](https://support.simplerisk.com/kb/08-04-rate-limiting-and-quotas?hsLang=en).
## 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](https://support.simplerisk.com/kb/08-06-using-the-postman-collection?hsLang=en).
## 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](https://support.simplerisk.com/kb/07-03-webhook-integration?hsLang=en).
- **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](https://support.simplerisk.com/kb/07-03-webhook-integration?hsLang=en) and [Building a Script Against the API](https://support.simplerisk.com/kb/08-07-building-a-script-against-the-api?hsLang=en).
- **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
- **Authentication mechanics:** [Authentication and API Keys](https://support.simplerisk.com/kb/08-02-authentication-and-api-keys?hsLang=en)
- **API key lifecycle:** [API Key Management](https://support.simplerisk.com/kb/04-07-api-key-management?hsLang=en)
- **Permissions model:** [Permissions and the API](https://support.simplerisk.com/kb/08-03-permissions-and-the-api?hsLang=en)
- **Rate limiting (or lack thereof):** [Rate Limiting and Quotas](https://support.simplerisk.com/kb/08-04-rate-limiting-and-quotas?hsLang=en)
- **Endpoint reference:** [The OpenAPI Documentation](https://support.simplerisk.com/kb/08-05-the-openapi-documentation?hsLang=en)
- **Postman workflow:** [Using the Postman Collection](https://support.simplerisk.com/kb/08-06-using-the-postman-collection?hsLang=en)
- **Example scripts:** [Building a Script Against the API](https://support.simplerisk.com/kb/08-07-building-a-script-against-the-api?hsLang=en)
- **Integration patterns:** [Using the API for Integrations](https://support.simplerisk.com/kb/07-04-using-the-api-for-integrations?hsLang=en)
## Related
- [Authentication and API Keys](https://support.simplerisk.com/kb/08-02-authentication-and-api-keys?hsLang=en)
- [Permissions and the API](https://support.simplerisk.com/kb/08-03-permissions-and-the-api?hsLang=en)
- [Rate Limiting and Quotas](https://support.simplerisk.com/kb/08-04-rate-limiting-and-quotas?hsLang=en)
- [The OpenAPI Documentation](https://support.simplerisk.com/kb/08-05-the-openapi-documentation?hsLang=en)
- [Using the Postman Collection](https://support.simplerisk.com/kb/08-06-using-the-postman-collection?hsLang=en)
- [Building a Script Against the API](https://support.simplerisk.com/kb/08-07-building-a-script-against-the-api?hsLang=en)
- [API Key Management](https://support.simplerisk.com/kb/04-07-api-key-management?hsLang=en)
- [Using the API for Integrations](https://support.simplerisk.com/kb/07-04-using-the-api-for-integrations?hsLang=en)
- [Webhook Integration](https://support.simplerisk.com/kb/07-03-webhook-integration?hsLang=en)
- [FAQs](https://support.simplerisk.com/kb/faqs?hsLang=en)
- [SimpleRisk Extras](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#main-content)
- [Vulnerability Management Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#vulnerability-management-extra)
- [Team Separation Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#team-separation-extra)
- [Import-Export Extra](https://support.simplerisk.com/kb/simplerisk-extras?hsLang=en#import-export-extra)
- [Administrator Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#main-content)
- [00 About This Guide](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#00-about-this-guide)
- [01 Installation and Deployment](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#01-installation-and-deployment)
- [02 Upgrades and Maintenance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#02-upgrades-and-maintenance)
- [03 Users and Permissions](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#03-users-and-permissions)
- [04 Authentication](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#04-authentication)
- [05 Customization](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#05-customization)
- [06 Configuring Risk and Compliance](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#06-configuring-risk-and-compliance)
- [07 Integrations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#07-integrations)
- [08 The API](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#08-the-api)
- [09 Encryption and Data Security](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#09-encryption-and-data-security)
- [10 Workflows and Automation](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#10-workflows-and-automation)
- [11 Reporting and Auditing](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#11-reporting-and-auditing)
- [12 Operations](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#12-operations)
- [13 Reference](https://support.simplerisk.com/kb/administrator-guide?hsLang=en#13-reference)
- [User Guide](https://support.simplerisk.com/kb/user-guide?hsLang=en#main-content)
- [00 Foundations of GRC](https://support.simplerisk.com/kb/user-guide?hsLang=en#00-foundations-of-grc)
- [01 Risk Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#01-risk-management)
- [02 Compliance Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#02-compliance-management)
- [03 Governance](https://support.simplerisk.com/kb/user-guide?hsLang=en#03-governance)
- [04 Asset and Data Inventory](https://support.simplerisk.com/kb/user-guide?hsLang=en#04-asset-and-data-inventory)
- [05 Threat and Vulnerability Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#05-threat-and-vulnerability-management)
- [06 Assessments](https://support.simplerisk.com/kb/user-guide?hsLang=en#06-assessments)
- [07 Incident Management](https://support.simplerisk.com/kb/user-guide?hsLang=en#07-incident-management)
- [08 Audit and Reporting](https://support.simplerisk.com/kb/user-guide?hsLang=en#08-audit-and-reporting)
- [09 Day-to-Day SimpleRisk](https://support.simplerisk.com/kb/user-guide?hsLang=en#09-day-to-day-simplerisk)
- [10 Continuous Improvement](https://support.simplerisk.com/kb/user-guide?hsLang=en#10-continuous-improvement)
- [SimpleRisk User Guides](https://support.simplerisk.com/kb/simplerisk-user-guides?hsLang=en)
- [Troubleshooting](https://support.simplerisk.com/kb/troubleshooting?hsLang=en)
- [SimpleRisk Hosted](https://support.simplerisk.com/kb/simplerisk-hosted?hsLang=en)
- [How To videos](https://support.simplerisk.com/kb/how-to-videos?hsLang=en)
[](https://www.simplerisk.com)
Copyright © 2026, SimpleRisk, Inc.