VibeCheck API Documentation

Introduction

VibeCheck is a public HTTP API that security-scans vibe-coded apps in two modes — lightweight static analysis of source code and robust AI-powered red-teaming of running applications through a built-in WebSocket reverse tunnel.

Lightweight mode analyzes source code via five static scanners (dependency, pattern, secret, config, and Gemini contextual). Robust mode deploys four Gemini-powered AI agents (recon, auth, injection, config) that actively probe a live target.

Base URL

https://vibechecker.aedify.ai

18 Endpoints REST + WebSocket Zero Auth Gemini AI Agents OpenAPI /docs

⚡ Quick Start Guide

Get from zero to security findings in 3 steps. We'll scan a real vulnerable repository — damn-vulnerable-MCP-server — to show you exactly how VibeCheck works.

Step 1 — Check API Health

Verify the API is up and running:

curl https://vibechecker.aedify.ai/v1/health

You should see {"status": "healthy", ...}. Try it below in the Health endpoint.

Step 2 — Create a Scan

Submit the vulnerable repo for lightweight static analysis. This scans the code for SQL injection, hardcoded secrets, XSS, insecure configs, and more:

curl -X POST https://vibechecker.aedify.ai/v1/assessments \
          -H "Content-Type: application/json" \
          -d '{"mode": "lightweight", "repo_url": "https://github.com/vulnerable-apps/damn-vulnerable-MCP-server"}'
        

The API returns 202 Accepted with an assessment object. Copy the id field (e.g. asm_abc123) — you'll need it for every following step.

// Example response
          {
          "id": "asm_abc123",
          "mode": "lightweight",
          "status": "queued",
          "repo_url": "https://github.com/vulnerable-apps/damn-vulnerable-MCP-server",
          "finding_counts": {"critical": 0, "high": 0, "medium": 0, "low": 0, "info": 0, "total": 0},
          "created_at": "2026-02-28T12:00:00Z"
          }

Step 3 — Poll for Completion

The scan runs in the background. Poll the assessment status until it reaches complete:

curl https://vibechecker.aedify.ai/v1/assessments/asm_abc123

Status progression: queued → cloning → analyzing → complete (usually ~30-60 seconds).

Step 4 — View Findings

Once complete, fetch the security findings:

curl https://vibechecker.aedify.ai/v1/assessments/asm_abc123/findings

You'll see findings like SQL injection, hardcoded secrets, command injection, and more — each with severity, description, location, and remediation advice.

Step 5 — Deep-Dive with AI Analysis

Pick any finding and get Gemini AI-powered analysis with root cause, impact assessment, and an actionable fix plan:

curl -X POST
          https://vibechecker.aedify.ai/v1/assessments/asm_abc123/findings/fnd_abc123/analyze \
          -H "Content-Type: application/json" \
          -d '{"focus": "How can an attacker exploit this?"}'

💡 Tip: All the Try It panels below are pre-filled with asm_abc123 as a demo ID. Create your own assessment first (Step 2), then replace the ID in any panel to explore your real results!

📝 Common Workflows

🔍 Scan a GitHub Repo

POST assessment with repo_url → poll status → GET findings → analyze finding with Gemini AI.

🎯 Red-Team a Live App

Connect via WebSocket tunnel or Cloudflare Tunnel → POST robust assessment with target_url → poll → GET findings + agent logs.

⚙️ CI/CD Integration

POST assessment with idempotency_key → poll until complete → GET findings → check for critical severity → fail/pass your pipeline.

🖥️ IDE Integration (MCP)

Add this to your mcp.json in Cursor or VS Code to use VibeCheck tools directly from your editor chat:

{
  "mcpServers": {
    "vibecheck-remote": {
      "url": "https://vibecheckmcp.aedify.ai/mcp"
    }
  }
}

Then add a .cursorrules file to your project root so Cursor uses VibeCheck automatically:

