API Validation

Validate workflows from CI/CD without guessing the setup.

Flowcerta's validation API lets you submit workflow files from pipelines, receive a structured score plus findings, and review API or CI/CD runs in the same Validations feed your team already uses.

Base endpointhttps://app.flowcerta.com/api/v1/validate
  • Auth: Authorization: ApiKey <key>
  • Content type: multipart form-data
  • Pass status: 200
  • Blocking findings: 422
  • Metadata field: metadata JSON string, max 4096 bytes
01

Create an API key

In the app, open Team, go to API Keys, and create a key with analysis:write for pipeline submissions.

02

Store it in your CI secret manager

Use a secret such as FLOWCERTA_API_KEY. Do not check raw keys into the repository.

03

Post the workflow file

Send the file and platform as multipart fields to /api/v1/validate, tag CI runs with source=cicd, and attach pipeline context through metadata.

04

Review the result

Every run lands in the Validations feed with its source label, score, summary, and any available pipeline context.

cURLManual Smoke Test

Try one validation first

Use this command to verify the key, endpoint, and file packaging before you wire it into your pipeline.

curl -X POST "https://app.flowcerta.com/api/v1/validate" \
  -H "Authorization: ApiKey $FLOWCERTA_API_KEY" \
  -F "file=@Main.xaml" \
  -F "platform=uipath" \
  -F "source=cicd" \
  -F "label=manual smoke test" \
  -F 'metadata={
    "provider":"manual",
    "pipeline":{
      "repository":"contoso/rpa-bots",
      "branch":"main",
      "commit":"a3f8b2c"
    }
  }'
GitHub ActionsCI example

Drop into a workflow job

Build the metadata JSON from the GitHub context, post the file, and let Flowcerta return pass or fail status. enforcement_mode=blocking causes a 422 on critical or high findings, which fails the job automatically.

- name: Validate workflow with Flowcerta
  env:
    FLOWCERTA_API_KEY: ${{ secrets.FLOWCERTA_API_KEY }}
  run: |
    PR_URL=""
    if [ "${{ github.event_name }}" = "pull_request" ]; then
      PR_URL="https://github.com/${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
    fi

    METADATA=$(jq -nc \
      --arg repo "${{ github.repository }}" \
      --arg branch "${{ github.ref_name }}" \
      --arg commit "${{ github.sha }}" \
      --arg prUrl "$PR_URL" \
      --arg workflowRunUrl "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
      '{
        provider: "github-actions",
        pipeline: {
          provider: "github-actions",
          repository: $repo,
          branch: $branch,
          commit: ($commit[0:7]),
          prUrl: ($prUrl | select(. != "")),
          workflowRunUrl: $workflowRunUrl
        }
      }')

    curl -X POST "https://app.flowcerta.com/api/v1/validate" \
      -H "Authorization: ApiKey $FLOWCERTA_API_KEY" \
      -F "file=@workflows/Main.xaml" \
      -F "platform=uipath" \
      -F "source=cicd" \
      -F "enforcement_mode=blocking" \
      -F "label=${{ github.workflow }} #${{ github.run_number }}" \
      -F "metadata=$METADATA"
Power PlatformPipeline extension flow

Send deployment context from a pipeline-triggered flow

Use a Power Automate extension flow around Power Platform Pipelines, compose the metadata JSON from the trigger payload, and post it with the exported solution or workflow package.

Flowcerta validation trigger inside a Power Platform pipeline extension flow:

1. Trigger: "When a pipeline deployment completes"
2. Compose metadata JSON:

{
  "provider": "power_platform",
  "pipeline": {
    "provider": "power_platform",
    "host": "power-platform-pipelines",
    "pipeline_name": "@{triggerBody()?['pipeline']?['name']}",
    "stage_name": "@{triggerBody()?['stage']?['name']}",
    "deployment_id": "@{triggerBody()?['deployment']?['id']}",
    "solution_name": "@{triggerBody()?['solution']?['uniqueName']}",
    "solution_version": "@{triggerBody()?['solution']?['version']}",
    "environment_name": "@{triggerBody()?['targetEnvironment']?['displayName']}",
    "environment_id": "@{triggerBody()?['targetEnvironment']?['id']}",
    "deployment_url": "@{triggerBody()?['deployment']?['link']}"
  }
}

3. HTTP action -> POST https://app.flowcerta.com/api/v1/validate
   Headers:
     Authorization: ApiKey <FLOWCERTA_API_KEY>
   Body form-data:
     file: exported workflow package
     platform: power_automate
     source: cicd
     enforcement_mode: blocking
     label: @{triggerBody()?['pipeline']?['name']} / @{triggerBody()?['stage']?['name']}
     metadata: <Compose output>
metadataGitHub Actions shape

Canonical GitHub pipeline payload

These field names map directly to the pipeline context shown in the Validations feed and result detail page.

