API Reference

Overview

The SignalBreak REST API allows programmatic access to all platform features, including workflows, provider signals, risk scenarios, governance reports, and billing management.

Base URL: https://signalbreak.vercel.app/api (or your custom domain)

Protocol: HTTPS only

Format: JSON request and response bodies

Authentication: Session-based (cookie) or API key (planned for future release)

Authentication

Session Authentication (Current)

All API requests require authentication via Clerk session cookies. To use the API:

Web Application: Browser automatically includes session cookies
Programmatic Access: Not yet supported (API key authentication planned for Q2 2026)

Authentication Header: None required (session cookie handled automatically)

Error Response (Unauthorized):

json

HTTP/1.1 401 Unauthorized
{
  "error": "Unauthorized"
}

Tenant Scoping

All API requests are automatically scoped to the authenticated user's tenant. You cannot access data from other tenants.

Tenant Resolution:

Determined from authenticated user's session
Automatically applied to all database queries
Enforced via Row-Level Security (RLS) policies

API Categories

SignalBreak's API is organized into the following categories:

Category	Endpoints	Description
Workflows	9	AI workflow management and provider bindings
Provider Changes (Signals)	8	AI provider change notifications and impacts
Scenarios	7	Risk scenario assessment and mitigation tracking
Providers	5	AI provider registry and health monitoring
Governance	14	Compliance scorecards, frameworks, and MIT risk data
Reports	8	Evidence packs and compliance reports (PDF/Markdown)
AI Systems	3	AI system inventory and EU AI Act classification
Team & Users	6	Team member management and invitations
Billing	5	Subscription management and usage tracking
Settings	6	Organisation settings, branding, notifications
Security	5	Password, SSO, sessions, IP allowlist
Self-Hosted Connections	5	Self-hosted AI provider discovery and health checks
Products	4	Product registry and tenant product mappings
Dashboard	2	Risk summary and correlation analytics
Audit	2	Audit trail export and search
Admin/Cron	5	Administrative and scheduled task endpoints

Total: 122 REST endpoints

Common Patterns

Pagination

List endpoints support pagination via limit and offset parameters.

Query Parameters:

GET /api/workflows?limit=50&offset=0

Parameter	Type	Default	Max	Description
`limit`	integer	50	200	Number of records to return
`offset`	integer	0	—	Number of records to skip

Response Format:

json

{
  "workflows": [...],
  "total": 142,
  "limit": 50,
  "offset": 0
}

Filtering

Many list endpoints support filtering via query parameters.

Example:

GET /api/provider-changes?provider_id=1&severity=critical&change_type=deprecation

Common Filter Parameters:

Parameter	Applicable Endpoints	Values
`provider_id`	Provider Changes, Workflows	Integer (provider ID)
`change_type`	Provider Changes	`deprecation`, `policy`, `pricing`, `capability`, `incident`
`severity`	Provider Changes, Scenarios	`critical`, `warning`, `info`
`domain`	Provider Changes, Incidents	`1`-`7` (MIT domain ID)
`status`	Scenarios, Workflows	Varies by endpoint

Error Responses

All errors return JSON with an error field.

Standard Error Format:

json

{
  "error": "Error message",
  "detail": "Optional detailed explanation",
  "code": "ERROR_CODE" // Optional error code
}

HTTP Status Codes:

Code	Meaning	Common Causes
200	Success	Request completed successfully
201	Created	Resource created successfully (POST)
400	Bad Request	Invalid parameters or request body
401	Unauthorized	Not authenticated (missing or invalid session)
403	Forbidden	Feature limit exceeded or insufficient permissions
404	Not Found	Resource doesn't exist or doesn't belong to tenant
409	Conflict	Resource already exists (duplicate)
500	Internal Server Error	Server error (contact support)

Feature Gates & Billing Limits

Certain endpoints enforce feature limits based on subscription tier.

Feature-Gated Endpoints:

POST /api/scenarios — Scenario creation limit
POST /api/workflows — Workflow creation limit
GET /api/provider-changes — Signal history retention

403 Response (Feature Limit Exceeded):

json

HTTP/1.1 403 Forbidden
{
  "error": "Scenario limit reached",
  "code": "FEATURE_LIMIT_EXCEEDED",
  "requiresUpgrade": true,
  "limit": 10,
  "current": 10,
  "suggestedPlan": "professional"
}

Billing Tier Limits:

Feature	Free	Professional	Enterprise
Workflows	5	50	Unlimited
Scenarios	10	100	Unlimited
Signal History	7 days	90 days	Unlimited
Team Members	1	10	Unlimited
Evidence Packs	1/month	Unlimited	Unlimited

Workflows

Endpoints for managing AI workflows and provider bindings.

List Workflows

GET /api/workflows

Returns all workflows for the authenticated tenant.

Query Parameters: None

Response:

json

{
  "workflows": [
    {
      "workflow_id": "uuid",
      "workflow_name": "Customer Support Chatbot",
      "ai_capability": "text_generation",
      "criticality": "mission_critical",
      "human_in_loop": true,
      "output_format": "json",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-20T14:22:00Z",
      "ai_system_id": "uuid",
      "product_id": "uuid",
      "provider_name": "OpenAI",
      "model_class": "gpt-4o",
      "model_name": "GPT-4o",
      "discovered_model_id": "uuid",
      "discovered_model_name": "gpt-4o-2024-08-06",
      "ai_system_name": "Support AI",
      "product_name": "Customer Service Platform",
      "total_risks": 12,
      "treated_risks": 8,
      "untreated_risks": 4,
      "scenario_count": 3,
      "max_impact_severity": "high",
      "signal_count": 5
    }
  ]
}

Get Workflow by ID

GET /api/workflows/{id}

Returns a single workflow with full details.

Path Parameters:

id (uuid) — Workflow ID

Response:

json

