Report-as-a-Service API

v1

Submit compliance assessment data via API and receive 25 persona-specific stakeholder reports. Reports can be embedded on your website via iframe — no client identity exposed.

Quick Start (3 Steps)
1
Submit Assessment

POST your company's met/not_met requirements to /api/v1/assessments

2
Generate Reports

POST to /api/v1/assessments/:id/generate to create all 25 persona reports

3
Embed Reports

Use the returned embedUrl in an iframe on your website

Authentication

All authenticated endpoints require a Bearer token in the Authorization header. API keys are generated from the API Key Management page.

Authorization: Bearer lf_YOUR_API_KEY_HERE

Key format: lf_ prefix followed by 64 hex characters

Rate limits: Configurable per key (default 100 requests/hour)

Framework restrictions: Keys can be limited to specific frameworks

Privacy-First Design

This API is designed with privacy as a core principle. Partner companies send only an opaque company ID (e.g., client_8472) — never the actual company name.

Reports use generic language like "the organization" unless the partner provides an optional displayName field. This means client identity is never stored or exposed in the Lionfish platform.

API Endpoints

25 Persona Reports
CEO / President
ceo_presidentExecutive
CFO
cfoExecutive
CIO
cioExecutive
CISO
cisoExecutive
COO
cooExecutive
Board Member
board_memberExecutive
General Counsel
general_counselManagement
Compliance Officer
compliance_officerManagement
IT Director
it_directorManagement
Risk Manager
risk_managerManagement
HR Director
hr_directorManagement
Procurement Manager
procurement_managerManagement
Data Privacy Officer
data_privacy_officerManagement
Project Manager
project_managerOperational
Internal Auditor
internal_auditorOperational
Security Analyst
security_analystOperational
Security Architect
security_architectOperational
Incident Responder
incident_responderOperational
Network Admin
network_adminOperational
Sales Director
sales_directorBusiness
Marketing Director
marketing_directorBusiness
Small Business Owner
small_business_ownerBusiness
External Auditor
external_auditorExternal
Insurance Underwriter
insurance_underwriterExternal
Investor / VC
investorExternal
cURL Examples

1. Submit Assessment

curl -X POST https://stakeholder.lionfishcyber.com/api/v1/assessments \
  -H "Authorization: Bearer lf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{\n  "companyId": "client_8472",\n  "industry": "Healthcare",\n  "framework": "HIPAA",\n  "policy": "YES",\n  "requirements": [\n    { "id": "164.308(a)(1)", "title": "Security Management Process", "status": "met" },\n    { "id": "164.308(a)(2)", "title": "Assigned Security Responsibility", "status": "met" },\n    { "id": "164.308(a)(3)", "title": "Workforce Security", "status": "not_met" },\n    { "id": "164.308(a)(4)", "title": "Information Access Management", "status": "partially_met" },\n    { "id": "164.308(a)(5)", "title": "Security Awareness and Training", "status": "not_met" },\n    { "id": "164.310(a)(1)", "title": "Facility Access Controls", "status": "met" },\n    { "id": "164.310(b)", "title": "Workstation Use", "status": "met" },\n    { "id": "164.312(a)(1)", "title": "Access Control", "status": "partially_met" },\n    { "id": "164.312(b)", "title": "Audit Controls", "status": "not_met" },\n    { "id": "164.312(c)(1)", "title": "Integrity", "status": "met" }\n  ],\n  "displayName": "Acme Health Corp"\n}'

2. Generate Reports

curl -X POST https://stakeholder.lionfishcyber.com/api/v1/assessments/42/generate \
  -H "Authorization: Bearer lf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"methodology": "spin"}'

3. Embed on Your Website

<!-- Embed all reports with persona selector -->
<iframe
  src="https://stakeholder.lionfishcyber.com/embed/assessment/{embedToken}"
  width="100%"
  height="800"
  frameborder="0"
  style="border: 1px solid #1e293b; border-radius: 12px;"
></iframe>

<!-- Embed a single report -->
<iframe
  src="https://stakeholder.lionfishcyber.com/embed/report/{viewToken}"
  width="100%"
  height="800"
  frameborder="0"
></iframe>
10 Sales Methodologies

Each report can be generated with a specific sales methodology that changes the tone, framing, and call-to-action style. Default is SPIN.

spin

SPIN Selling

challenger

Challenger Sale

sandler

Sandler

solution_selling

Solution Selling

bant

BANT

gap_selling

Gap Selling

value_selling

Value Selling

command_of_message

Command of the Message

consultative_selling

Consultative

meddpicc

MEDDPICC

Rate Limiting

Each API key has a configurable rate limit (default: 100 requests/hour). The API returns rate limit information in response headers on every authenticated request.

X-RateLimit-Limit

Maximum requests allowed per hour

X-RateLimit-Remaining

Requests remaining in current window

X-RateLimit-Reset

UTC epoch seconds when window resets

429 Too Many Requests Response

{
  "error": "Rate limit exceeded. Try again later.",
  "retryAfter": 1842
}

Tier options: 10/hr (Trial), 50/hr (Starter), 100/hr (Standard), 500/hr (Professional), 1000/hr (Enterprise)

Sliding window: Uses a 1-hour sliding window, not a fixed clock-hour reset

Webhook Notifications

Configure a webhook URL when creating an API key to receive automatic notifications when report generation completes. Webhooks are signed with HMAC-SHA256 so you can verify they came from Lionfish.

Webhook Headers

X-Lionfish-Signature — HMAC-SHA256 hex digest of the request body
X-Lionfish-Event — Event type (e.g., assessment.reports.completed)
X-Lionfish-Delivery — Unique delivery ID for deduplication
X-Lionfish-Timestamp — ISO 8601 timestamp of the event

Webhook Payload Example

{
  "event": "assessment.reports.completed",
  "assessmentId": 42,
  "externalCompanyId": "client_8472",
  "framework": "HIPAA",
  "complianceScore": 50,
  "status": "completed",
  "totalReports": 25,
  "failedReports": 0,
  "embedToken": "abc123def456...",
  "embedUrl": "https://your-domain/embed/assessment/abc123def456...",
  "reports": [
    { "persona": "ceo_president", "viewToken": "tok_...", "viewUrl": "/embed/report/tok_..." },
    ...
  ],
  "timestamp": "2026-02-25T22:00:00.000Z"
}

Signature Verification (Node.js)

import crypto from 'crypto';

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac('sha256', secret).update(body).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// In your Express handler:
app.post('/webhooks/lionfish', (req, res) => {
  const signature = req.headers['x-lionfish-signature'];
  const isValid = verifyWebhook(JSON.stringify(req.body), signature, WEBHOOK_SECRET);
  if (!isValid) return res.status(401).send('Invalid signature');
  
  // Process the webhook...
  console.log('Reports ready:', req.body.reports.length);
  res.status(200).send('OK');
});

Events: assessment.reports.completed, assessment.reports.failed

Retries: 3 attempts with exponential backoff (1s, 4s, 16s)

Timeout: 10 seconds per attempt

Success: Any 2xx response is considered successful delivery

Pricing

$250 per assessment — includes all 25 persona-specific reports ($10 each).

Partners processing 20 clients/month = $5,000/month recurring revenue.

Contact us for volume discounts and enterprise pricing.