Create account keys, manage projects, start scans, and poll results through the public v1 API.
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.aiStandard Content Type
application/json2. 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.
Malformed JSON payload or invalid parameter type.
Bearer token header is missing, wrong, or invalid.
Token doesn't have permissions or is revoked.
The requested project or scan doesn't exist.
Credits are depleted or resource is archived.
Zod verification error, e.g. failing validation schemas.
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
}
}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
| Name | Type | Req | Description |
|---|---|---|---|
| keyId | string | Y | The 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
}
}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
}
}Create Project
Initialize a new security assessment project workspace. You can optionally submit LLM privacy preferences.
Parameters
| Name | Type | Req | Description |
|---|---|---|---|
| name | string | Y | Descriptive name of the workspace. |
| description | string | N | Short 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
}
}Retrieve Project
Fetch detailed metadata, security score, architectural context, and user stories for a specific project.
Parameters
| Name | Type | Req | Description |
|---|---|---|---|
| projectId | string | Y | The 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"]
}
}
}Update Project
Modify name, description, user stories, or the architectural trust-zones configuration of a project.
Parameters
| Name | Type | Req | Description |
|---|---|---|---|
| projectId | string | Y | The 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 Project
Archive a project workspace. Archive state removes the project from active user listing. This endpoint performs logical archival.
Parameters
| Name | Type | Req | Description |
|---|---|---|---|
| projectId | string | Y | The 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"
}
}List Scans
Query background analysis scans. Filters can optionally query by project ID to limit list context.
Parameters
| Name | Type | Req | Description |
|---|---|---|---|
| projectId | string | N | Optionally filter scans to a single project. |
| limit | number | N | Number 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"
}
}Start a Scan
Queue an autonomous security scanning agent pipeline run. Consumes 1 credit upon complete agent review.
Parameters
| Name | Type | Req | Description |
|---|---|---|---|
| projectId | string | Y | The target project ID to scan. |
| methodology | string | N | Threat modeling framework: STRIDE, PASTA, LINDDUN, MAESTRO (Default: STRIDE). |
| name | string | N | Optional name to label this scan run. |
| bypassCache | boolean | N | Force 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
}
}Retrieve Scan Status
Poll scan progress and retrieve final agent threats, vulnerabilities, compliance mappings, and scores once completed.
Parameters
| Name | Type | Req | Description |
|---|---|---|---|
| scanId | string | Y | The 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 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
| Name | Type | Req | Description |
|---|---|---|---|
| scanId | string | Y | The 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
}
}