Developer documentation

Delete Account

Permanently close the current user's account.

JSON body

Change Password

Change the current user's password.

JSON body

Forgot Password

Request a password reset email.

JSON body

Login

Authenticate user and return JWT tokens.

JSON body

Logout

Logout the current user.

JSON body

Get Current User Profile

Get current authenticated user's profile.

Update Profile

Update the current user's profile.

JSON body

Mfa Disable

Disable MFA for the current user.

JSON body

Mfa Setup

Initiate MFA setup by generating a TOTP secret.

Mfa Verify Login

Complete login by verifying MFA code after initial password authentication.

JSON body

Mfa Verify Setup

Verify MFA setup by confirming a TOTP code from the user's authenticator app.

JSON body

Refresh

Obtain a new access token using a refresh token.

JSON body

Register

Register a new user account.

JSON body

Resend Verification

Send a new activation link to an account that is waiting for one.

JSON body

Reset Password

Reset password using a valid reset token.

JSON body

Send Verification

Send an email verification link to the current user.

Verify Email

Activate an account when the mailbox holder accepts the current Terms.

JSON body

List Credentials

List the authenticated user's credentials, newest first. Never leaks keys.

Create Credential

Create a credential, encrypting the key at rest. Returns no key.

JSON body

Get Credential

Fetch a single credential owned by the caller. Never leaks the key.

credential_id (path, required)

Update Credential

Partial update. Re-encrypts api_key if sent; omitted key stays unchanged.

credential_id (path, required), JSON body

Delete Credential

Delete a credential. Referencing agents' credential_id becomes NULL.

credential_id (path, required)

List Agents

List all agents registered by the current user.

Create Agent

Register a new LLM agent (endpoint) for security testing.

JSON body

Get Agent

Get a specific agent by ID.

agent_id (path, required)

Update Agent

Update an agent.

agent_id (path, required), JSON body

Delete Agent

Archive an agent while preserving all associated scans and evidence.

agent_id (path, required)

Inventory Agents

offset (query), limit (query)

List Assets

kind (query), offset (query), limit (query)

Create Asset

JSON body

Update Asset

asset_id (path, required), JSON body

Delete Asset

asset_id (path, required)

Save Vendor Assessment

Score bounded questionnaire answers and save only to the owner's vendor.

asset_id (path, required), JSON body

List Templates

Create Template

JSON body

Seed Samples

Create 3 illustrative starter templates for the user.

JSON body

Get Template

template_id (path, required)

Update Template

Update a template's name / description / category / linked agent.

template_id (path, required), JSON body

Delete Template

template_id (path, required)

Activate Version

template_id (path, required), version_number (path, required)

Diff Versions

template_id (path, required), a (query, required), b (query, required)

List Versions

template_id (path, required)

Create Version

template_id (path, required), JSON body

Get Version

template_id (path, required), version_number (path, required)

Delete Version

Delete a single version. Refused if the version is currently active or is the only version.

template_id (path, required), version_number (path, required)

Return the full attack cost catalog

Returns the complete ATTACK_COSTS catalog with all supported attack types, their descriptions, researcher hour estimates, infrastructure costs, and average token consumption per attempt. Use the attack type identifiers from this response as the 'attack_type' parameter in POST /estimate-attack-cost.

Return a fully-populated model card template

Returns a complete model card template with all required and recommended fields filled with descriptive placeholder values. Use this as a starting point when creating a model card for your AI system. Replace all placeholder values with real information before submitting to POST /validate-card.

Compute the ROI of a Secuvon scan against expected breach cost

Computes the return on investment (ROI) of running a Secuvon security scan, comparing scan cost against the expected breach cost avoidance. The model uses: (1) Attacker-equivalent cost: total attacker labour for all detected attacks. (2) Breach probability reduction: critical_findings_pct × 0.30 (NIST SP 800-30). (3) Expected loss avoidance: breach cost × probability reduction. (4) ROI ratio: loss avoidance / scan cost. Breach cost baseline defaults to $4,450,000 (IBM Cost of a Data Breach 2023).

JSON body

Estimate the fully-loaded cost for an attacker to mount a specific attack

Estimates the researcher time and infrastructure cost required for an attacker to mount a specific AI security attack. The fully-loaded cost combines researcher hours (at the provided hourly rate) and infrastructure costs (GPU, API calls, cloud services). Use this to quantify the value Secuvon delivers by replicating attacker workloads at a fraction of the cost.

JSON body

Estimate the total API and platform cost for a Secuvon scan

