Complete REST API Endpoints

<h2 id="bkmrk-rest-api-endpoints-%E2%80%94">REST API Endpoints — SecuScan v0.28.0</h2>

<p id="bkmrk-the-secuscan-api-exp">The SecuScan API exposes 100+ REST endpoints, all protected by JWT or API key authentication, with multi-tenant isolation via PostgreSQL RLS.</p>

<p id="bkmrk-base-url%3A-https%3A%2F%2Fap"><strong>Base URL</strong>: <code>https://api.secuscan.secuaas.dev/v1&lt;/code> (dev) / <code>https://api.secuscan.secuaas.ovh/v1&lt;/code> (prod)</p>

<h3 id="bkmrk-authentication-%28%2Fv1%2F">Authentication (/v1/auth/*)</h3> <table id="bkmrk-methodendpointauthde"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>POST</td><td>/auth/register</td><td>No</td><td>Register with email and password (creates tenant + user)</td></tr> <tr><td>POST</td><td>/auth/login</td><td>No</td><td>Login (returns access + refresh JWT tokens)</td></tr> <tr><td>POST</td><td>/auth/refresh</td><td>No</td><td>Refresh access token</td></tr> <tr><td>POST</td><td>/auth/sso/zitadel</td><td>No</td><td>SSO login via Zitadel (OIDC)</td></tr> <tr><td>POST</td><td>/auth/verify-email</td><td>No</td><td>Email verification (Resend API)</td></tr> <tr><td>POST</td><td>/auth/forgot-password</td><td>No</td><td>Password reset request</td></tr> <tr><td>POST</td><td>/auth/reset-password</td><td>No</td><td>Password reset</td></tr> </tbody> </table>

<h3 id="bkmrk-targets-%28%2Fv1%2Ftargets">Targets (/v1/targets/*)</h3> <table id="bkmrk-methodendpointauthde-1"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/targets</td><td>JWT</td><td>List tenant targets</td></tr> <tr><td>POST</td><td>/targets</td><td>JWT</td><td>Create a target (domain, IP)</td></tr> <tr><td>GET</td><td>/targets/{id}</td><td>JWT</td><td>Target details</td></tr> <tr><td>PUT</td><td>/targets/{id}</td><td>JWT</td><td>Update a target</td></tr> <tr><td>DELETE</td><td>/targets/{id}</td><td>JWT</td><td>Delete a target</td></tr> <tr><td>POST</td><td>/targets/{id}/schedule</td><td>JWT</td><td>Schedule recurring scan (cron)</td></tr> </tbody> </table>

<h3 id="bkmrk-network-scans-%28%2Fv1%2Fs">Network Scans (/v1/scans/*)</h3> <table id="bkmrk-methodendpointauthde-2"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/scans</td><td>JWT</td><td>List scans</td></tr> <tr><td>POST</td><td>/scans</td><td>JWT</td><td>Launch a scan (full, quick, port_scan, vuln_scan, dns_audit, etc.)</td></tr> <tr><td>GET</td><td>/scans/{id}</td><td>JWT</td><td>Scan details + progress</td></tr> <tr><td>DELETE</td><td>/scans/{id}</td><td>JWT</td><td>Delete a scan</td></tr> <tr><td>GET</td><td>/scans/{id}/progress</td><td>JWT</td><td>Real-time progress</td></tr> </tbody> </table>

<h3 id="bkmrk-findings-%28%2Fv1%2Ffindin">Findings (/v1/findings/*)</h3> <table id="bkmrk-methodendpointauthde-3"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/findings</td><td>JWT</td><td>List findings with filters (severity, category, status)</td></tr> <tr><td>GET</td><td>/findings/{id}</td><td>JWT</td><td>Finding details</td></tr> <tr><td>PUT</td><td>/findings/{id}</td><td>JWT</td><td>Update (status, notes)</td></tr> <tr><td>POST</td><td>/findings/ai-analyze</td><td>JWT</td><td>AI batch analysis (max 500 findings, Claude AI)</td></tr> <tr><td>GET</td><td>/findings/export/csv</td><td>JWT</td><td>CSV export</td></tr> <tr><td>PUT</td><td>/findings/bulk-update</td><td>JWT</td><td>Bulk update</td></tr> </tbody> </table>

<h3 id="bkmrk-reports-%28%2Fv1%2Freports">Reports (/v1/reports/*)</h3> <table id="bkmrk-methodendpointauthde-4"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/reports</td><td>JWT</td><td>List reports</td></tr> <tr><td>POST</td><td>/reports</td><td>JWT</td><td>Generate a PDF report</td></tr> <tr><td>GET</td><td>/reports/{id}/download</td><td>JWT</td><td>Download with signed URL</td></tr> </tbody> </table>

<h3 id="bkmrk-code-repositories-%28%2F">Code Repositories (/v1/code-repositories/*)</h3> <table id="bkmrk-methodendpointauthde-5"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/code-repositories</td><td>JWT</td><td>List Git repositories</td></tr> <tr><td>POST</td><td>/code-repositories</td><td>JWT</td><td>Add a repository (GitHub, GitLab, Bitbucket)</td></tr> <tr><td>GET</td><td>/code-repositories/{id}</td><td>JWT</td><td>Repository details</td></tr> <tr><td>PUT</td><td>/code-repositories/{id}</td><td>JWT</td><td>Update</td></tr> <tr><td>DELETE</td><td>/code-repositories/{id}</td><td>JWT</td><td>Delete</td></tr> </tbody> </table>

<h3 id="bkmrk-code-scans-%28%2Fv1%2Fcode">Code Scans (/v1/code-scans/*)</h3> <table id="bkmrk-methodendpointauthde-6"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/code-scans</td><td>JWT</td><td>List code scans (includes app_version and version_tag)</td></tr> <tr><td>POST</td><td>/code-scans</td><td>JWT</td><td>Launch a code scan</td></tr> <tr><td>GET</td><td>/code-scans/{id}</td><td>JWT</td><td>Scan details (with version and tag)</td></tr> <tr><td>POST</td><td>/code-scans/{id}/ai-report</td><td>JWT</td><td>Generate AI remediation report (async)</td></tr> <tr><td>GET</td><td>/code-scans/{id}/ai-report</td><td>JWT</td><td>Retrieve AI report</td></tr> </tbody> </table>

<h3 id="bkmrk-false-positive-suppr">False Positive Suppressions (/v1/code-scans/* — v0.28.0)</h3> <p id="bkmrk-new-in-v0.28.0-%E2%80%94-fal"><em>New in v0.28.0</em> — False positive management system with SHA256 fingerprinting for cross-scan persistence.</p> <table id="bkmrk-methodendpointauthde-7"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>POST</td><td>/code-scans/issues/{id}/suppress</td><td>JWT</td><td>Suppress/accept an issue (creates SHA256 fingerprint)</td></tr> <tr><td>DELETE</td><td>/code-scans/suppressions/{id}</td><td>JWT</td><td>Remove a suppression (issue reappears in next scans)</td></tr> <tr><td>GET</td><td>/code-scans/repositories/{id}/suppressions</td><td>JWT</td><td>List all suppressions for a repository</td></tr> <tr><td>POST</td><td>/code-scans/{id}/apply-suppressions</td><td>JWT</td><td>Auto-apply existing suppressions to scan issues</td></tr> </tbody> </table> <p id="bkmrk-suppression-statuses"><strong>Suppression statuses</strong>: <code>false_positive</code> (confirmed false positive), <code>accepted_risk</code> (accepted risk), <code>wont_fix</code> (will not be fixed).</p> <p id="bkmrk-fingerprint%3A-sha256%28"><strong>Fingerprint</strong>: <code>SHA256(repository_id|tool|rule_id|category|title|file_path)</code> — allows matching the same issue across scans even if line numbers change.</p>

<h3 id="bkmrk-code-issues-%28%2Fv1%2Fcod">Code Issues (/v1/code-issues/*)</h3> <table id="bkmrk-methodendpointauthde-8"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/code-issues</td><td>JWT</td><td>List with filters (severity, category, CWE)</td></tr> <tr><td>GET</td><td>/code-issues/{id}</td><td>JWT</td><td>Issue details</td></tr> <tr><td>PUT</td><td>/code-issues/{id}</td><td>JWT</td><td>Update status</td></tr> </tbody> </table>

<h3 id="bkmrk-ssh-keys-%28%2Fv1%2Fssh-ke">SSH Keys (/v1/ssh-keys/*)</h3> <table id="bkmrk-methodendpointauthde-9"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/ssh-keys</td><td>JWT</td><td>List SSH keys (AES-GCM encrypted)</td></tr> <tr><td>POST</td><td>/ssh-keys</td><td>JWT</td><td>Add an SSH key</td></tr> <tr><td>DELETE</td><td>/ssh-keys/{id}</td><td>JWT</td><td>Delete a key</td></tr> </tbody> </table>

<h3 id="bkmrk-pentests-%28%2Fv1%2Fpentes">Pentests (/v1/pentests/*)</h3> <table id="bkmrk-methodendpointauthde-10"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/pentests/authorizations</td><td>JWT</td><td>List legal authorizations</td></tr> <tr><td>POST</td><td>/pentests/authorizations</td><td>JWT</td><td>Create an authorization</td></tr> <tr><td>GET</td><td>/pentests/runs</td><td>JWT</td><td>List pentest runs</td></tr> <tr><td>POST</td><td>/pentests/runs</td><td>JWT</td><td>Launch an AI pentest (Claude AI + Temporal)</td></tr> <tr><td>GET</td><td>/pentests/runs/{id}</td><td>JWT</td><td>Run details + status</td></tr> <tr><td>GET</td><td>/pentests/runs/{id}/findings</td><td>JWT</td><td>Pentest findings</td></tr> </tbody> </table>

<h3 id="bkmrk-agents-%28%2Fv1%2Fagents%2F%2A">Agents (/v1/agents/*)</h3> <table id="bkmrk-methodendpointauthde-11"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/agents</td><td>JWT</td><td>List agents</td></tr> <tr><td>POST</td><td>/agents/register</td><td>API Key</td><td>Register a new agent</td></tr> <tr><td>POST</td><td>/agents/{id}/heartbeat</td><td>API Key</td><td>Heartbeat signal</td></tr> <tr><td>GET</td><td>/agents/{id}/inventory</td><td>JWT</td><td>System inventory</td></tr> <tr><td>POST</td><td>/agents/{id}/inventory</td><td>API Key</td><td>Submit inventory</td></tr> <tr><td>POST</td><td>/agents/{id}/analyze</td><td>JWT</td><td>Vulnerability analysis (Claude AI)</td></tr> </tbody> </table>

<h3 id="bkmrk-billing-%28%2Fv1%2Fbilling">Billing (/v1/billing/*)</h3> <table id="bkmrk-methodendpointauthde-12"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/billing/plans</td><td>JWT</td><td>Available plans (free, starter, professional, enterprise, unlimited)</td></tr> <tr><td>POST</td><td>/billing/checkout</td><td>JWT</td><td>Create Stripe Checkout session</td></tr> <tr><td>POST</td><td>/billing/portal</td><td>JWT</td><td>Access Stripe customer portal</td></tr> <tr><td>GET</td><td>/billing/subscription</td><td>JWT</td><td>Current subscription</td></tr> <tr><td>GET</td><td>/billing/usage</td><td>JWT</td><td>Usage (API calls, scans, targets)</td></tr> <tr><td>GET</td><td>/billing/invoices</td><td>JWT</td><td>Invoice history</td></tr> <tr><td>POST</td><td>/billing/webhook</td><td>Stripe</td><td>Stripe webhook handler</td></tr> </tbody> </table>

<h3 id="bkmrk-dashboard%2C-notificat">Dashboard, Notifications, Settings</h3> <table id="bkmrk-methodendpointauthde-13"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/dashboard</td><td>JWT</td><td>Aggregated dashboard data</td></tr> <tr><td>GET</td><td>/notifications</td><td>JWT</td><td>List notifications</td></tr> <tr><td>PUT</td><td>/notifications/{id}/read</td><td>JWT</td><td>Mark as read</td></tr> <tr><td>PUT</td><td>/notifications/read-all</td><td>JWT</td><td>Mark all as read</td></tr> <tr><td>GET</td><td>/settings</td><td>JWT</td><td>User settings</td></tr> <tr><td>PUT</td><td>/settings</td><td>JWT</td><td>Update settings</td></tr> <tr><td>PUT</td><td>/settings/profile</td><td>JWT</td><td>Update profile</td></tr> </tbody> </table>

<h3 id="bkmrk-team-%28%2Fv1%2Fteam%2F%2A%29">Team (/v1/team/*)</h3> <table id="bkmrk-methodendpointauthde-14"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/team</td><td>JWT</td><td>Team members</td></tr> <tr><td>POST</td><td>/team/invite</td><td>JWT</td><td>Invite a member</td></tr> <tr><td>PUT</td><td>/team/{id}/role</td><td>JWT</td><td>Change role</td></tr> <tr><td>DELETE</td><td>/team/{id}</td><td>JWT</td><td>Remove a member</td></tr> </tbody> </table>

<h3 id="bkmrk-integrations-%28%2Fv1%2Fin">Integrations (/v1/integrations/*)</h3> <table id="bkmrk-methodendpointauthde-15"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/integrations/api-keys</td><td>JWT</td><td>List API keys (test/live)</td></tr> <tr><td>POST</td><td>/integrations/api-keys</td><td>JWT</td><td>Create an API key</td></tr> <tr><td>DELETE</td><td>/integrations/api-keys/{id}</td><td>JWT</td><td>Revoke a key</td></tr> <tr><td>GET</td><td>/integrations/webhooks</td><td>JWT</td><td>List webhooks</td></tr> <tr><td>POST</td><td>/integrations/webhooks</td><td>JWT</td><td>Create a webhook (HMAC-SHA256)</td></tr> <tr><td>PUT</td><td>/integrations/webhooks/{id}</td><td>JWT</td><td>Update</td></tr> <tr><td>DELETE</td><td>/integrations/webhooks/{id}</td><td>JWT</td><td>Delete</td></tr> </tbody> </table>

<h3 id="bkmrk-administration-%28%2Fv1%2F">Administration (/v1/admin/*)</h3> <p id="bkmrk-endpoints-reserved-f">Endpoints reserved for platform administrators (admin role required).</p> <table id="bkmrk-methodendpointauthde-16"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/admin/stats</td><td>Admin</td><td>Global statistics (users, tenants, scans, revenue)</td></tr> <tr><td>GET</td><td>/admin/users</td><td>Admin</td><td>List all users</td></tr> <tr><td>PUT</td><td>/admin/users/{id}</td><td>Admin</td><td>Update role/status/plan/limits</td></tr> <tr><td>GET</td><td>/admin/tenants</td><td>Admin</td><td>List all tenants</td></tr> <tr><td>PUT</td><td>/admin/tenants/{id}</td><td>Admin</td><td>Update plan/limits</td></tr> <tr><td>POST</td><td>/admin/tenants/{id}/suspend</td><td>Admin</td><td>Suspend a tenant</td></tr> <tr><td>POST</td><td>/admin/tenants/{id}/reactivate</td><td>Admin</td><td>Reactivate a tenant</td></tr> <tr><td>POST</td><td>/admin/tenants/{id}/impersonate</td><td>Admin</td><td>Impersonate a tenant</td></tr> <tr><td>GET</td><td>/admin/audit-logs</td><td>Admin</td><td>Audit logs with filters</td></tr> <tr><td>GET</td><td>/admin/settings</td><td>Admin</td><td>Global settings</td></tr> <tr><td>PUT</td><td>/admin/settings</td><td>Admin</td><td>Update global settings</td></tr> </tbody> </table>

<h3 id="bkmrk-assets-%26-system">Assets & System</h3> <table id="bkmrk-methodendpointauthde-17"> <thead><tr><th>Method</th><th>Endpoint</th><th>Auth</th><th>Description</th></tr></thead> <tbody> <tr><td>GET</td><td>/assets</td><td>JWT</td><td>List discovered assets</td></tr> <tr><td>GET</td><td>/assets/{id}</td><td>JWT</td><td>Asset details</td></tr> <tr><td>GET</td><td>/health</td><td>No</td><td>Health check (readiness probe)</td></tr> <tr><td>GET</td><td>/healthz</td><td>No</td><td>K8s liveness probe</td></tr> </tbody> </table>