{ "openapi": "3.0.4", "info": { "title": "Flowcerta API", "description": "Public HTTP API for Flowcerta — the automation governance control plane.\n\n**What's covered here:**\n- `POST /api/v1/validate` — authenticated workflow validation for CI/CD pipelines and integrations\n- `POST /api/v1/demo/validate` — anonymous free-scan endpoint that backs flowcerta.com/scan/\n- `GET /api/v1/demo/scan/{token}` — fetch a persisted free-scan report\n- `POST /api/v1/demo/leads` — email capture from the /scan email gate\n\nInternal admin, billing, dashboard, and tenancy endpoints are intentionally not included in this spec.\n\n**Auth:** Bearer JWT (Supabase) or API key (`Authorization: ApiKey fc_...`). All authenticated endpoints additionally require the `X-Org-Id` header.\n\n**Errors:** every non-2xx response has the shape `{ \"error\": { \"code\": \"STABLE_CODE\", \"message\": \"...\", \"docs_url\": \"...\" } }`.", "contact": { "name": "Flowcerta", "url": "https://flowcerta.com/contact/", "email": "sales@flowcerta.com" }, "license": { "name": "Commercial — see Master Service Agreement", "url": "https://flowcerta.com/terms/" }, "version": "v1" }, "servers": [ { "url": "https://api.flowcerta.com", "description": "Production" } ], "paths": { "/api/v1/demo/validate": { "post": { "tags": [ "Free Scanner" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } } }, "encoding": { "file": { "style": "form" } } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DemoScanResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DemoScanResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DemoScanResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } }, "408": { "description": "Request Timeout", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } }, "413": { "description": "Content Too Large", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } } } } }, "/api/v1/demo/scan/{token}": { "get": { "tags": [ "Free Scanner" ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DemoScanResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DemoScanResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DemoScanResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } } } } }, "/api/v1/demo/leads": { "post": { "tags": [ "Free Scanner" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDemoLeadRequest" } }, "text/json": { "schema": { "$ref": "#/components/schemas/CreateDemoLeadRequest" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/CreateDemoLeadRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DemoLeadResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DemoLeadResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DemoLeadResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } }, "404": { "description": "Not Found", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } } } } }, "/api/v1/validate/project": { "post": { "tags": [ "ProjectValidation" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "source": { "type": "string" }, "metadata": { "type": "string" } } }, "encoding": { "file": { "style": "form" }, "source": { "style": "form" }, "metadata": { "style": "form" } } } } }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/validate/project/{id}": { "get": { "tags": [ "ProjectValidation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/validate": { "post": { "tags": [ "Validation" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "platform": { "type": "string" }, "enforcement_mode": { "type": "string" }, "ruleset": { "type": "string" }, "policy_pack": { "type": "string" }, "environment": { "type": "string" }, "label": { "type": "string" }, "source": { "type": "string" }, "metadata": { "type": "string" }, "async": { "type": "boolean", "default": false } } }, "encoding": { "file": { "style": "form" }, "platform": { "style": "form" }, "enforcement_mode": { "style": "form" }, "ruleset": { "style": "form" }, "policy_pack": { "style": "form" }, "environment": { "style": "form" }, "label": { "style": "form" }, "source": { "style": "form" }, "metadata": { "style": "form" }, "async": { "style": "form" } } } } }, "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } } } }, "422": { "description": "Unprocessable Content", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } } } }, "400": { "description": "Bad Request", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } }, "401": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } }, "402": { "description": "Payment Required", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } }, "403": { "description": "Forbidden", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } }, "413": { "description": "Content Too Large", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ApiErrorPayload" } } } } } } }, "/api/v1/validate/async": { "post": { "tags": [ "Validation" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "platform": { "type": "string" }, "enforcement_mode": { "type": "string" }, "ruleset": { "type": "string" }, "policy_pack": { "type": "string" }, "environment": { "type": "string" }, "label": { "type": "string" }, "source": { "type": "string" }, "metadata": { "type": "string" }, "webhook_url": { "type": "string" } } }, "encoding": { "file": { "style": "form" }, "platform": { "style": "form" }, "enforcement_mode": { "style": "form" }, "ruleset": { "style": "form" }, "policy_pack": { "style": "form" }, "environment": { "style": "form" }, "label": { "style": "form" }, "source": { "style": "form" }, "metadata": { "style": "form" }, "webhook_url": { "style": "form" } } } } }, "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "ApiErrorBody": { "type": "object", "properties": { "code": { "type": "string", "nullable": true }, "message": { "type": "string", "nullable": true }, "docsUrl": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ApiErrorPayload": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiErrorBody" } }, "additionalProperties": false }, "CreateDemoLeadRequest": { "type": "object", "properties": { "email": { "type": "string", "nullable": true }, "scanToken": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true } }, "additionalProperties": false }, "DemoFindingPayload": { "type": "object", "properties": { "severity": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "rule": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true } }, "additionalProperties": false }, "DemoFindingSummary": { "type": "object", "properties": { "critical": { "type": "integer", "format": "int32" }, "high": { "type": "integer", "format": "int32" }, "medium": { "type": "integer", "format": "int32" }, "low": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "DemoLeadResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "nullable": true }, "scanToken": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "DemoScanResponse": { "type": "object", "properties": { "shareToken": { "type": "string", "nullable": true }, "score": { "type": "integer", "format": "int32" }, "passed": { "type": "boolean" }, "platform": { "type": "string", "nullable": true }, "fileName": { "type": "string", "nullable": true }, "enforcementMode": { "type": "string", "nullable": true }, "validatedAt": { "type": "string", "format": "date-time" }, "summary": { "$ref": "#/components/schemas/DemoFindingSummary" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/DemoFindingPayload" }, "nullable": true } }, "additionalProperties": false }, "ValidateBlockingFinding": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "severity": { "type": "string", "nullable": true }, "rule": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "sourceXPath": { "type": "string", "nullable": true }, "sourceLineNumber": { "type": "integer", "format": "int32", "nullable": true }, "detectorId": { "type": "string", "nullable": true }, "exceptionId": { "type": "string", "nullable": true }, "exceptionStatus": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ValidateDiff": { "type": "object", "properties": { "isRegression": { "type": "boolean" }, "newFindingsCount": { "type": "integer", "format": "int32" }, "resolvedFindingsCount": { "type": "integer", "format": "int32" }, "unchangedFindingsCount": { "type": "integer", "format": "int32" }, "severityChangedCount": { "type": "integer", "format": "int32" }, "waiverChangedCount": { "type": "integer", "format": "int32" }, "scoreDelta": { "type": "integer", "format": "int32", "nullable": true }, "previousScore": { "type": "integer", "format": "int32", "nullable": true }, "previousValidatedAt": { "type": "string", "format": "date-time", "nullable": true }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/ValidateDiffChange" }, "nullable": true } }, "additionalProperties": false }, "ValidateDiffChange": { "type": "object", "properties": { "ruleId": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "fileName": { "type": "string", "nullable": true }, "currentSeverity": { "type": "string", "nullable": true }, "previousSeverity": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ValidateFinding": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "catalogRuleId": { "type": "string", "nullable": true }, "severity": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "rule": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "remediation": { "type": "string", "nullable": true }, "complianceTags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "sourceXPath": { "type": "string", "nullable": true }, "sourceLineNumber": { "type": "integer", "format": "int32", "nullable": true }, "detectorId": { "type": "string", "nullable": true }, "exceptionId": { "type": "string", "nullable": true }, "exceptionStatus": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ValidateFindingSummary": { "type": "object", "properties": { "critical": { "type": "integer", "format": "int32" }, "high": { "type": "integer", "format": "int32" }, "medium": { "type": "integer", "format": "int32" }, "low": { "type": "integer", "format": "int32" }, "total": { "type": "integer", "format": "int32" } }, "additionalProperties": false }, "ValidatePipelineContext": { "type": "object", "properties": { "provider": { "type": "string", "nullable": true }, "host": { "type": "string", "nullable": true }, "repository": { "type": "string", "nullable": true }, "branch": { "type": "string", "nullable": true }, "commit": { "type": "string", "nullable": true }, "prUrl": { "type": "string", "nullable": true }, "workflowRunUrl": { "type": "string", "nullable": true }, "definitionName": { "type": "string", "nullable": true }, "buildNumber": { "type": "string", "nullable": true }, "pipelineName": { "type": "string", "nullable": true }, "stageName": { "type": "string", "nullable": true }, "deploymentId": { "type": "string", "nullable": true }, "solutionName": { "type": "string", "nullable": true }, "solutionVersion": { "type": "string", "nullable": true }, "environmentName": { "type": "string", "nullable": true }, "environmentId": { "type": "string", "nullable": true }, "deploymentUrl": { "type": "string", "nullable": true } }, "additionalProperties": false }, "ValidateResponse": { "type": "object", "properties": { "validationId": { "type": "string", "format": "uuid" }, "orgId": { "type": "string", "format": "uuid" }, "passed": { "type": "boolean" }, "score": { "type": "integer", "format": "int32" }, "enforcementMode": { "type": "string", "nullable": true }, "platform": { "type": "string", "nullable": true }, "ruleset": { "type": "string", "nullable": true }, "policyPackId": { "type": "string", "format": "uuid", "nullable": true }, "policyPackSlug": { "type": "string", "nullable": true }, "filename": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true }, "summary": { "$ref": "#/components/schemas/ValidateFindingSummary" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidateFinding" }, "nullable": true }, "blockingFindings": { "type": "array", "items": { "$ref": "#/components/schemas/ValidateBlockingFinding" }, "nullable": true }, "pipeline": { "$ref": "#/components/schemas/ValidatePipelineContext" }, "validatedAt": { "type": "string", "format": "date-time" }, "validationMs": { "type": "integer", "format": "int64" }, "ownerId": { "type": "string", "nullable": true }, "ownerName": { "type": "string", "nullable": true }, "diff": { "$ref": "#/components/schemas/ValidateDiff" }, "reportUrl": { "type": "string", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "bearerAuth": { "type": "http", "description": "Supabase-issued JWT. Send as `Authorization: Bearer `.", "scheme": "bearer", "bearerFormat": "JWT" }, "apiKeyAuth": { "type": "apiKey", "description": "Send as `Authorization: ApiKey fc_live_…`. Mutually exclusive with bearer auth.", "name": "Authorization", "in": "header" } } }, "tags": [ { "name": "Free Scanner" }, { "name": "ProjectValidation" }, { "name": "Validation" } ] }