# Security Scanning with VibeCheck

              You have access to the VibeCheck MCP server for AI-powered security scanning.

              ## When to use VibeCheck
              - Before committing code: run a lightweight scan on the current repo
              - When reviewing PRs: scan changed files for vulnerabilities
              - When the user asks about security: scan and analyze findings
              - After adding dependencies: check for known vulnerabilities

              ## How to use
              1. Use the `create_assessment` tool with mode "lightweight" and the repo URL or file contents
              2. Poll the assessment status until complete
              3. Use `list_findings` to see all discovered vulnerabilities
              4. Use `analyze_finding` on critical/high findings for AI-powered remediation advice

              ## Guidelines
              - Always scan before saying code is "secure" or "ready for production"
              - Flag critical and high severity findings to the user immediately
              - Suggest specific fixes based on the remediation advice from findings

Authentication

VibeCheck requires no authentication (hackathon MVP). All endpoints are public. Every response includes an X-Request-ID header for request tracing.

Error Handling

All errors return a consistent envelope:

{
          "error": {
          "type": "not_found",
          "message": "Assessment 'asm_abc123' not found.",
          "code": "ASSESSMENT_NOT_FOUND",
          "param": null
          }
          }

HTTP	Type	Codes
`400`	validation_error, tunnel_error	INVALID_MODE, MISSING_REPO_URL, MISSING_TUNNEL_SESSION, TUNNEL_NOT_CONNECTED, INVALID_AGENT, LOGS_NOT_AVAILABLE
`404`	not_found	ASSESSMENT_NOT_FOUND, FINDING_NOT_FOUND, AGENT_NOT_FOUND, TUNNELSESSION_NOT_FOUND
`409`	conflict	ASSESSMENT_IN_PROGRESS, DUPLICATE_IDEMPOTENCY_KEY
`422`	validation_error	VALIDATION_ERROR (Pydantic)
`502`	external_error, tunnel_error	CLONE_FAILED, TARGET_UNREACHABLE

Pagination

All list endpoints return a paginated response:

{
          "data": [ ... ],
          "pagination": {
          "page": 1,
          "per_page": 20,
          "total": 42,
          "total_pages": 3
          }
          }

Standard query parameters: page (int, default 1) and per_page (int, default 20, max 100).

📋 Usage Notes

Rate Limiting: None (hackathon MVP) — all endpoints are fully open.
Concurrency: Scans are processed sequentially per instance.
Lightweight scans: Take ~15–60 seconds depending on repo size.
Robust scans: Take ~30–120 seconds depending on depth and number of agents.
WebSocket: Connections are cleaned up after 5 minutes of inactivity.

GET /v1/health Health Check

Returns API health status, version, active tunnel count, and agent availability.

Parameters

None

Example Response

{
                "status": "healthy",
                "version": "1.0.0",
                "active_tunnels": 0,
                "agents_available": true
                }

cURL

curl https://vibechecker.aedify.ai/v1/health

🧪 Try It

POST /v1/assessments Create Assessment

Create a security assessment. Returns 202 Accepted. The scan runs in the background.

Body Parameters

Param	Type	Required	Description
`mode`	string	Yes	`"lightweight"` or `"robust"`
`repo_url`	string	Conditional	GitHub URL. Required for lightweight if no `files`.
`files`	array	Conditional	Array of `{path, content}`. Required for lightweight if no `repo_url`.
`target_url`	string	Conditional	Any reachable URL. Required for robust.
`tunnel_session_id`	string	No	Only needed with built-in tunnel.
`agents`	string[]	No	Default: `["recon","auth","injection","config"]`
`depth`	string	No	`"quick"` (5), `"standard"` (15), `"deep"` (30)
`idempotency_key`	string	No	Prevents duplicate scans.

Example: Lightweight with repo_url

curl -X POST https://vibechecker.aedify.ai/v1/assessments \
                -H "Content-Type: application/json" \
                -d '{"mode": "lightweight", "repo_url": "https://github.com/user/repo"}'

Example: Lightweight with inline files

{
                "mode": "lightweight",
                "files": [{
                "path": "app.py",
                "content": "import os\nJWT_SECRET = \"supersecret123\"\ndb.execute(f\"SELECT * FROM users WHERE id =
                {id}\")\nos.system(\"rm -rf \" + user_input)\napp.run(debug=True)"
                }]
                }

