REST API and MCP

Manual · Set up data sources · Adapters · Ingest reference

Availability

As of 19 September 2026: The extended domain API, push ingest and new adapters are implemented but are not included in the published customer release v1.25.0. This chapter describes that extension. The OpenAPI specification of an installed instance determines its available operations. Updating this manual does not update the application.

Set up API access

  1. As an administrator, open Settings > API access.
  2. Create a key for each application, with a name, expiry date and required scopes.
  3. Store the key in a secret store or the client's protected environment. It is displayed only once and cannot be retrieved later.
  4. Download your instance's OpenAPI specification and check a read request.

Each key has its own technical user. Changes appear under that identity in the audit log. Revoking a key ends access immediately. Updates do not automatically grant additional scopes to existing keys.

All paths in this chapter refer to your ISMS instance, such as https://isms.example.org, rather than this manual website. The API accepts bearer keys; a browser session cannot replace a key.

$env:ISMS_URL = 'https://isms.example.org'
# ISMS_API_KEY was loaded from the secret store into the process environment.
$headers = @{ Authorization = "Bearer $env:ISMS_API_KEY" }
Invoke-RestMethod "$env:ISMS_URL/api/v1/assets?perPage=10" -Headers $headers

This request requires assets:read.

Documentation and downloads

Path on your instance Access and content
/settings/api-keys/docs Embedded guide, using an administrator session
/settings/api-keys/openapi.json OpenAPI download using an administrator session
/api/v1/openapi.json OpenAPI 3.1 with a valid bearer key
/settings/api-keys/adapters.zip HTTPS sender, asset export and Veeam examples with German and English instructions
/settings/api-keys/mcp-server.zip Local MCP server and setup instructions

OpenAPI lists operations, parameters, required fields, responses and errors. x-required-scopes lists permissions; operation descriptions explain additional conditions. x-domain-schema describes domain value constraints. Use the target instance's specification when building a client.

Domain coverage

The domain API exposes defined workflows rather than direct database access. Validation, conflict checks, approvals, document encryption and audit logging also apply to API requests.

Paths under /api/v1 Data and workflows
/assets, /assets/{id}/records Assets, dependencies, contracts, documents and recovery information
/vendors, /vendors/{id}/records Vendors, contacts, contracts, assessments and subcontractors
/risks, /measures Risks, acceptance, measures, completion and effectiveness
/scope, /scope/elements, /scope/history Scope, elements, interfaces, versions and approvals
/soa, /soa/snapshots, /soa/gap-analysis Controls, assessments, evidence, links and assessment snapshots
/bcm, /bcm/exercises/{id}, /recovery-plan Processes, BIA, recovery, exercises, findings and tasks
/backup-jobs Backup jobs, runs, restore test definitions and test evidence
/audits, /reviews Audit programmes, audits, findings, management reviews and decisions
/incidents Incidents, timeline, classification, recorded notifications and evidence
/policies, /policies/{id}/translations Policies, versions, approvals and translations
/trainings, /emergency Training, attendance administration, emergency plans, contacts and tests
/processing-activities, /processing-activities/toms Processing activities, technical and organisational measures and links
/access-requests, /user-lifecycle, /user-lifecycle/profiles Requests, decisions, implementation and access profiles
/users, /groups, /group-assignments User and group references and domain group assignments
/documents, /documents/{id}, /audit-log Document metadata, downloads and change history
/integrations Sources, bindings, push batches, observations and deviations

These paths do not imply unrestricted CRUD support for every resource. Available methods and action paths are listed in OpenAPI. System administration, licensing, directory configuration and framework import remain in Settings. Technical API accounts cannot provide personal acknowledgements or self-confirmations.

Permissions

Scope Purpose
<module>:read Read domain data
<module>:write Create and edit; additional domain actions also require read
<module>:approve Domain decisions and completion, in addition to required read/write permissions
<module>:delete Supported deletion actions
directory:read Read user references
groups:read, groups:write Group references and domain assignments according to the operation
documents:read, documents:write, documents:delete Document access combined with permissions for the owning record
audit-log:read Read the audit log
integrations:read, integrations:manage, ingest:write Separate roles for evaluation, setup and data delivery

Module names include assets, backup-jobs, processing-activities and user-lifecycle-profiles. Each operation documents the exact combination.

Scopes apply across the entire instance, including drafts and domain versions. They do not inherit personal role or group visibility. For compatibility, assets:read also permits user and vendor references; technical asset details may be returned decrypted. Linked domain sections require additional read scopes, such as bcm:read for recovery notes in /assets/{id}/records. Use separate instances for actual tenant isolation.

Read, create and edit

