API-First Quickstart

This guide walks you through the Forgecroft API using curl. By the end you’ll have evaluated a diff against your organization’s Controls and read the verdict. Everything here also works with the Go SDK and CLI.

Prerequisites

• A Forgecroft account with an API key carrying evaluate:read scope (create one in the console under Settings → API Keys, or via the OAuth flow). A broad codebases:read key also works.
• A repository with a change you want evaluated.

Set your API key and base URL:

export FC_API=https://api.forgecroft.com
export FC_KEY=fc_live_...

Verify your identity

curl -s -H "Authorization: Bearer $FC_KEY" $FC_API/whoami | jq .

Evaluate a diff

The core endpoint is POST /evaluate. Send it the unified diff of your change with kind=pr_diff; Forgecroft matches your changed paths to the covering Components, applies your Controls, and returns a deterministic verdict. No LLM runs on this path — the same diff always returns the same decision.

DIFF=$(git diff origin/main...HEAD)

curl -s -X POST \
  -H "Authorization: Bearer $FC_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg d "$DIFF" '{kind: "pr_diff", diff: $d}')" \
  $FC_API/evaluate | jq .

POST /evaluate accepts five input kinds — pr_diff, config_change, deploy_event, iam_update, and schema_migration. kind defaults to pr_diff when omitted.

Read the verdict

The response is the decision plus its supporting context:

curl -s -X POST \
  -H "Authorization: Bearer $FC_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg d "$DIFF" '{kind: "pr_diff", diff: $d}')" \
  $FC_API/evaluate | jq '{decision, blast_radius, confidence, coverage_notes, findings}'

The decision is one of four states:

Decision	Meaning
go	No Control was violated; the change is clear to merge.
conditional_go	Allowed, but a finding needs attention or an approval.
no_go	A Control blocks the change. Produce a different change, or request a time-bound Exception.
insufficient_context	The graph could not be resolved confidently. Returns empty plus a coverage note rather than a false go.

Each entry in findings carries a severity, a message, and a fix_hint an agent or author can act on. blast_radius reflects the Components your change touches; if your system map is unseeded it reports honest empty coverage (import_graph_not_built).

Offline pre-check (no key, no network)

To evaluate a diff without sending it anywhere, use the gate binary in offline mode against the embedded best-practice packs:

forgecroft-gate --diff <(git diff) --offline --json

An offline go checks the generic packs only — it does not consult your org’s Controls, Exceptions, or blast radius. A change that is go offline can still be blocked by a Control in hosted mode.

Creating a CI-scoped API key

For CI/CD pipelines, create a narrowly-scoped key:

curl -s -X POST \
  -H "Authorization: Bearer $FC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline",
    "scope_type": "org",
    "action_scope": "read",
    "scopes": ["evaluate"]
  }' \
  $FC_API/api-keys | jq .

This key can evaluate diffs and read verdicts but cannot approve runs, manage API keys, or access other resources. See API Keys for the full scope reference.

What’s next

• CI Gate — drop the same evaluation into GitHub Actions
• Coding Agents — call forgecroft_evaluate in-loop from Claude Code, Codex, or Cursor
• CLI Reference — manage evaluations from the command line
• Go SDK — build integrations in Go