Developer APIPublic V1 API Reference

Create account keys, manage projects, start scans, and poll results through the public v1 API.

YAML Contract

1. Overview & Host

Welcome to the Verdict API. Integrate security validation scans directly into your CI/CD workflows, pull risk registers, and manage architectures programmatically.

Base Production Host

https://verdict.ai

Standard Content Type

application/json

2. Authentication

All requests to our endpoints must include a Bearer authentication token. You can provision these tokens under the Developer Settings dashboard.

API Token Format

Tokens begin with a vxt_live_ prefix. Never commit these tokens to public repositories.

Example Request Header

Authorization: Bearer vxt_live_58c21...

3. Error Handling & HTTP Status

Verdict uses standard HTTP status codes to communicate successful and failed requests.

400Bad Request

Malformed JSON payload or invalid parameter type.

401Unauthorized

Bearer token header is missing, wrong, or invalid.

403Forbidden

Token doesn't have permissions or is revoked.

404Not Found

The requested project or scan doesn't exist.

409Conflict

Credits are depleted or resource is archived.

422Unprocessable

Zod verification error, e.g. failing validation schemas.

GET/api/v1/api-keys

List API Keys

Retrieve all programmatic API keys created by the current account user. Ideal for verifying pipeline access keys.

Example Request

curl -X GET "https://verdict.ai/api/v1/api-keys" \
  -H "Authorization: Bearer vxt_live_your_secret_key"

Response Body

{
  "data": [
    {
      "id": "key_91fba32",
      "name": "Production Key",
      "keyPrefix": "vxt_live",
      "keyLast4": "k91a",
      "creatorEmail": "dev@verdict.ai",
      "createdAt": 1781495226000,
      "lastUsedAt": 1781501230000,
      "revokedAt": null
    }
  ],
  "meta": {
    "count": 1
  }
}
DELETE/api/v1/api-keys/[keyId]

Revoke API Key

Revoke an API key by its unique ID. Revoked keys cannot be used for any API actions, and this action is irreversible.

Parameters

NameTypeReqDescription
keyIdstringYThe unique identifier of the key to revoke.

Example Request

curl -X DELETE "https://verdict.ai/api/v1/api-keys/key_e9a182b" \
  -H "Authorization: Bearer vxt_live_your_secret_key"

Response Body

{
  "data": {
    "keyId": "key_e9a182b",
    "revoked": true
  }
}
GET/api/v1/projects

List Projects

Retrieve a list of security assessment projects associated with the owner of the API key.

Example Request

curl -X GET "https://verdict.ai/api/v1/projects" \
  -H "Authorization: Bearer vxt_live_your_secret_key"

Response Body

{
  "data": [
    {
      "id": "proj_abc123",
      "name": "Verdict Core API",
      "description": "Risk assessment for core microservices",
      "securityScore": 84,
      "status": "ready",
      "createdAt": 1781495226000
    }
  ],
  "meta": {
    "count": 1
  }
}
POST/api/v1/projects

Create Project

Initialize a new security assessment project workspace. You can optionally submit LLM privacy preferences.

Parameters

NameTypeReqDescription
namestringYDescriptive name of the workspace.
descriptionstringNShort description outlining the system architecture scoping.

Example Request

curl -X POST "https://verdict.ai/api/v1/projects" \
  -H "Authorization: Bearer vxt_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payments API Gateway",
    "description": "Security mapping of credit card ingress flows"
  }'

Response Body

{
  "data": {
    "id": "proj_abc123",
    "name": "Payments API Gateway",
    "description": "Security mapping of credit card ingress flows",
    "securityScore": 100,
    "status": "ready",
    "createdAt": 1781495226000
  }
}
GET/api/v1/projects/[projectId]

Retrieve Project

Fetch detailed metadata, security score, architectural context, and user stories for a specific project.

Parameters

NameTypeReqDescription
projectIdstringYThe unique ID of the project workspace.

Example Request

curl -X GET "https://verdict.ai/api/v1/projects/proj_abc123" \
  -H "Authorization: Bearer vxt_live_your_secret_key"

Response Body

{
  "data": {
    "id": "proj_abc123",
    "name": "Verdict Core API",
    "description": "Risk assessment for core microservices",
    "securityScore": 84,
    "status": "ready",
    "createdAt": 1781495226000,
    "architecturalContext": {
      "dataFlow": "User requests route through Cloudflare WAF before API ingress...",
      "externalDependencies": ["stripe", "sendgrid"]
    }
  }
}
PATCH/api/v1/projects/[projectId]

Update Project

Modify name, description, user stories, or the architectural trust-zones configuration of a project.

Parameters

NameTypeReqDescription
projectIdstringYThe ID of the project to update.

Example Request

curl -X PATCH "https://verdict.ai/api/v1/projects/proj_abc123" \
  -H "Authorization: Bearer vxt_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Verdict Core v2 API"
  }'

