AI Reports

Publish AI report results

post

Store AI analysis results from a Hatchet workflow. Called by the workflow after running sfp project:report.

Append-only: Each publish creates a new row (timestamp in key). No upserts.

Retention: Keeps last 10 reports per scope/scopeName combination.

Authorizations

access-token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

repositoryIdentifierstringRequired

Repository identifier (e.g., flxbl-io/sf-core)

Example: flxbl-io/sf-core

scopestring · enumRequired

Analysis scope

Example: domainPossible values:

scopeNamestringRequired

Name of the domain or package analyzed. Use "repository" for repository scope.

Example: sales

commitShastringRequired

Git commit SHA at the time of analysis

Example: 6dcb09b5b57875f334f61aebed695e2e4193db5e

analyzedAtstringRequired

ISO 8601 timestamp of when analysis was performed

Example: 2026-02-25T10:00:00.000Z

statusstring · enumRequired

Analysis status

Possible values:

markdownReportstringRequired

Markdown report content

providerstringOptional

AI provider used (e.g., anthropic, openai)

modelstringOptional

AI model used (e.g., claude-sonnet-4-5-20250929)

executionTimeMsnumberOptional

Total execution time in milliseconds

taskExecutionIdstringOptional

Task execution ID from the Hatchet workflow

Responses

201

Report stored successfully

400

Invalid request body

401

Unauthorized

403

Forbidden - Requires role: application

post

/sfp/api/ai-reports/results

HTTPcURLJavaScriptPython

POST /sfp/api/ai-reports/results HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 298

{
  "repositoryIdentifier": "flxbl-io/sf-core",
  "scope": "domain",
  "scopeName": "sales",
  "commitSha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "analyzedAt": "2026-02-25T10:00:00.000Z",
  "status": "completed",
  "markdownReport": "text",
  "provider": "text",
  "model": "text",
  "executionTimeMs": 1,
  "taskExecutionId": "text"
}

No content

List AI report summaries

get

Retrieve the latest AI report summary per scope/scopeName for a repository. Returns metadata only — no markdown content. Use GET /ai-reports/latest for full report.

Authorizations

access-token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequired

Repository identifier (e.g., flxbl-io/sf-core)

Example: flxbl-io/sf-core

Responses

200

Latest report summary per scope/scopeName

No content

400

Missing repositoryIdentifier

403

Forbidden - Requires role: member, owner, application

get

/sfp/api/ai-reports

HTTPcURLJavaScriptPython

GET /sfp/api/ai-reports?repositoryIdentifier=flxbl-io%2Fsf-core HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get AI report status

get

Check the current status of AI analysis for a specific scope/scopeName. Returns one of: never_ran, generating, completed, or failed. Use this to show real-time status in the UI without triggering a refresh.

Authorizations

access-token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequiredExample: flxbl-io/sf-core

scopestringRequiredExample: domain

scopeNamestringRequiredExample: sales

Responses

200

Current AI report status

No content

400

Missing required query parameters

403

Forbidden - Requires role: member, owner, application

get

/sfp/api/ai-reports/status

HTTPcURLJavaScriptPython

GET /sfp/api/ai-reports/status?repositoryIdentifier=flxbl-io%2Fsf-core&scope=domain&scopeName=sales HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get latest full AI report

get

Retrieve the latest full AI report (including markdown) for a specific scope/scopeName.

Authorizations

access-token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequired

Repository identifier

Example: flxbl-io/sf-core

scopestringRequired

Analysis scope (repository, domain, or package)

Example: domain

scopeNamestringRequired

Scope name (e.g., domain name, package name, or "repository")

Example: sales

Responses

200

Full AI report with markdown

No content

400

Missing required query parameters

403

Forbidden - Requires role: member, owner, application

get

/sfp/api/ai-reports/latest

HTTPcURLJavaScriptPython

GET /sfp/api/ai-reports/latest?repositoryIdentifier=flxbl-io%2Fsf-core&scope=domain&scopeName=sales HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get AI report history

get

Retrieve historical report metadata (no markdown) for a specific scope/scopeName. Useful for showing a timeline of past analyses.

Authorizations

access-token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequired

Repository identifier

Example: flxbl-io/sf-core

scopestringRequired

Analysis scope

Example: domain

scopeNamestringRequired

Scope name

Example: sales

limitnumberOptional

Maximum results to return (default: 10, max: 100)

Responses

200

Historical report metadata

No content

400

Missing required query parameters

403

Forbidden - Requires role: member, owner, application

get

/sfp/api/ai-reports/history

HTTPcURLJavaScriptPython

GET /sfp/api/ai-reports/history?repositoryIdentifier=flxbl-io%2Fsf-core&scope=domain&scopeName=sales HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Trigger AI report refresh

post

Trigger a new AI analysis via Hatchet workflow. Returns a task execution ID for tracking.

Cost-aware: AI tokens are expensive. Reports are only generated on explicit user request — no auto-trigger.

Authorizations

access-token

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

repositoryIdentifierstringRequired

Repository identifier

Example: flxbl-io/sf-core

scopestringRequired

Analysis scope

Example: domain

scopeNamestringRequired

Scope name

Example: sales

modelanyOptional

AI model to use

provideranyOptional

AI provider to use

forcebooleanOptional

Force re-analysis even if a completed report exists for the current commit (default: false)

Responses

202

Refresh triggered or skipped if report already exists for HEAD commit

400

Missing required query parameters

403

Forbidden - Requires role: member, owner

409

An AI report generation is already in progress for this scope

post

/sfp/api/ai-reports/refresh

HTTPcURLJavaScriptPython

POST /sfp/api/ai-reports/refresh?repositoryIdentifier=flxbl-io%2Fsf-core&scope=domain&scopeName=sales HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content