{
  "workflow_id": "uuid",
  "workflow_name": "Customer Support Chatbot",
  "ai_capability": "text_generation",
  "criticality": "mission_critical",
  "human_in_loop": true,
  "output_format": "json",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-20T14:22:00Z",
  "ai_system_id": "uuid",
  "product_id": "uuid"
}

Error Responses:

404 — Workflow not found or doesn't belong to tenant

Create Workflow

POST /api/workflows

Creates a new workflow.

Request Body:

json

{
  "workflow_name": "Legal Document Analysis",
  "ai_capability": "text_generation",
  "criticality": "important",
  "human_in_loop": true,
  "output_format": "text",
  "ai_system_id": "uuid",
  "product_id": "uuid"
}

Required Fields:

workflow_name (string, 1-200 chars)
ai_capability (enum): text_generation, image_generation, image_to_text, text_to_speech, speech_to_text, embeddings, reasoning, code_generation, vision, multimodal
criticality (enum): mission_critical, important, nice_to_have

Optional Fields:

human_in_loop (boolean, default: false)
output_format (enum): text, json, image, audio, video
ai_system_id (uuid)
product_id (uuid)

Response:

json

HTTP/1.1 201 Created
{
  "workflow_id": "uuid",
  "workflow_name": "Legal Document Analysis",
  ...
}

Error Responses:

400 — Validation error (invalid field values)
403 — Workflow limit exceeded (feature gate)

Update Workflow

PUT /api/workflows/{id}

Updates an existing workflow.

Path Parameters:

id (uuid) — Workflow ID

Request Body: Same as create, all fields optional (partial update supported)

Response:

json

{
  "workflow_id": "uuid",
  "workflow_name": "Legal Document Analysis (Updated)",
  ...
}

Delete Workflow

DELETE /api/workflows/{id}

Soft-deletes a workflow (sets is_active = FALSE).

Path Parameters:

id (uuid) — Workflow ID

Response:

json

HTTP/1.1 204 No Content

Get Workflow Signals

GET /api/workflows/{id}/signals

Returns provider signals affecting this workflow.

Path Parameters:

id (uuid) — Workflow ID

Response:

json

{
  "signals": [
    {
      "id": "uuid",
      "provider_name": "OpenAI",
      "change_type": "deprecation",
      "severity": "warning",
      "title": "OpenAI Deprecating GPT-3.5 Turbo in March 2025",
      "description": "GPT-3.5 Turbo will be retired...",
      "source_url": "https://openai.com/changelog/...",
      "created_at": "2025-01-15T14:32:00Z"
    }
  ]
}

Get Workflow Risks

GET /api/workflows/{id}/risks

Returns MIT AI Risk domains associated with this workflow.

Path Parameters:

id (uuid) — Workflow ID

Response:

json

{
  "risks": [
    {
      "domain_id": "7",
      "domain_name": "AI System Safety, Failures & Limitations",
      "subdomain_id": "7.3",
      "subdomain_name": "Lack of capability or robustness",
      "risk_level": "high",
      "treatment_status": "Treated",
      "mitigation_actions": ["Implement fallback provider", "Monitor deprecation schedule"]
    }
  ]
}

Import Workflows (Bulk)

POST /api/workflows/import

Imports multiple workflows from CSV or JSON.

Request Body:

json

{
  "format": "json",
  "workflows": [
    {
      "workflow_name": "Workflow 1",
      "ai_capability": "text_generation",
      "criticality": "important"
    },
    {
      "workflow_name": "Workflow 2",
      "ai_capability": "embeddings",
      "criticality": "nice_to_have"
    }
  ]
}

Response:

json

{
  "imported": 2,
  "failed": 0,
  "errors": []
}

Get Workflow Templates

GET /api/workflows/templates

Returns pre-defined workflow templates for common use cases.

Response:

json

{
  "templates": [
    {
      "template_id": "customer-support-chatbot",
      "name": "Customer Support Chatbot",
      "ai_capability": "text_generation",
      "criticality": "mission_critical",
      "description": "AI-powered customer support chatbot template"
    }
  ]
}

Get Workflow Stats

GET /api/workflows/stats

Returns aggregate statistics for tenant's workflows.

Response:

json

{
  "total_workflows": 12,
  "by_criticality": {
    "mission_critical": 3,
    "important": 6,
    "nice_to_have": 3
  },
  "by_capability": {
    "text_generation": 8,
    "image_to_text": 2,
    "embeddings": 2
  },
  "total_provider_bindings": 24,
  "workflows_with_fallback": 9
}

Provider Changes (Signals)

Endpoints for accessing provider change notifications and impact analysis.

List Provider Changes

GET /api/provider-changes

Returns provider signals (changes, incidents, announcements).

Query Parameters:

provider_id (integer, optional) — Filter by provider
change_type (enum, optional) — deprecation, policy, pricing, capability, incident
severity (enum, optional) — critical, warning, info
domain (string, optional) — MIT domain ID (1-7)
limit (integer, default: 50, max: 200)
offset (integer, default: 0)

Response:

json