Example: Robust with target_url

curl -X POST https://vibechecker.aedify.ai/v1/assessments \
                -H "Content-Type: application/json" \
                -d '{"mode": "robust", "target_url": "https://example.com", "depth": "standard"}'

🧪 Try It

Request Body (JSON)

GET /v1/assessments List Assessments

List assessments with pagination, filtering, and sorting.

Query Parameters

Param	Type	Default	Description
`page`	int	1	Page number
`per_page`	int	20	Items per page (max 100)
`mode`	string	—	Filter: `lightweight` or `robust`
`status`	string	—	Filter: queued, cloning, analyzing, scanning, complete, failed
`sort`	string	-created_at	Sort field (prefix `-` for desc)

🧪 Try It

per_page

mode

status

GET /v1/assessments/{id} Get Assessment

Get full assessment detail. Status progresses: queued → cloning → analyzing → scanning → complete | failed.

Path Parameters

Param	Type	Required
`id`	string	Yes

🧪 Try It

Assessment ID

DELETE /v1/assessments/{id} Delete Assessment

Delete assessment and all associated findings and logs. Returns 204 No Content.

🧪 Try It

Assessment ID

POST /v1/assessments/{id}/rerun Re-run Assessment

Re-run a completed or failed assessment. Clears existing findings and logs, resets status to queued. Returns 409 if the assessment is still in progress.

🧪 Try It

Assessment ID

WS /v1/assessments/{id}/ws Real-time Status Stream

WebSocket endpoint for real-time assessment status updates. Server sends assessment_update on status changes and assessment_terminal on completion.

WebSocket — No Try It panel. Connect using a WebSocket client.

Server Message: Status Update

{
                "type": "assessment_update",
                "assessment": {
                "id": "asm_abc123",
                "status": "scanning",
                "finding_counts": {"critical": 0, "high": 1, "medium": 2, "low": 0, "info": 0, "total": 3}
                }
                }

Server Message: Terminal

{
                "type": "assessment_terminal",
                "assessment": {
                "id": "asm_abc123",
                "status": "complete",
                "finding_counts": {"critical": 1, "high": 3, "medium": 5, "low": 2, "info": 1, "total": 12}
                }
                }

GET /v1/assessments/{id}/findings List Findings

List findings for an assessment. Filterable, searchable, and paginated. Default sort uses domain ordering: critical → high → medium → low → info.

Query Parameters

Param	Type	Description
`page`	int	Page number (default 1)
`per_page`	int	Items per page (default 20)
`severity`	string	critical, high, medium, low, info
`category`	string	e.g. sql_injection, xss, hardcoded_secret
`agent`	string	Filter by agent name
`q`	string	Text search across title + description
`sort`	string	Default `severity`

Example Finding Object

{
                "id": "fnd_abc123def456",
                "assessment_id": "asm_abc123",
                "severity": "critical",
                "category": "sql_injection",
                "title": "SQL Injection via string formatting",
                "description": "User input directly interpolated into SQL query...",
                "location": {"file": "app.py", "line": 3, "snippet": "db.execute(f\"SELECT...\")"},
                "evidence": null,
                "remediation": "Use parameterized queries instead of string formatting.",
                "agent": "static_pattern",
                "created_at": "2026-02-28T12:00:00Z"
                }

🧪 Try It

Assessment ID

severity

q (search)

GET /v1/assessments/{id}/findings/{finding_id} Get Finding

Get a single finding with full detail.

🧪 Try It

Assessment ID

Finding ID

POST /v1/assessments/{id}/findings/{finding_id}/analyze Analyze Finding (AI)

Gemini AI-powered deep analysis of a finding. Returns summary, impact, root cause, mode-specific guidance, where to fix, action plan, and similar findings from Supermemory.

Body (optional)

{"focus": "optional guidance string"}

Response Shape

{
                "summary": "...",
                "impact": "...",
                "possible_root_cause": "...",
                "mode_guidance": "...",
                "where_to_fix": "...",
                "actions": ["Step 1...", "Step 2..."],
                "memory_similar_results_count": 3,
                "memory_similar_results": [...]
                }

🧪 Try It

