Developer Tools·Intermediate

SDK & API Keys

Use the FinishKit TypeScript SDK for programmatic access to scans, findings, and Intelligence Packs.

The @finishkit/sdk package provides typed access to the FinishKit API. Use it for scripts, CI/CD pipelines, or custom tooling.

Install

npm install @finishkit/sdk

Get an API key

Generate a key from Settings > Developer, or use the CLI:

npx @finishkit/mcp login

API keys start with fk_live_ and are stored at ~/.finishkit/credentials.

Quick example

import { FinishKit } from '@finishkit/sdk'
 
const fk = new FinishKit({ apiKey: process.env.FINISHKIT_API_KEY! })
 
// Scan a connected repo (blocks until complete, typically 2-8 min)
const result = await fk.scan({
  repoOwner: 'myorg',
  repoName: 'myrepo',
  onProgress: (run) => console.log(run.status, run.progress + '%'),
})
 
console.log(`Found ${result.findings.length} issues`)
for (const finding of result.findings) {
  console.log(`[${finding.severity}] ${finding.title}`)
}

Available methods

Projects

const { projects } = await fk.projects.list()
const { project } = await fk.projects.get(projectId)

Runs

const { run } = await fk.runs.create({
  projectId: 'uuid',
  runType: 'baseline',       // 'baseline' | 'pr' | 'manual_patch'
  commitSha: 'abc123',       // optional
})
 
const { run } = await fk.runs.get(runId)
const { findings, patches } = await fk.runs.outcomes(runId)
const { events } = await fk.runs.events(runId, { since: isoString, limit: 100 })
await fk.runs.cancel(runId)

Intelligence

const pack = await fk.intelligence.getPack({
  framework: 'nextjs',
  language: 'typescript',
  packageManager: 'npm',
  integrations: ['supabase', 'stripe'],
})
 
await fk.intelligence.syncFindings({
  projectName: 'my-app',
  agentId: 'claude-code',
  packId: pack.id,
  packVersion: pack.version,
  findings: [...],
  summary: 'Found 12 issues across 4 dimensions',
  startedAt: new Date().toISOString(),
  finishedAt: new Date().toISOString(),
  detectedStack: { framework: 'nextjs', language: 'typescript' },
})

Error handling

import {
  AuthenticationError,   // 401: invalid or expired API key
  BillingError,          // 402: plan limit reached
  NotFoundError,         // 404: resource not found
  RateLimitError,        // 429: too many requests (check retryAfter)
  ValidationError,       // 400: invalid request parameters
  ProjectNotFoundError,  // repo not connected to FinishKit
} from '@finishkit/sdk'

Configuration

Option	Default	Description
`apiKey`	(required)	Your `fk_live_` API key
`baseUrl`	`https://finishkit.app`	Override for staging environments

Never commit API keys to source control. Use environment variables or ~/.finishkit/credentials.

Next step

Intelligence Packs →