Lists have module-specific filters and page sizes. Domain lists start page at 1; integration lists use offset and limit. A missing linked section may indicate a missing read scope.

  • GET reads the documented data section.
  • POST on a collection creates a record.
  • PUT submits a complete editing form. Omitting optional fields can clear existing values.
  • Assets and vendors retain their partial PATCH endpoints; null clears a field.
  • Domain decisions use dedicated POST paths under /{id}/actions/….

For domain actions, JSON scalars become form values, arrays become repeated fields and null becomes an empty value. Read the current record before updating and include the operation's conflict markers, such as baseUpdatedAt, expectedUpdatedAt or baseVersion. On 409, read again and reconcile the changes.

Domain actions usually return HTTP 200 and success: true; the existing asset creation endpoint uses 201. A returned id can identify the parent record. Read the result through the documented read endpoint. Domain creation is not automatically idempotent: do not blindly repeat a request after a lost response. Use push ingest for repeatable source imports.

Match assets by external IDs

The classic asset API uses externalSource and externalId together. Matching ignores case and surrounding whitespace.

  1. Search using GET /api/v1/assets?externalSource=glpi&externalId=srv-001.
  2. If absent, create using POST /api/v1/assets. Required fields are name, assetType, criticality from 1 to 5 and a valid ownerId.
  3. If present, use PATCH /api/v1/assets/{id} and send the previously read updatedAt as expectedUpdatedAt.
  4. On 409 duplicateExternalRef, read the existing record identified by details.existingId.

This is a client-side reconciliation workflow, not a single upsert endpoint. Push ingest uses a separate source/binding contract. Explicitly bind existing assets there.

Backup runs and restore tests

An existing backup job can receive a backup run. The key requires backup-jobs:read and backup-jobs:write. Replace the example timestamps with actual values.

$jobId = 'UUID-OF-BACKUP-JOB'
$run = @{
    startedAt = '2026-09-19T01:00:00Z'
    finishedAt = '2026-09-19T01:10:00Z'
    result = 'successful'
    restorePointAt = '2026-09-19T01:00:00Z'
} | ConvertTo-Json
Invoke-RestMethod "$env:ISMS_URL/api/v1/backup-jobs/$jobId/actions/add-run" `
    -Method Post -Headers $headers -ContentType 'application/json' -Body $run

The detail response includes backupJob.runs, backupJob.restoreTestDefinitions and executions. Restore test completion and correction use complete-execution and correct-execution, with the additional scope backup-jobs:approve. OpenAPI lists their required fields. A correction creates new evidence rather than overwriting a completed test.

Ingest observations are separate. A backup_run event does not automatically create a domain backup run; a restore_test event does not complete a test execution. The adapter chapter explains what a successful job means for RPO and restore evidence.

Documents and evidence

Send files through the owning record's upload action, for example POST /api/v1/assets/{id}/actions/upload-document with multipart/form-data and a file field. In addition to domain permissions, documents:write is required. For multipart requests, send Origin: https://isms.example.org using the actual instance origin without a trailing slash. Form protection runs before API authentication.

Downloads require documents:read and read permission for the owning record. Documents are stored encrypted. JSON requests are limited to 1 MiB and multipart requests to 26 MiB; domain-specific file limits also apply. Ingest evidence contains short summaries with optional links and hashes, not uploaded files.

Errors and request limits

{
  "code": "conflict",
  "message": "…",
  "details": { "reason": "sourceRevision" }
}

Clients should inspect the HTTP status and code, and additionally details.reason for ingest. message is localised using Accept-Language: de or en.

Status Handling
400 Check JSON, required fields, values and references
401 Key is missing, invalid, expired or revoked
403 Required scopes are missing
404 Check path, record ID and installed feature set; for ingest, also check the key's source assignment
409 Inspect the conflict and read the current domain state
413 / 415 Correct request size or Content-Type
429 Respect Retry-After; maximum 120 requests per minute per key

Use polling to detect status changes; webhooks are not included.

MCP clients

The supplied MCP server runs on the user's computer and connects to the instance over HTTPS. Download the ZIP under API access, extract it and follow its README to install. Configure the MCP client to run node with the path to index.js, providing ISMSLITE_URL and ISMSLITE_API_KEY from protected configuration.

The MCP package requires Node.js 20 or later. Run npm install once in the extracted directory. This installs the local MCP client, not the ISMS server or the separate push adapters.

Alongside existing asset/vendor tools, the extension provides list_api_operations and call_api_operation. They use the target instance's OpenAPI specification for supported JSON operations with GET, POST and PUT. File uploads require a suitable HTTP client. AI clients also operate within their key's scopes; grant approval permissions deliberately.