API Documentation
Integrate SamuAI scans into your CI/CD pipeline, dashboards, or security workflows.
The Scan API requires a Pro or Org plan. Lookup, Catalog, and Badge endpoints are free. View plans
Base URL
https://www.samuai.devAuthentication
The Scan API authenticates via API key. Pass it in one of two ways:
Header (recommended)
x-api-key: aisk_your_key_hereAuthorization header
Authorization: Bearer aisk_your_key_hereGenerate API keys in Settings → API Keys. Each key has configurable scopes and rate limits.
Rate Limits
Rate limit headers are included on every response:
X-RateLimit-Limitheader
Max requests per hour for your plan
X-RateLimit-Remainingheader
Requests remaining in the current window
X-RateLimit-Resetheader
Unix timestamp when the window resets
Retry-Afterheader
Seconds to wait (only on 429 responses)
Errors
All errors return JSON with an error field:
{
"error": "API key required. Pass via x-api-key header or Authorization: Bearer aisk_..."
}400status
Invalid request body or parameters
401status
Missing or invalid API key
403status
API key lacks required scope
429status
Rate limit exceeded
502status
Upstream scan failure (e.g., store unavailable)
Tool Types
SamuAI auto-detects the tool type from the input. You can also force it:
chrometype
32-char ID or Chrome Web Store URL
vscodetype
publisher.extension format (e.g.,
ms-python.python)npmtype
npm package name (e.g.,
express)mcptype
MCP server package name