{
  "signals": [
    {
      "id": "uuid",
      "provider_id": 1,
      "provider_name": "OpenAI",
      "change_type": "deprecation",
      "severity": "warning",
      "title": "OpenAI Deprecating GPT-3.5 Turbo in March 2025",
      "description": "GPT-3.5 Turbo will be retired on 2025-03-31...",
      "effective_date": "2025-03-31",
      "source_url": "https://openai.com/changelog/...",
      "is_synthetic": false,
      "created_at": "2025-01-15T14:32:00Z",
      "updated_at": "2025-01-15T14:35:12Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Billing Restriction: Signal history limited by subscription tier (Free: 7 days, Professional: 90 days, Enterprise: Unlimited).

Get Provider Change by ID

GET /api/provider-changes/{id}

Returns a single provider signal with enrichment data.

Path Parameters:

id (uuid) — Signal ID

Response:

json

{
  "id": "uuid",
  "provider_id": 1,
  "provider_name": "OpenAI",
  "change_type": "deprecation",
  "severity": "warning",
  "title": "OpenAI Deprecating GPT-3.5 Turbo in March 2025",
  "description": "GPT-3.5 Turbo will be retired on 2025-03-31...",
  "effective_date": "2025-03-31",
  "source_url": "https://openai.com/changelog/...",
  "raw_content": "Full raw content from provider...",
  "classification_model": "claude-3-5-haiku-20241022",
  "classification_confidence": 0.85,
  "created_at": "2025-01-15T14:32:00Z",
  "updated_at": "2025-01-15T14:35:12Z",
  "mit_domains": [
    {
      "domain_id": "7",
      "subdomain_id": "7.3",
      "confidence": 0.92,
      "reason": "Model deprecation may cause system failures"
    }
  ]
}

Get Signal Impacts

GET /api/provider-changes/{id}/impacts

Returns workflows affected by this signal.

Path Parameters:

id (uuid) — Signal ID

Response:

json

{
  "impacts": [
    {
      "workflow_id": "uuid",
      "workflow_name": "Customer Support Chatbot",
      "criticality": "mission_critical",
      "impact_score": 240,
      "impact_status": "red",
      "provider_binding": "primary",
      "model_name": "gpt-3.5-turbo"
    }
  ],
  "total_affected": 3
}

Create Scenario from Signal

POST /api/provider-changes/{id}/create-scenario

Converts a signal into a formal risk scenario.

Path Parameters:

id (uuid) — Signal ID

Request Body:

json

{
  "scenario_name": "GPT-3.5 Turbo Deprecation Response",
  "impact_severity": "high",
  "likelihood": "certain",
  "mitigation_plan": "Migrate to GPT-4o mini by 2025-03-01"
}

Response:

json

HTTP/1.1 201 Created
{
  "scenario_id": "uuid",
  "scenario_name": "GPT-3.5 Turbo Deprecation Response",
  "scenario_status": "draft",
  "created_at": "2025-01-20T10:15:00Z"
}

Scenarios

Endpoints for risk scenario management and mitigation tracking.

List Scenarios

GET /api/scenarios

Returns all scenarios for the authenticated tenant.

Query Parameters:

status (enum, optional) — draft, active, resolved, archived
scenario_type (enum, optional) — provider_outage, model_deprecation, policy_change, cost_overrun, performance_degradation, security_incident, compliance_violation, custom

Response:

json

{
  "scenarios": [
    {
      "scenario_id": "uuid",
      "scenario_name": "OpenAI GPT-4 Outage Response",
      "scenario_description": "Contingency plan for GPT-4 outage exceeding 1 hour",
      "scenario_type": "provider_outage",
      "scenario_status": "active",
      "created_at": "2025-01-10T09:00:00Z",
      "updated_at": "2025-01-15T14:30:00Z",
      "impact_count": 5,
      "mitigation_count": 3
    }
  ]
}

Create Scenario

POST /api/scenarios

Creates a new risk scenario.

Request Body:

json

{
  "scenario_name": "AWS Bedrock Regional Outage",
  "scenario_description": "Response plan if AWS Bedrock experiences regional outage",
  "scenario_type": "provider_outage",
  "target_product_id": "uuid",
  "trigger_conditions": {
    "provider": "AWS Bedrock",
    "duration_threshold_mins": 60
  }
}

Response:

json

HTTP/1.1 201 Created
{
  "scenario_id": "uuid",
  "scenario_name": "AWS Bedrock Regional Outage",
  "scenario_status": "draft",
  ...
}

Error Responses:

403 — Scenario limit exceeded (feature gate)

Execute Scenario

POST /api/scenarios/{id}/execute

Activates a scenario response plan.

Path Parameters:

id (uuid) — Scenario ID

Request Body:

json

{
  "execution_notes": "AWS Bedrock us-east-1 outage detected at 14:32 UTC",
  "notify_team": true
}

Response:

json

{
  "execution_id": "uuid",
  "scenario_id": "uuid",
  "executed_at": "2025-01-20T14:35:00Z",
  "execution_status": "in_progress"
}

Get Scenario Mitigations

GET /api/scenarios/{id}/mitigations

Returns mitigation actions for a scenario.

Path Parameters:

id (uuid) — Scenario ID

Response:

json

{
  "mitigations": [
    {
      "mitigation_id": "uuid",
      "action_description": "Switch to OpenAI fallback provider",
      "assigned_to": "user@example.com",
      "due_date": "2025-01-25",
      "status": "completed",
      "completed_at": "2025-01-23T10:00:00Z"
    }
  ]
}

Create Scenario from Signal

POST /api/scenarios/from-signal

Creates a scenario from a provider signal (alternative endpoint).

Request Body:

json

{
  "signal_id": "uuid",
  "scenario_name": "OpenAI API Pricing Increase Response",
  "impact_severity": "medium"
}

Response: Same as POST /api/scenarios

Get Scenario Templates

GET /api/scenarios/templates

Returns pre-defined scenario templates.

Response:

json

{
  "templates": [
    {
      "template_id": "provider-outage",
      "name": "Provider Outage Response",
      "description": "Standard response plan for provider outages exceeding 1 hour",
      "scenario_type": "provider_outage"
    }
  ]
}

Providers

Endpoints for AI provider registry and health monitoring.

List Providers

GET /api/providers

Returns AI providers available in SignalBreak.

Query Parameters:

in_use_only (boolean, default: false) — Only return providers used by tenant's workflows

Response:

json

{
  "providers": [
    {
      "provider_id": 1,
      "provider_name": "OpenAI",
      "provider_key": "openai",
      "tier": "Tier 1",
      "capabilities": ["text_generation", "embeddings", "vision"],
      "health_status": "operational",
      "in_use": true
    }
  ]
}

Get Provider by ID

GET /api/providers/{id}

Returns a single provider with details.

Path Parameters:

id (integer) — Provider ID

Response:

json

{
  "provider_id": 1,
  "provider_name": "OpenAI",
  "provider_key": "openai",
  "tier": "Tier 1",
  "capabilities": ["text_generation", "embeddings", "vision"],
  "health_status": "operational",
  "status_page_url": "https://status.openai.com",
  "documentation_url": "https://platform.openai.com/docs"
}

Get Provider Health

GET /api/providers/health

Returns current health status for all monitored providers.

Response:

json

{
  "providers": [
    {
      "provider_id": 1,
      "provider_name": "OpenAI",
      "health_status": "operational",
      "last_checked": "2025-01-26T10:00:00Z",
      "indicators": {
        "api_status": "operational",
        "dashboard_status": "operational",
        "docs_status": "operational",
        "status_page": "operational",
        "community_reports": "operational"
      }
    }
  ]
}

Get Provider Products

GET /api/providers/{id}/products

Returns AI models/products offered by a provider.

Path Parameters:

id (integer) — Provider ID

Response:

json

{
  "products": [
    {
      "product_id": "uuid",
      "provider_id": 1,
      "product_name": "GPT-4o",
      "model_identifier": "gpt-4o",
      "capabilities": ["text_generation", "vision"],
      "is_active": true
    }
  ]
}

Search Providers

GET /api/providers/search

Searches providers by name or capability.

Query Parameters:

q (string, required) — Search query
capability (enum, optional) — Filter by AI capability

Response:

json

{
  "results": [
    {
      "provider_id": 1,
      "provider_name": "OpenAI",
      "provider_key": "openai",
      "match_score": 0.95
    }
  ]
}

Governance

Endpoints for compliance scoring, framework mapping, and MIT risk data.

Get Governance Scorecard

GET /api/governance/scorecard

Returns overall governance scorecard for tenant.

Response:

json

{
  "riskScore": {
    "score": 42,
    "status": "amber",
    "label": "Moderate Risk"
  },
  "concentration": {
    "primaryProvider": "OpenAI",
    "primaryWorkflowCount": 7,
    "totalWorkflows": 12,
    "concentrationPercentage": 58.3,
    "diversificationScore": 4
  },
  "topExposures": [
    {
      "impact_id": "uuid",
      "severity": "critical",
      "impact_description": "Customer support system unavailable",
      "estimated_downtime_mins": 240,
      "workflow_name": "Support Chatbot",
      "scenario_name": "OpenAI Outage",
      "provider_name": "OpenAI"
    }
  ],
  "activeSignals": [
    {
      "change_id": "uuid",
      "signal_type": "deprecation",
      "severity": "warning",
      "detected_at": "2025-01-15T14:32:00Z",
      "title": "OpenAI Deprecating GPT-3.5 Turbo",
      "provider_name": "OpenAI"
    }
  ]
}

Get Scorecard History

GET /api/governance/scorecard/history

Returns historical governance scores (time series).

Query Parameters:

days (integer, default: 90) — Number of days of history

Response:

json

{
  "history": [
    {
      "date": "2025-01-01",
      "score": 38,
      "status": "amber"
    },
    {
      "date": "2025-01-08",
      "score": 42,
      "status": "amber"
    }
  ]
}

List Governance Frameworks

GET /api/governance/frameworks

Returns supported governance frameworks.

Response:

json

{
  "frameworks": [
    {
      "framework_id": "iso-42001",
      "framework_name": "ISO 42001:2023",
      "description": "AI Management System",
      "is_certifiable": true,
      "adoption_percentage": 75
    },
    {
      "framework_id": "nist-ai-rmf",
      "framework_name": "NIST AI RMF",
      "description": "AI Risk Management Framework",
      "is_certifiable": false,
      "adoption_percentage": 82
    }
  ]
}

Get Frameworks for Domain

GET /api/governance/frameworks/for-domain/{domainId}

Returns governance frameworks relevant to a specific MIT domain.

Path Parameters:

domainId (string) — MIT domain ID (1-7)

Response:

json

{
  "frameworks": [
    {
      "framework_id": "iso-42001",
      "framework_name": "ISO 42001:2023",
      "relevance": "high",
      "mapped_controls": 12
    }
  ]
}

Get Mitigations for Subdomain

GET /api/governance/mitigations/for-subdomain/{subdomainId}

Returns MIT mitigation strategies for a specific subdomain.

Path Parameters:

subdomainId (string) — MIT subdomain ID (e.g., 7.3)

Response:

json

{
  "mitigations": [
    {
      "mitigation_id": "uuid",
      "title": "Implement multi-provider fallback architecture",
      "description": "Reduce single-provider dependency by configuring fallback providers",
      "effectiveness": "high",
      "implementation_complexity": "medium"
    }
  ]
}

Get Provider Concentration

GET /api/governance/concentration

Returns provider concentration analysis for tenant.

Response:

json

{
  "primaryProvider": "OpenAI",
  "primaryWorkflowCount": 7,
  "totalWorkflows": 12,
  "concentrationPercentage": 58.3,
  "diversificationScore": 4,
  "providers": [
    {
      "provider_name": "OpenAI",
      "workflow_count": 7,
      "percentage": 58.3
    },
    {
      "provider_name": "Anthropic",
      "workflow_count": 3,
      "percentage": 25.0
    }
  ]
}

Get Risk Radar

GET /api/governance/risk-radar

Returns MIT domain risk distribution for tenant.

Response:

json

{
  "domains": [
    {
      "domain_id": "7",
      "domain_name": "AI System Safety",
      "signal_count": 12,
      "workflow_count": 8,
      "risk_level": "high"
    }
  ]
}

Generate Evidence Pack

POST /api/governance/evidence-pack

Generates a compliance evidence pack (PDF).

Request Body:

json

{
  "frameworks": ["iso-42001", "nist-ai-rmf", "eu-ai-act"],
  "include_mit_context": true,
  "include_provider_analysis": true
}

Response:

json

{
  "evidence_pack_id": "uuid",
  "generation_status": "completed",
  "download_url": "/api/governance/evidence-pack/{id}/download",
  "expires_at": "2025-01-27T10:00:00Z"
}

Note: Evidence pack generation takes 30-60 seconds. Use polling or webhooks to check status.

Get Tenant Framework Adoption

GET /api/governance/tenant-adoption

Returns tenant's adoption percentage for each framework.

Response:

json

{
  "adoption": [
    {
      "framework_id": "iso-42001",
      "framework_name": "ISO 42001:2023",
      "adoption_percentage": 75,
      "controls_implemented": 8,
      "controls_total": 10
    }
  ]
}

Get Framework Adoption by ID

GET /api/governance/tenant-adoption/{frameworkId}

Returns detailed adoption breakdown for a specific framework.

Path Parameters:

frameworkId (string) — Framework ID (e.g., iso-42001)

Response:

json

{
  "framework_id": "iso-42001",
  "framework_name": "ISO 42001:2023",
  "adoption_percentage": 75,
  "controls": [
    {
      "control_id": "4.1",
      "control_name": "Understanding the organisation and its context",
      "implementation_status": "implemented",
      "evidence_count": 3
    }
  ]
}

Reports

Endpoints for generating compliance reports and evidence packs.

Generate Board Report

POST /api/reports/board

Generates executive board report (PDF).

Request Body:

json

{
  "reporting_period": "Q4 2024",
  "include_risk_trends": true,
  "include_signal_summary": true
}

Response:

json

{
  "report_id": "uuid",
  "report_type": "board",
  "generation_status": "completed",
  "download_url": "/api/reports/board/{id}/download"
}

Generate ISO 42001 Report

POST /api/reports/iso42001

Generates ISO 42001 compliance report (PDF/Markdown).

Request Body:

json

{
  "format": "pdf",
  "include_gap_analysis": true
}

Response:

json

{
  "report_id": "uuid",
  "report_type": "iso42001",
  "generation_status": "completed",
  "download_url": "/api/reports/iso42001/{id}/download"
}

Generate NIST AI RMF Report

POST /api/reports/nist-ai-rmf

Generates NIST AI RMF conformance report (PDF/Markdown).

Request Body:

json

{
  "format": "markdown"
}

Response:

json

{
  "report_id": "uuid",
  "report_type": "nist-ai-rmf",
  "generation_status": "completed",
  "download_url": "/api/reports/nist-ai-rmf/{id}/download"
}

Generate EU AI Act Report

POST /api/reports/eu-ai-act

Generates EU AI Act readiness report (PDF/Markdown).

Request Body:

json

{
  "format": "pdf",
  "risk_tier": "high-risk"
}

Response:

json

{
  "report_id": "uuid",
  "report_type": "eu-ai-act",
  "generation_status": "completed",
  "download_url": "/api/reports/eu-ai-act/{id}/download"
}

Generate Operational Report

POST /api/reports/operational

Generates operational risk report for technical teams.

Request Body:

json

{
  "time_period_days": 30
}

Response:

json

{
  "report_id": "uuid",
  "report_type": "operational",
  "generation_status": "completed",
  "download_url": "/api/reports/operational/{id}/download"
}

Generate Vendor Risk Report

POST /api/reports/vendor-risk

Generates vendor risk assessment report.

Request Body:

json

{
  "provider_ids": [1, 2, 3],
  "include_soc2_status": true
}

Response:

json

{
  "report_id": "uuid",
  "report_type": "vendor-risk",
  "generation_status": "completed",
  "download_url": "/api/reports/vendor-risk/{id}/download"
}

AI Systems

Endpoints for AI system inventory and EU AI Act classification.

List AI Systems

GET /api/ai-systems

Returns AI systems in tenant's inventory.

Response:

json

{
  "ai_systems": [
    {
      "id": "uuid",
      "name": "Customer Support AI",
      "description": "AI-powered customer support chatbot",
      "risk_tier": "high-risk",
      "compliance_status": "compliant",
      "created_at": "2025-01-10T09:00:00Z"
    }
  ]
}

Get AI System by ID

GET /api/ai-systems/{id}

Returns a single AI system with full details.

Path Parameters:

id (uuid) — AI system ID

Response:

json

{
  "id": "uuid",
  "name": "Customer Support AI",
  "description": "AI-powered customer support chatbot",
  "risk_tier": "high-risk",
  "compliance_status": "compliant",
  "eu_ai_act_classification": {
    "risk_level": "high-risk",
    "article_6_criteria": ["Safety component", "Critical infrastructure"],
    "conformity_requirements": ["Article 9", "Article 10", "Article 13"]
  },
  "workflows": [
    {
      "workflow_id": "uuid",
      "workflow_name": "Support Chat"
    }
  ]
}

Import AI Systems

POST /api/ai-systems/import

Imports AI systems from CSV or JSON.

Request Body:

json

{
  "format": "json",
  "systems": [
    {
      "name": "Legal AI Assistant",
      "risk_tier": "high-risk"
    }
  ]
}

Response:

json

{
  "imported": 1,
  "failed": 0,
  "errors": []
}

Team & Users

Endpoints for team member management, invitations, and permissions.

List Team Members

GET /api/team

Returns all team members for the tenant.

Response:

json

{
  "members": [
    {
      "user_id": "uuid",
      "email": "user@example.com",
      "full_name": "John Doe",
      "role": "admin",
      "joined_at": "2025-01-01T10:00:00Z",
      "last_active": "2025-01-26T09:30:00Z"
    }
  ]
}

Invite Team Member

POST /api/team/invite

Sends invitation to a new team member.

Request Body:

json

{
  "email": "newuser@example.com",
  "role": "member"
}

Response:

json

HTTP/1.1 201 Created
{
  "invite_id": "uuid",
  "email": "newuser@example.com",
  "invite_status": "pending",
  "expires_at": "2025-02-02T10:00:00Z"
}

Error Responses:

403 — Team member limit exceeded (feature gate)

Get Invite Status

GET /api/team/invite/{inviteId}

Returns invitation status.

Path Parameters:

inviteId (uuid) — Invite ID

Response:

json

{
  "invite_id": "uuid",
  "email": "newuser@example.com",
  "invite_status": "accepted",
  "accepted_at": "2025-01-27T14:00:00Z"
}

Update Team Member Role

PUT /api/team/{memberId}

Updates a team member's role.

Path Parameters:

memberId (uuid) — User ID

Request Body:

json

{
  "role": "admin"
}

Response:

json

{
  "user_id": "uuid",
  "email": "user@example.com",
  "role": "admin"
}

Remove Team Member

DELETE /api/team/{memberId}

Removes a team member from the organisation.

Path Parameters:

memberId (uuid) — User ID

Response:

json

HTTP/1.1 204 No Content

Billing

Endpoints for subscription management, usage tracking, and invoices.

Get Billing Status

GET /api/billing/status

Returns current subscription status and plan.

Response:

json

{
  "plan": "professional",
  "status": "active",
  "current_period_start": "2025-01-01T00:00:00Z",
  "current_period_end": "2025-02-01T00:00:00Z",
  "cancel_at_period_end": false,
  "payment_method": {
    "type": "card",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2026
  }
}

Get Usage Data

GET /api/billing/usage

Returns current billing period usage.

Response:

json

{
  "billing_period": "2025-01-01 to 2025-02-01",
  "usage": {
    "workflows": {
      "current": 12,
      "limit": 50,
      "percentage": 24
    },
    "scenarios": {
      "current": 8,
      "limit": 100,
      "percentage": 8
    },
    "evidence_packs": {
      "current": 3,
      "limit": -1,
      "percentage": 0
    }
  }
}

Get Customer Portal URL

GET /api/billing/portal

Returns Stripe Customer Portal URL for managing subscription.

Response:

json

{
  "portal_url": "https://billing.stripe.com/session/...",
  "expires_at": "2025-01-26T11:00:00Z"
}

Note: URL expires after 1 hour.

Create Checkout Session

POST /api/checkout

Creates a Stripe Checkout session for upgrading subscription.

Request Body:

json

{
  "plan": "professional",
  "success_url": "https://signalbreak.vercel.app/settings/billing?success=true",
  "cancel_url": "https://signalbreak.vercel.app/settings/billing"
}

Response:

json

{
  "checkout_url": "https://checkout.stripe.com/c/pay/...",
  "session_id": "cs_..."
}

Settings

Endpoints for organisation settings, branding, and notifications.

Get Organisation Settings

GET /api/organisation

Returns organisation details and settings.

Response:

json

{
  "tenant_id": "uuid",
  "organisation_name": "Acme Corp",
  "industry": "Financial Services",
  "company_size": "50-200",
  "country": "United Kingdom",
  "plan": "professional",
  "created_at": "2024-12-01T10:00:00Z"
}

Update Organisation Settings

PUT /api/organisation

Updates organisation details.

Request Body:

json

{
  "organisation_name": "Acme Corporation",
  "industry": "Financial Services",
  "company_size": "200-1000"
}

Response:

json

{
  "tenant_id": "uuid",
  "organisation_name": "Acme Corporation",
  ...
}

Update Branding

PUT /api/settings/branding

Updates organisation branding (logo, colors).

Request Body:

json

{
  "logo_url": "https://example.com/logo.png",
  "primary_color": "#3B82F6"
}

Response:

json

{
  "branding": {
    "logo_url": "https://example.com/logo.png",
    "primary_color": "#3B82F6"
  }
}

Get Notification Settings

GET /api/settings/notifications

Returns notification preferences.

Response:

json

{
  "email_notifications": {
    "critical_signals": true,
    "weekly_digest": true,
    "billing_updates": true
  },
  "in_app_notifications": {
    "signals": true,
    "scenarios": true,
    "team_activity": false
  }
}

Update Notification Settings

PUT /api/settings/notifications

Updates notification preferences.

Request Body:

json

{
  "email_notifications": {
    "critical_signals": true,
    "weekly_digest": false
  }
}

Response: Same as GET response.

Security

Endpoints for security settings (password, SSO, sessions, IP allowlist).

Change Password

POST /api/security/password

Changes user's password.

Request Body:

json

{
  "current_password": "oldpassword",
  "new_password": "newpassword123"
}

Response:

json

HTTP/1.1 200 OK
{
  "message": "Password updated successfully"
}

Configure SSO

POST /api/security/sso

Configures Single Sign-On (SAML/OIDC).

Request Body:

json

{
  "provider": "okta",
  "metadata_url": "https://okta.com/app/metadata"
}

Response:

json

{
  "sso_enabled": true,
  "provider": "okta",
  "entity_id": "https://signalbreak.vercel.app/sso"
}

Note: SSO requires Enterprise plan.

List Active Sessions

GET /api/security/sessions

Returns active user sessions.

Response:

json

{
  "sessions": [
    {
      "session_id": "uuid",
      "device": "Chrome on macOS",
      "ip_address": "192.168.1.1",
      "last_active": "2025-01-26T09:30:00Z"
    }
  ]
}

Revoke All Sessions

DELETE /api/security/sessions/all

Revokes all sessions (except current).

Response:

json

{
  "revoked_count": 3
}

Get IP Allowlist

GET /api/security/ip-allowlist

Returns IP allowlist configuration.

Response:

json

{
  "enabled": true,
  "allowed_ips": [
    "203.0.113.0/24",
    "198.51.100.42"
  ]
}

Note: IP allowlist requires Enterprise plan.

Self-Hosted Connections

Endpoints for self-hosted AI provider discovery and monitoring.

List Self-Hosted Connections

GET /api/self-hosted/connections

Returns self-hosted provider connections.

Response:

json

{
  "connections": [
    {
      "connection_id": "uuid",
      "connection_name": "Ollama Production",
      "provider_type": "ollama",
      "endpoint_url": "https://ollama.internal.company.com",
      "health_status": "healthy",
      "last_discovered": "2025-01-26T08:00:00Z"
    }
  ]
}

Discover Models

POST /api/self-hosted/connections/{id}/discover

Triggers model discovery for self-hosted provider.

Path Parameters:

id (uuid) — Connection ID

Response:

json

{
  "discovery_id": "uuid",
  "discovered_models": 12,
  "status": "completed"
}

Get Connection Health

GET /api/self-hosted/connections/{id}/health

Returns health check results for self-hosted connection.

Path Parameters:

id (uuid) — Connection ID

Response:

json

{
  "connection_id": "uuid",
  "health_status": "healthy",
  "response_time_ms": 45,
  "last_check": "2025-01-26T10:00:00Z",
  "models_available": 12
}

Dashboard

Endpoints for dashboard analytics and risk summaries.

Get Risk Summary

GET /api/dashboard/risk-summary

Returns high-level risk summary for dashboard.

Response:

json

{
  "riskScore": {
    "score": 42,
    "status": "amber",
    "label": "Moderate Risk"
  },
  "concentration": {
    "primaryProvider": "OpenAI",
    "concentrationPercentage": 58.3
  },
  "topExposures": [
    {
      "workflow_name": "Support Chatbot",
      "severity": "critical",
      "scenario_name": "OpenAI Outage"
    }
  ],
  "activeSignals": [
    {
      "title": "OpenAI Deprecating GPT-3.5 Turbo",
      "severity": "warning",
      "detected_at": "2025-01-15T14:32:00Z"
    }
  ]
}

Get Correlation Data

GET /api/dashboard/correlation

Returns signal-workflow correlation matrix for analytics.

Response:

json

{
  "correlations": [
    {
      "provider_name": "OpenAI",
      "workflow_count": 7,
      "signal_count": 12,
      "high_severity_count": 3
    }
  ]
}

Audit

Endpoints for audit trail export and search.

Get Audit Log

GET /api/audit

Returns audit log entries.

Query Parameters:

event_type (enum, optional) — Filter by event type
user_id (uuid, optional) — Filter by user
from_date (ISO 8601, optional)
to_date (ISO 8601, optional)
limit (integer, default: 100)
offset (integer, default: 0)

Response:

json

{
  "audit_entries": [
    {
      "audit_id": "uuid",
      "event_type": "workflow.created",
      "user_id": "uuid",
      "user_email": "user@example.com",
      "resource_type": "workflow",
      "resource_id": "uuid",
      "metadata": {
        "workflow_name": "New Chatbot"
      },
      "timestamp": "2025-01-26T09:30:00Z",
      "ip_address": "192.168.1.1"
    }
  ],
  "total": 1247,
  "limit": 100,
  "offset": 0
}

Export Audit Log

GET /api/audit/export

Exports audit log as CSV.

Query Parameters:

from_date (ISO 8601, required)
to_date (ISO 8601, required)

Response:

HTTP/1.1 200 OK
Content-Type: text/csv
Content-Disposition: attachment; filename="audit-log-2025-01-26.csv"

audit_id,event_type,user_email,timestamp,resource_type,resource_id
uuid,workflow.created,user@example.com,2025-01-26T09:30:00Z,workflow,uuid
...

Admin/Cron

Administrative and scheduled task endpoints (restricted access).

Poll Provider Sources

POST /api/cron/poll-sources

Triggers provider source polling (status pages, changelogs).

Authorization: Requires cron secret header (x-vercel-cron-secret)

Response:

json

{
  "status": "completed",
  "sources_polled": 42,
  "signals_created": 3,
  "duration_ms": 12453
}

Enrich Orphan Signals

POST /api/cron/enrich-orphans

Triggers enrichment for unenriched signals.

Authorization: Requires cron secret header

Response:

json

{
  "status": "completed",
  "signals_enriched": 8,
  "duration_ms": 45120
}

Refresh Discovered Models

POST /api/cron/refresh-discoveries

Triggers model discovery refresh for self-hosted connections.

Authorization: Requires cron secret header

Response:

json

{
  "status": "completed",
  "connections_checked": 3,
  "models_discovered": 24
}

Reinterpret Signals

POST /api/admin/reinterpret-signals

Re-runs Claude interpretation on existing signals (admin tool).

Authorization: Requires admin role

Request Body:

json

{
  "signal_ids": ["uuid1", "uuid2"],
  "force": true
}

Response:

json

{
  "signals_reinterpreted": 2,
  "failed": 0
}

Get Extraction Metrics

GET /api/admin/extraction-metrics

Returns signal extraction performance metrics (admin tool).

Authorization: Requires admin role

Response:

json

{
  "total_signals": 1247,
  "enriched_signals": 1198,
  "pending_enrichment": 49,
  "average_enrichment_time_ms": 3450,
  "classification_accuracy": 0.89
}

Rate Limits

SignalBreak enforces rate limits to ensure fair usage and system stability.

Global Rate Limits (Per Tenant):

Endpoint Type	Requests per Minute	Requests per Hour
Read (GET)	120	3600
Write (POST/PUT/DELETE)	60	1200
Report Generation	10	100
Webhook Endpoints	No limit	—

Rate Limit Headers:

All API responses include rate limit information:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1706265600

429 Response (Rate Limit Exceeded):

json

HTTP/1.1 429 Too Many Requests
{
  "error": "Rate limit exceeded",
  "retry_after_seconds": 45
}

Best Practices:

Implement exponential backoff when receiving 429 responses
Cache responses where appropriate
Use webhooks instead of polling for real-time updates (when available)

Webhooks (Planned)

Status: Planned for Q2 2026

Webhooks will allow real-time notifications for events:

signal.created — New provider signal detected
signal.high_severity — Critical/Warning signal detected
scenario.executed — Scenario response plan activated
workflow.impacted — Workflow affected by new signal
evidence_pack.generated — Evidence pack PDF ready

Configuration: Settings → Webhooks → Add Webhook URL

SDKs & Client Libraries (Planned)

Status: Planned for Q3 2026

Official client libraries will be available for:

JavaScript/TypeScript (Node.js, Browser)
Python
Go

Installation (Example):

bash

npm install @signalbreak/sdk

typescript

import { SignalBreak } from '@signalbreak/sdk';

const sb = new SignalBreak({ apiKey: 'your-api-key' });

const signals = await sb.signals.list({ severity: 'critical' });

OpenAPI Specification (Planned)

Status: Planned for Q2 2026

OpenAPI 3.1 specification will be available at:

https://signalbreak.vercel.app/api/openapi.json

Use Cases:

Auto-generate client libraries
API documentation tools (Swagger UI, Redoc)
API testing tools (Postman, Insomnia)

Workflows & Provider Bindings — Understanding workflows
Provider Signals — Signal intelligence system
Risk Scoring Methodology — How risk scores are calculated
Troubleshooting — Common API issues

Support

API Issues

If you encounter API errors or unexpected behavior:

Check Error Response: Read the error and detail fields
Verify Authentication: Ensure you're logged in (session valid)
Check Feature Limits: Review billing tier limits if receiving 403 errors
Review Rate Limits: Wait if receiving 429 errors
Contact Support: Email support@signalbreak.com with:
- API endpoint
- Request method and body
- Response status code and error message
- Timestamp of request

Feature Requests

Submit feature requests via:

Email: support@signalbreak.com
GitHub: (Link TBD)

Last Updated: 2026-01-26 API Version: v1 Documentation Version: 1.0

API Reference ​

Overview ​

Authentication ​

Session Authentication (Current) ​

Tenant Scoping ​

API Categories ​

Common Patterns ​

Pagination ​

Filtering ​

Error Responses ​

Feature Gates & Billing Limits ​

Workflows ​

List Workflows ​

Get Workflow by ID ​

Create Workflow ​

Update Workflow ​

Delete Workflow ​

Get Workflow Signals ​

Get Workflow Risks ​

Import Workflows (Bulk) ​

Get Workflow Templates ​

Get Workflow Stats ​

Provider Changes (Signals) ​

List Provider Changes ​

Get Provider Change by ID ​

Get Signal Impacts ​

Create Scenario from Signal ​

Scenarios ​

List Scenarios ​

Create Scenario ​

Execute Scenario ​

Get Scenario Mitigations ​

Create Scenario from Signal ​

Get Scenario Templates ​

Providers ​

List Providers ​

Get Provider by ID ​

Get Provider Health ​

Get Provider Products ​

Search Providers ​

Governance ​

Get Governance Scorecard ​

Get Scorecard History ​

List Governance Frameworks ​

Get Frameworks for Domain ​

Get Mitigations for Subdomain ​

Get Provider Concentration ​

Get Risk Radar ​

Generate Evidence Pack ​

Get Tenant Framework Adoption ​

Get Framework Adoption by ID ​

Reports ​

Generate Board Report ​

Generate ISO 42001 Report ​

Generate NIST AI RMF Report ​

Generate EU AI Act Report ​

Generate Operational Report ​

Generate Vendor Risk Report ​

AI Systems ​

List AI Systems ​

Get AI System by ID ​

Import AI Systems ​

Team & Users ​

List Team Members ​

Invite Team Member ​

Get Invite Status ​

Update Team Member Role ​

Remove Team Member ​

Billing ​

Get Billing Status ​

Get Usage Data ​

Get Customer Portal URL ​

Create Checkout Session ​

Settings ​

Get Organisation Settings ​

Update Organisation Settings ​

Update Branding ​

Get Notification Settings ​

Update Notification Settings ​

Security ​

API Reference

Overview

Authentication

Session Authentication (Current)

Tenant Scoping

API Categories

Common Patterns

Pagination

Filtering

Error Responses

Feature Gates & Billing Limits

Workflows

List Workflows

Get Workflow by ID

Create Workflow

Update Workflow

Delete Workflow

Get Workflow Signals

Get Workflow Risks

Import Workflows (Bulk)

Get Workflow Templates

Get Workflow Stats

Provider Changes (Signals)

List Provider Changes

Get Provider Change by ID

Get Signal Impacts

Create Scenario from Signal

Scenarios

List Scenarios

Create Scenario

Execute Scenario

Get Scenario Mitigations

Create Scenario from Signal

Get Scenario Templates

Providers

List Providers

Get Provider by ID

Get Provider Health

Get Provider Products

Search Providers

Governance

Get Governance Scorecard

Get Scorecard History

List Governance Frameworks

Get Frameworks for Domain

Get Mitigations for Subdomain

Get Provider Concentration

Get Risk Radar

Generate Evidence Pack

Get Tenant Framework Adoption

Get Framework Adoption by ID

Reports

Generate Board Report

Generate ISO 42001 Report

Generate NIST AI RMF Report

Generate EU AI Act Report

Generate Operational Report

Generate Vendor Risk Report

AI Systems

List AI Systems

Get AI System by ID

Import AI Systems

Team & Users

List Team Members

Invite Team Member

Get Invite Status

Update Team Member Role

Remove Team Member

Billing

Get Billing Status

Get Usage Data

Get Customer Portal URL

Create Checkout Session

Settings

Get Organisation Settings

Update Organisation Settings

Update Branding

Get Notification Settings

Update Notification Settings

Security