Skip to main content

​
Security API reference

Base URL: https://api.withfoundry.ai
Auth: Authorization: Bearer key_... All responses use the envelope { success, data, meta: { requestId } }.

​
Start scan

POST /v1/security/scan Start a security scan for a repository. Request body
FieldTypeRequiredDescription
repoUrlstringYesClone URL (e.g. https://github.com/org/repo).
branchstringNoBranch or ref to scan (default: default branch).
waitForCompletionbooleanNoIf true, long-poll until done and return findings in response.
Response data
FieldTypeDescription
scanIdstringId to fetch result (e.g. scan_...).
statusstringpending | running | completed | failed.
findingsarrayPresent when waitForCompletion: true and status is completed.
Example 
curl -X POST https://api.withfoundry.ai/v1/security/scan \
  -H "Authorization: Bearer key_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoUrl":"https://github.com/your-org/your-repo","branch":"main"}'

​
Get scan result

GET /v1/security/scan/:scanId Retrieve scan status and findings. Path
ParamDescription
scanIdId returned from POST /v1/security/scan.
Response data
FieldTypeDescription
scanIdstringSame as path.
statusstringpending | running | completed | failed.
findingsarrayList of findings when status is completed.
errorstringOptional; set when status is failed.
Finding object
FieldTypeDescription
idstringFinding id.
severitystringcritical | high | medium | low | info.
titlestringShort title.
descriptionstringDetailed description.
filestringFile path in repo.
linenumberLine number.
suggestionstringOptional remediation.
Example 
curl -H "Authorization: Bearer key_YOUR_KEY" \
  "https://api.withfoundry.ai/v1/security/scan/scan_abc123"