Estimates the token consumption and cost of running a Secuvon security scan against a given LLM model. Token costs are based on the model's published pricing (per 1M tokens). A 25% platform overhead is added on top of raw API costs to cover Secuvon orchestration, storage, and result analysis. Unknown model identifiers fall back to gpt-4o pricing with an 'is_unknown_model' flag in the response.

JSON body

Validate a model card against the HuggingFace / Google MC spec

Validates an AI model card JSON object against the HuggingFace model card standard and Google Model Card Toolkit specification. Returns a structured ValidationReport with errors, warnings, a completeness score (0-100), and a letter grade (A-F). Errors indicate missing required content; warnings indicate missing recommended content. Use GET /card-template to retrieve a fully-populated starting point.

JSON body

Submit a vendor assessment and receive scored risk report

Accepts a completed (or partial) vendor assessment and returns a fully scored risk report. Unanswered questions are treated as score 0 (no control present). The report includes overall risk score (0-100, lower = safer), risk rating (LOW / MEDIUM / HIGH / CRITICAL), per-domain scores, identified gaps, and prioritised recommendations.

JSON body

Get full vendor risk assessment questionnaire

Returns all 40 assessment questions organised by domain in canonical order. Each question includes its ID, domain, full text, weight, assessor guidance, and preferred evidence type. Use this endpoint to display the questionnaire in a UI or export it for offline completion.

Download empty assessment template

Returns an empty assessment template containing all 40 questions with blank answer slots. Useful for downloading, distributing to vendors, or pre-filling a UI form before submission. Each question slot contains null score, empty notes, and empty evidence fields.

List Scans

List scans for the current user.

limit (query), offset (query), agent_id (query)

Compare Scans By Query

Compare current with baseline, or with the automatic baseline when baseline is omitted: the caller's most recent completed, scored scan of the same agent that finished before current.

current (query, required), baseline (query)

Dashboard Stats

Get aggregated dashboard statistics for the current user.

Model Comparison Modules

Per-model, per-module pass rates over the caller's current-corpus scans.

limit (query), offset (query)

Module Catalogue

Every module the scanner loads from the corpus, with its display name, test count, profile membership (smoke, quick, release, full), the OWASP ids authored on its tests and the evaluation types it is graded with.

Profile Readiness

Which assessment profiles the active grader can run, and why not.

modules (query)

Start Scan

Start a new security scan against a registered agent.

JSON body

Get Scan

Return a single scan summary in the same normalized shape the list returns.

scan_id (path, required)

Delete Scan

Delete a scan and optionally its results.

scan_id (path, required), delete_results (query)

Cancel Scan

Cancel an in-flight scan.

scan_id (path, required)

Get Scan Results

Get the complete results of a completed scan.

scan_id (path, required), page (query), per_page (query)

Get Scan Status

Get the current status of a scan.

scan_id (path, required)

Sse Scan Progress

Server-Sent Events endpoint for real-time scan progress.

scan_id (path, required)

Verify Scan Integrity

Compare a scan's stored result hash with its result summary fields.

scan_id (path, required)

Full evidence trace for a finding

Return the structured evidence trace for (scan_id, finding_id).

scan_id (path, required), finding_id (path, required)

Downloadable evidence bundle (JSON + transcript)

Return a zip archive containing trace.json and transcript.txt.

scan_id (path, required), finding_id (path, required)

Download PDF pentest report for a scan

Generate and stream a professional PDF pentest report for the given scan.

scan_id (path, required)

Get JSON summary of scan data used for the PDF report

Return the structured JSON data that would be used to generate the PDF report.

scan_id (path, required)

Get Remediation

Return the cached remediation plan, or generate one on first access.

finding_id (path, required)

Submit Feedback

Persist helpful/not-helpful feedback for the cached plan.

finding_id (path, required), JSON body

Regenerate Remediation

Force regeneration of the plan, bypassing the cache.

finding_id (path, required)

Pass-rate history for an agent

Return the last limit scored scans of the caller's agent_id.

agent_id (path, required), limit (query)

Drift vs auto-resolved baseline

Compute drift for scan_id vs its automatically-resolved baseline.

scan_id (path, required)

Drift vs explicit baseline

Compute drift between two specific scans of the same agent.

scan_id (path, required), baseline_id (path, required)

List Schedules

One page of the user's schedules, newest first.

limit (query), offset (query)

Create Schedule

Create a new scan schedule.

JSON body

Get Risk Trends

Get security-score trend data for an agent.

agent_id (path, required), days (query)

Get Schedule

Get details of a specific schedule.

schedule_id (path, required)

Update Schedule

Update a schedule.

schedule_id (path, required), JSON body

Delete Schedule

Delete a schedule.

schedule_id (path, required)

List Schedule Runs

One page of the schedule's run history, newest first.