Assessment ID

Finding ID

Request Body (JSON, optional)

GET /v1/assessments/{id}/logs Agent Activity Logs

Agent activity logs for robust scans. Returns 400 LOGS_NOT_AVAILABLE for lightweight assessments.

Query Parameters

Param	Type	Description
`page`	int	Page number
`per_page`	int	Items per page
`agent`	string	Filter by agent name

Log Entry Shape

{
                "id": "log_abc123",
                "assessment_id": "asm_abc123",
                "agent": "injection",
                "step": 3,
                "action": "http_request",
                "target": "/api/users?id=1 OR 1=1",
                "payload": "...",
                "response_code": 200,
                "response_preview": "...",
                "reasoning": "Testing SQL injection on user lookup endpoint.",
                "finding_id": "fnd_def456",
                "timestamp": "2026-02-28T12:05:00Z"
                }

🧪 Try It

Assessment ID

agent (optional)

GET /v1/agents List Agents

List all 5 agents with descriptions and categories.

🧪 Try It

GET /v1/agents/{name} Get Agent

Get a single agent by name. Valid names: recon, auth, injection, config, static.

🧪 Try It

Agent Name

WS /v1/tunnel Tunnel Client Connection

WebSocket endpoint for the reverse tunnel client. Used to expose localhost apps for robust scanning.

WebSocket — No Try It panel. Use the tunnel client CLI.

Quick Start

pip install vibecheck-client
                vibecheck connect 3000 --server wss://vibechecker.aedify.ai/v1/tunnel

Protocol

# Client → Server: Connect
                {"type": "connect", "target_port": 3000}

                # Server → Client: Session Created
                {"type": "session_created", "session_id": "tun_abc123"}

                # Server → Client: Forward HTTP request
                {"type": "http_request", "request_id": "req_001", "method": "GET", "path": "/api/users", "headers": {},
                "body": null}

                # Client → Server: HTTP response
                {"type": "http_response", "request_id": "req_001", "status_code": 200, "headers": {}, "body": "..."}

                # Heartbeat
                Server → Client: {"type": "ping"}
                Client → Server: {"type": "pong"}

GET /v1/tunnel/sessions List Tunnel Sessions

List all tunnel sessions with status, target port, and last heartbeat.

🧪 Try It

GET /v1/tunnel/sessions/{id} Get Tunnel Session

Get a single tunnel session by ID.

🧪 Try It

Session ID

GET /v1/memory/status Memory Status

Check if Supermemory integration is enabled.

🧪 Try It

GET /v1/memory/search Memory Search

Semantic search across stored findings using Supermemory.

Query Parameters

Param	Type	Required	Description
`q`	string	Yes	Search query text
`limit`	int	No	Max results (default 5, max 25)
`assessment_id`	string	No	Filter to specific assessment

🧪 Try It

q (search query) *

limit

Introduction

Base URL

⚡ Quick Start Guide

Step 1 — Check API Health

Step 2 — Create a Scan

Step 3 — Poll for Completion

Step 4 — View Findings

Step 5 — Deep-Dive with AI Analysis

📝 Common Workflows

🔍 Scan a GitHub Repo

🎯 Red-Team a Live App

⚙️ CI/CD Integration

🖥️ IDE Integration (MCP)

Authentication

Error Handling

Pagination

📋 Usage Notes

Health

Parameters

Example Response

cURL

🧪 Try It

Assessments

Body Parameters

Example: Lightweight with repo_url

Example: Lightweight with inline files

Example: Robust with target_url

🧪 Try It

Query Parameters

🧪 Try It

Path Parameters

🧪 Try It

🧪 Try It

🧪 Try It

Server Message: Status Update

Server Message: Terminal

Findings

Query Parameters

Example Finding Object

🧪 Try It

🧪 Try It

Body (optional)

Response Shape

🧪 Try It

Agent Logs

Query Parameters

Log Entry Shape

🧪 Try It

Agents

🧪 Try It

🧪 Try It

Tunnel

Quick Start

Protocol

🧪 Try It

🧪 Try It

Memory

🧪 Try It

Query Parameters

🧪 Try It