{
  "provider": "github-actions",
  "pipeline": {
    "provider": "github-actions",
    "repository": "contoso/rpa-bots",
    "branch": "feature/invoice-v4",
    "commit": "a3f8b2c",
    "prUrl": "https://github.com/contoso/rpa-bots/pull/142",
    "workflowRunUrl": "https://github.com/contoso/rpa-bots/actions/runs/9001"
  }
}
metadataPower Platform shape

Canonical Power Platform payload

Use this shape for Power Platform pipeline extension flows so deployment, solution, and target environment context survive into Flowcerta.

{
  "provider": "power_platform",
  "pipeline": {
    "provider": "power_platform",
    "host": "power-platform-pipelines",
    "pipeline_name": "Core ALM Pipeline",
    "stage_name": "QA",
    "deployment_id": "dep-12345",
    "solution_name": "Contoso.InvoiceAutomation",
    "solution_version": "1.4.2.0",
    "environment_name": "Contoso QA",
    "environment_id": "11111111-2222-3333-4444-555555555555",
    "deployment_url": "https://make.powerapps.com/environments/11111111-2222-3333-4444-555555555555/pipelines/deployments/dep-12345"
  }
}
200 OKPass response

Workflow passed

No blocking findings. The job continues. Findings below the blocking threshold are still returned for review, and pipeline context is echoed back for traceability.

HTTP/1.1 200 OK
{
  "validation_id": "3fa1c2d4-8b7e-4a3f-9c1d-e2f567890abc",
  "org_id": "11111111-2222-3333-4444-555555555555",
  "passed": true,
  "score": 91,
  "enforcement_mode": "blocking",
  "platform": "uipath",
  "summary": {
    "critical": 0,
    "high": 0,
    "medium": 1,
    "low": 0,
    "total": 1
  },
  "pipeline": {
    "provider": "github-actions",
    "repository": "contoso/rpa-bots",
    "branch": "main",
    "commit": "a3f8b2c",
    "workflowRunUrl": "https://github.com/contoso/rpa-bots/actions/runs/9001"
  },
  "findings": [
    {
      "id": "ERR-001",
      "severity": "medium",
      "description": "Activity sequence lacks retry scope",
      "location": "Main.xaml > Process > Sequence",
      "compliance_tags": [],
      "exception_status": "none"
    }
  ],
  "blocking_findings": [],
  "validated_at": "2025-04-01T09:00:00Z",
  "validation_ms": 312,
  "report_url": "https://app.flowcerta.com/results/3fa1c2d4-8b7e-4a3f-9c1d-e2f567890abc"
}
422Blocking response

Workflow blocked

One or more critical or high-severity findings are present. The blocking_findings array names each one. The non-zero HTTP status fails the pipeline job.

HTTP/1.1 422 Unprocessable Entity
{
  "validation_id": "a7b3e9f1-2c4d-5e6f-7a8b-9c0d1e2f3a4b",
  "passed": false,
  "score": 34,
  "enforcement_mode": "blocking",
  "summary": {
    "critical": 1,
    "high": 2,
    "medium": 1,
    "low": 0,
    "total": 4
  },
  "findings": [ ... ],
  "blocking_findings": [
    {
      "id": "CRED-002",
      "severity": "critical",
      "description": "Hardcoded password detected in Assign activity",
      "location": "Main.xaml > Process > Sequence > Assign",
      "exception_id": null,
      "exception_status": "none"
    }
  ],
  "validated_at": "2025-04-01T09:01:00Z",
  "report_url": "https://app.flowcerta.com/results/a7b3e9f1-2c4d-5e6f-7a8b-9c0d1e2f3a4b"
}

enforcement_mode values

advisoryObserve only

Always 200

Findings are returned in full but the pipeline is never blocked. Use this when first integrating to baseline your estate without failing builds.

warningSoft gate

200 with findings flagged

Returns 200 even on high-severity findings. The response body includes all findings and a non-zero risk score. Useful for visibility without breaking CI.

blockingHard gate

422 on critical or high

Returns 422 when any critical or high-severity findings are present. The non-zero HTTP status fails the pipeline job automatically. Recommended for production gate checks.

RequiredMultipart Fields

What to send

file and platform are required.

platform must be one of uipath, power_automate, aa, or blue_prism.

Useful optional fields are source, label, ruleset, enforcement_mode, and metadata.

BehaviorResponse Model

What comes back

Every response includes a validation ID, score, summary counts, and structured findings.

If metadata includes pipeline context, the response includes a normalized pipeline object that the dashboard renders directly.

ReviewApp Workflow

Where teams look next

CI/API runs show up in the app's Validations feed, where reviewers can inspect findings, compare runs, and jump into pipeline context.

Next Step

Start in the app, then wire the same call into CI.

The lowest-friction path is to create a key, test the endpoint with one file, then move that exact command into GitHub Actions or another runner.

Open AppTalk to Flowcerta