schedule_id (path, required), limit (query), offset (query)

Trigger Schedule

Manually trigger a scheduled scan immediately.

schedule_id (path, required)

List Frameworks

The framework catalogue: every framework the compliance engine tracks.

Get Tenant Coverage

The caller's evidence per framework and control.

agent_id (query)

List Control Tests

The exact corpus tests mapped to one control, in test id order.

framework_id (path, required), control (query, required), limit (query), offset (query)

List Policies

One page of the authenticated user's policies (active and inactive).

limit (query), offset (query)

Create Policy

Create a new policy from raw YAML.

JSON body

Deploy Gate

CI/CD deploy gate: aggregate the caller's active policies into a verdict.

JSON body

List Gate Decisions

Recent CI/CD gate decisions for the caller, newest first.

limit (query)

Verify Gate Decision

Check that a gate decision is genuine, and say what it decided and when.

JSON body

Validate Policy Route

Check a policy document's structure with the engine's own parser.

JSON body

List Waivers

One page of the caller's waivers, newest first.

active (query), limit (query), offset (query)

Create Waiver

Create a waiver that suppresses a matching gate failure.

JSON body

Delete Waiver

Soft-delete a waiver (is_active = False). Owner-scoped.

waiver_id (path, required)

Get Policy

policy_id (path, required)

Update Policy

Update YAML source and/or active flag. Bumps version on YAML change.

policy_id (path, required), JSON body

Delete Policy

policy_id (path, required)

Evaluate Policy Route

Evaluate a policy against a scan owned by the same user.

policy_id (path, required), JSON body

List Policy Evaluations

A policy's stored evaluations, newest first, one page at a time.

policy_id (path, required), limit (query), offset (query)

Policy Impact

Dry-run a policy against the caller's most recent completed scans.

policy_id (path, required), JSON body

Current security posture

The caller's security posture now, from each agent's latest scored scan.

Security posture snapshot history

Return the caller's own daily security posture snapshots, newest first.

days (query)

List Packs

limit (query), offset (query)

Queue Pack

JSON body

Get Pack

pack_id (path, required)

Delete Pack

pack_id (path, required)

Download Pack

pack_id (path, required), format (query)

List Builtin Rules

List available built-in guardian rules.

Get Guardian Activity

Get recent guardian inspection events for an agent (newest first).

agent_id (path, required), limit (query)

Get Guardian Anomalies

Detect behavioral anomalies for an agent over its Guardian telemetry.

agent_id (path, required)

Get Guardian Config

Get guardian configuration for an agent.

agent_id (path, required)

Create Update Guardian Config

Create or update guardian configuration for an agent.

agent_id (path, required), JSON body

Delete Guardian Config

Disable guardian for an agent.

agent_id (path, required)

List Gateway Keys

agent_id (path, required)

Create Gateway Key

agent_id (path, required), JSON body

Revoke Gateway Key

agent_id (path, required), key_id (path, required)

Inspect Message

Inspect a message through the guardian.

agent_id (path, required), JSON body

Per-agent Guardian latency summary (JSON)

Return a JSON p50/p95/p99 latency summary for a single agent.

agent_id (path, required)

Add Custom Rule

Add a custom rule to an agent's guardian.

agent_id (path, required), JSON body

Get Guardian Stats

Get guardian statistics for an agent.

agent_id (path, required)

Anthropic

Openai

Events

limit (query), offset (query), agent_id (query), reason (query), verdict (query)

Export

List Sessions

List the caller's agent sessions, optionally filtered by agent.

agent_id (query), limit (query), offset (query)

Get Session

Fetch a single session header. Ownership-checked.

session_id (path, required)

Replay Session

Return the ordered, redaction-safe timeline for a session.

session_id (path, required)

List Teams

The workspaces you belong to, the one you founded first.

Accept Invite

Join a workspace with an invitation addressed to your account.

JSON body

Lookup Invite

What an invitation link offers the signed-in account.

JSON body

Get Team

One workspace: your role, what it lets you do, and its seats.

team_id (path, required)

Get Team Dashboard

The workspace's own completed assessments (scans:read).

team_id (path, required)

List Invites

Open invitations, newest first (team:invite).

team_id (path, required), limit (query), cursor (query)

Create Invite

Invite an address with a role (team:invite), within the plan's seats.

team_id (path, required), JSON body

Revoke Invite

Withdraw an open invitation; its link stops working at once.

team_id (path, required), invite_id (path, required)

Resend Invite

A fresh link and expiry for an open invitation; the old link stops working.

team_id (path, required), invite_id (path, required)

List Members

The workspace's members, the founder first. Any member may read it.

