API & CLI

Organization owners and security admins create API keys in Settings → Workspace & API → API Keys (a verified e-mail address is required). A key is shown once, starts with erppf_live_ and is bound to its organization. Send it in the X-Api-Key header.

Access is denied by default: every route that API keys may call requires one specific scope, and routes without a scope are closed to API keys. Keys created in the web app get projects:read, analyses:read, analyses:run, findings:read and reports:read. The other scopes — projects:write, findings:write, landscapes:read, landscapes:write, dashboard:read, webhooks:manage and changes:propose — can be granted when a key is created through the API. Managing API keys, members, the account, billing, single sign-on and SCIM, data retention and the audit log always requires an interactive sign-in.

The scope catalog, expiry, revocation and request limits are described under API keys & scopes.

All endpoints live under /api/v1. Typical automation flow:

POST /api/v1/projects                              create a project
POST /api/v1/projects/{projectId}/files            upload an artifact (multipart field "file")
POST /api/v1/analyses                              {"projectId", "engineTypes": [...], "fileIds": [...]}
GET  /api/v1/analyses/{analysisId}                 poll until COMPLETED / FAILED / PARTIAL
GET  /api/v1/findings?projectId={projectId}        findings with evidence
POST /api/v1/projects/{projectId}/analyses/{analysisId}/export   {"format": "PDF"}

Export formats: PDF, XLSX, CSV, JSON_BUNDLE, HTML_OFFLINE, ZIP_ALL. The complete, generated OpenAPI reference is linked below.

The CLI (package @erppreflight/cli, Node.js 18 or newer) uses the same API with an API key. Point it at your instance with --api-url or ERP_PREFLIGHT_API_URL (for example https://api.example.com); login verifies the key and stores it in a config file readable only by you:

erp-preflight login --key erppf_live_… --api-url https://api.example.com
erp-preflight status
erp-preflight project create --name "S/4HANA 2023 upgrade" --release S4H_2023
erp-preflight upload <projectId> ./exports/billing_opd.xml
erp-preflight analyze <projectId> --engines OPD_GUARD --wait --fail-on BLOCKER,CRITICAL
erp-preflight findings <projectId> --severity CRITICAL
erp-preflight report export <projectId> <analysisId> --format PDF --out report.pdf
erp-preflight report download <analysisId> --out bundle.zip

Uploads go through the same server-side checks as the web app (magic bytes, malware scan, secret redaction for text formats) and analyses run the same deterministic engines. project create needs a key with projects:write, which keys created in the web app do not have. analyze clean-core|api-diff|mfs <path…> --project <id> uploads local files and runs the matching engine. With --wait --fail-on the CLI exits with code 3 when findings of the listed severities exist — use it as a CI quality gate. Add --json for machine-readable output. Exit codes: 0 ok, 1 error, 2 usage/authentication, 3 quality gate failed. Details: CLI and CI integration.

POST /api/v1/mcp is a JSON-RPC 2.0 endpoint implementing the Model Context Protocol methods tools/list and tools/call (tools such as search_knowledge, get_findings and explain_finding); it does not implement the initialize handshake. For agents that expect a local command, the CLI package includes the stdio MCP server erp-preflight-mcp; its tools are prefixed erppreflight_ (for example erppreflight_list_projects and erppreflight_search_knowledge). Tools, scopes and configuration are described under MCP server.