Response Body

{
  "data": {
    "id": "proj_abc123",
    "name": "Verdict Core v2 API",
    "description": "Risk assessment for core microservices",
    "securityScore": 84,
    "status": "ready",
    "createdAt": 1781495226000
  }
}
DELETE/api/v1/projects/[projectId]

Delete Project

Archive a project workspace. Archive state removes the project from active user listing. This endpoint performs logical archival.

Parameters

NameTypeReqDescription
projectIdstringYThe ID of the project workspace to delete.

Example Request

curl -X DELETE "https://verdict.ai/api/v1/projects/proj_abc123" \
  -H "Authorization: Bearer vxt_live_your_secret_key"

Response Body

{
  "data": {
    "id": "proj_abc123",
    "name": "Verdict Core v2 API",
    "status": "archived"
  }
}
GET/api/v1/scans

List Scans

Query background analysis scans. Filters can optionally query by project ID to limit list context.

Parameters

NameTypeReqDescription
projectIdstringNOptionally filter scans to a single project.
limitnumberNNumber of records to return (Default: 25, Max: 100).

Example Request

curl -X GET "https://verdict.ai/api/v1/scans?projectId=proj_abc123&limit=10" \
  -H "Authorization: Bearer vxt_live_your_secret_key"

Response Body

{
  "data": [
    {
      "scanId": "run_j9a82bb",
      "projectId": "proj_abc123",
      "status": "completed",
      "methodology": "STRIDE",
      "name": "CI Trigger #44",
      "startedAt": 1781495226000,
      "completedAt": 1781495340000,
      "globalSecurityScore": 88
    }
  ],
  "meta": {
    "limit": 25,
    "count": 1,
    "totalAvailable": 1,
    "projectId": "proj_abc123"
  }
}
POST/api/v1/scans

Start a Scan

Queue an autonomous security scanning agent pipeline run. Consumes 1 credit upon complete agent review.

Parameters

NameTypeReqDescription
projectIdstringYThe target project ID to scan.
methodologystringNThreat modeling framework: STRIDE, PASTA, LINDDUN, MAESTRO (Default: STRIDE).
namestringNOptional name to label this scan run.
bypassCachebooleanNForce trigger AI agents to re-analyze architecture from scratch, ignoring cache. Defaults to false.

Example Request

curl -X POST "https://verdict.ai/api/v1/scans" \
  -H "Authorization: Bearer vxt_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_abc123",
    "methodology": "STRIDE",
    "name": "Nightly CI Scan"
  }'

Response Body

{
  "data": {
    "scanId": "run_j9a82bb",
    "jobId": "job_12ab34cd56ef",
    "projectId": "proj_abc123",
    "status": "queued"
  },
  "links": {
    "self": "/api/v1/scans/run_j9a82bb",
    "projectScans": "/api/v1/scans"
  },
  "meta": {
    "totalScans": 3
  }
}
GET/api/v1/scans/[scanId]

Retrieve Scan Status

Poll scan progress and retrieve final agent threats, vulnerabilities, compliance mappings, and scores once completed.

Parameters

NameTypeReqDescription
scanIdstringYThe unique run identifier of the scan.

Example Request

curl -X GET "https://verdict.ai/api/v1/scans/run_j9a82bb" \
  -H "Authorization: Bearer vxt_live_your_secret_key"

Response Body

{
  "data": {
    "scanId": "run_j9a82bb",
    "projectId": "proj_abc123",
    "status": "completed",
    "methodology": "STRIDE",
    "name": "Nightly CI Scan",
    "globalSecurityScore": 88,
    "startedAt": 1781495226000,
    "completedAt": 1781495340000,
    "jobStatus": {
      "status": "completed",
      "stepsCompleted": 7,
      "totalSteps": 7
    },
    "findings": {
      "synthesisSummary": "The analysis identified 4 critical vulnerabilities, primary data leakage at boundary...",
      "keyRecommendations": [
        "Enforce token-based access validation on the public ingress gateway.",
        "Implement column-level database envelope encryption."
      ],
      "risks": [
        {
          "id": "risk_1781495_0",
          "title": "Direct DB Access from Public Ingress",
          "severity": "critical",
          "mitreTechniqueId": "T1046",
          "remediationSteps": ["Isolate datastores inside private subnets."]
        }
      ]
    }
  }
}
DELETE/api/v1/scans/[scanId]

Delete Scan Run

Permanently delete a scan run from the system logs. This deletes historical scan scoring, threat lists, and component graphs. This action is irreversible.

Parameters

NameTypeReqDescription
scanIdstringYThe ID of the scan run to permanently delete.

Example Request

curl -X DELETE "https://verdict.ai/api/v1/scans/run_j9a82bb" \
  -H "Authorization: Bearer vxt_live_your_secret_key"

Response Body

{
  "data": {
    "scanId": "run_j9a82bb",
    "deleted": true
  }
}