team_id (path, required), limit (query), cursor (query)

Remove Member

Remove a member (team:remove), or leave the workspace yourself.

team_id (path, required), user_id (path, required)

Change Member Role

Give a member another role (rbac:manage).

team_id (path, required), user_id (path, required), JSON body

List Permissions

The permission catalogue custom roles are built from.

List Roles

Built-in and custom roles, each with its permissions and pages.

org_id (query)

Create Custom Role

Create a custom role from catalogue permissions (rbac:manage).

JSON body

Update Custom Role

Rename a custom role or replace its permissions (rbac:manage).

role_id (path, required), JSON body

Delete Custom Role

Delete a custom role nobody holds or is offered (rbac:manage).

role_id (path, required), org_id (query)

List Configs

org_id (query, required)

Create Config

JSON body

Update Config

config_id (path, required), org_id (query, required), JSON body

Delete Config

config_id (path, required), org_id (query, required)

Link Identity

config_id (path, required), org_id (query, required)

Unlink Identity

config_id (path, required), org_id (query, required)

Mfa Challenge

Sso Callback

org_slug (path, required)

Sso Callback

org_slug (path, required)

Sso Login

org_slug (path, required)

Metadata

org_slug (path, required)

List Tokens

org_id (query, required)

Issue Token

JSON body

Revoke Token

token_id (path, required), org_id (query, required)

List Groups

startIndex (query), count (query)

Create Group

Get Group

group_id (path, required)

Update Group

group_id (path, required)

Update Group

group_id (path, required)

Delete Group

group_id (path, required)

Types Route

Schemas Route

Config Route

List Users

filter (query), startIndex (query), count (query)

Create User

Get User

user_id (path, required)

Replace User

user_id (path, required)

Patch User

user_id (path, required)

Delete User

user_id (path, required)

List Tokens

org_id (query, required)

Issue Token

JSON body

Revoke Token

token_id (path, required), org_id (query, required)

Get Config

The workspace's retention windows, its plan's bounds and the purge.

org_id (query)

Update Config

Set the workspace's windows within its plan (retention:manage).

JSON body

List Webhooks

One page of the workspace's channels (integrations:read).

org_id (query), limit (query), cursor (query)

Create Webhook

Add a channel to the workspace (integrations:manage).

org_id (query), JSON body

List Events

What a channel can subscribe to, and the channel types this release has.

Get Webhook History

The delivery log: up to 20 recent outcomes per channel, with status codes, attempt numbers and scheduled retries (integrations:read).

org_id (query), limit (query), cursor (query)

Get Webhook

One channel of the workspace (integrations:read).

webhook_id (path, required), org_id (query)

Update Webhook

Change a channel (integrations:manage).

webhook_id (path, required), org_id (query), JSON body

Delete Webhook

Delete a channel and stop its retries (integrations:manage).

webhook_id (path, required), org_id (query)

Rotate Signing Secret

Replace a signed channel's secret; the new one is returned once and signs every later delivery (integrations:manage).

webhook_id (path, required), org_id (query)

Test Webhook

Send one REAL test delivery and report its REAL outcome.

webhook_id (path, required), org_id (query)

List Api Keys

limit (query), offset (query)

Create Api Key

JSON body

Revoke Api Key

key_id (path, required)

Create Checkout Session

Create a Stripe Checkout session for the requested plan.

Get Public Plans

Public, cacheable plan catalogue for the pricing and upgrade surfaces.

Create Portal Session

Create a Stripe customer portal session for self-serve billing management.

Get Billing Status

Return legacy Stripe state plus authoritative organisation entitlements.

Get Product Capabilities

List Blog Posts

List published blog posts with optional category filter and pagination.

category (query), page (query), page_size (query)

List Categories

List blog categories with the number of published posts in each.

Get Blog Post

Get a single published blog post by its slug.

slug (path, required)

List Module Facts

List every module fact, ordered by module name.

Submit Contact

Record a contact-form message from the public site.

JSON body

Confirm

Record consent only after the mailbox holder uses the emailed link.

JSON body

Subscribe

Send a confirmation email; no one is subscribed by this request alone.

JSON body

Unsubscribe

Withdraw marketing consent using the token included in email.

JSON body

Read My Email Preferences

Whether this account has current, confirmed newsletter consent.

Update My Email Preferences

Withdraw marketing consent for the signed-in account's address.

JSON body

Unsubscribe Onboarding

Stop the onboarding emails (founder note and nudge) for one account.

token (query)

Submit Feedback

Record feedback from the signed-in user and notify the founder inbox.

JSON body

Health Check

Public health: is this API process up and serving.

Root

Root endpoint with API information.