api_docs.md

SecureHeal Arena - API Reference

Complete reference for every endpoint exposed by the SecureHeal Agent backend on Hugging Face Spaces.

Base URL: https://ravindraog-secureheal-trainer.hf.space

---

GET /health

Returns the current health status of the Space and whether the model is loaded.

Request:

GET /health

Response (200):

{
  "status": "healthy",
  "model_loaded": true,
  "model": "Nitesh-Reddy/secureheal-agent-v2"
}

When to use: Call this before any scan request to confirm the Space is awake and the model is ready. If model_loaded is false, wait 1-2 minutes and retry.

---

POST /scan

Scans a code snippet provided as a JSON body. Runs the full 3-agent debate pipeline (Alpha scanner, Beta attacker, Gamma defender) and returns the combined analysis along with any tool calls the agents produced.

Request:

POST /scan
Content-Type: application/json

Body:

Field	Type	Required	Default	Description
code	string	Yes	-	The source code to analyze
context	string	No	"web application"	Describes the application type (e.g. "flask api", "express server")
max_tokens	integer	No	512	Maximum tokens for the model response

Example:

{
  "code": "cursor.execute(f\"SELECT * FROM users WHERE id = {user_id}\")",
  "context": "flask api",
  "max_tokens": 512
}

Response (200):

{
  "vulnerabilities_found": true,
  "tool_calls": [
    { "tool": "scan_code", "args": {} },
    { "tool": "simulate_attack", "args": { "payload": "1 OR 1=1" } },
    { "tool": "apply_patch", "args": { "patch_code": "cursor.execute(\"SELECT * FROM users WHERE id = ?\", (user_id,))" } }
  ],
  "analysis": "[AGENT ALPHA - RECON SCANNER]\n..."
}

Error Codes:

• 503 - Model is still loading. Retry after a short wait.

---

POST /scan/file

Uploads a source code file for vulnerability scanning. This is what the SecureHeal CLI (secureheal_cli.py) calls under the hood. Supports .py, .js, .ts, .java, .go, .rb, .php, and more.

Request:

POST /scan/file
Content-Type: multipart/form-data

Fields:

Field	Type	Required	Default	Description
file	file (binary)	Yes	-	The source code file to scan
context	string (form)	No	"web application"	Application type hint
max_tokens	integer (form)	No	512	Maximum tokens for the model response

Example (curl):

curl -X POST https://ravindraog-secureheal-trainer.hf.space/scan/file \
  -F "file=@vulnerable_app.py" \
  -F "context=flask api" \
  -F "max_tokens=512"

Response (200):

{
  "vulnerabilities_found": true,
  "tool_calls": [ ... ],
  "analysis": "...",
  "filename": "vulnerable_app.py"
}

Notes:

• Files larger than 8000 characters are automatically truncated to fit the model context window.
• The filename field in the response echoes back the uploaded file name.

Error Codes:

• 400 - File is not a valid text/source code file.
• 503 - Model is still loading.

---

POST /agent

A free-form prompt endpoint. Send any text prompt to the SecureHeal agent and get back a raw response along with any parsed tool calls. This is useful for custom queries outside the standard scan workflow.

Request:

POST /agent
Content-Type: application/json

Body:

Field	Type	Required	Default	Description
prompt	string	Yes	-	Free-form text prompt for the agent
max_tokens	integer	No	512	Maximum tokens for the response

Example:

{
  "prompt": "Explain the OWASP Top 10 vulnerability categories and which ones apply to Python Flask apps.",
  "max_tokens": 256
}

Response (200):

{
  "response": "The OWASP Top 10 covers...",
  "tool_calls": []
}

Error Codes:

• 503 - Model is still loading.

---

GET / (Gradio Dashboard)

The root path serves the VS Code-style Gradio IDE Dashboard. This is the visual interface that judges and users see when they visit the Hugging Face Space directly. It is mounted as a Gradio app on top of the FastAPI backend.

URL: https://ravindraog-secureheal-trainer.hf.space/

This is not an API endpoint in the traditional sense. It renders the interactive web UI.

---

Data Models

VulnerabilityReport

Returned by /scan and /scan/file.

Field	Type	Description
vulnerabilities_found	boolean	Whether the agent detected any issues
tool_calls	array of ToolCall	Parsed tool calls from the agent output
analysis	string	Full text of the multi-agent debate log
filename	string or null	Original filename (only for /scan/file)

ToolCall

Field	Type	Description
tool	string	Name of the tool called (e.g. scan_code, apply_patch)
args	object	Arguments passed to the tool

AgentResponse

Returned by /agent.

Field	Type	Description
response	string	The agent's text response
tool_calls	array of ToolCall	Any tool calls parsed from the response

---

Rate Limits and Constraints

• The Hugging Face Space runs on a T4 GPU with limited concurrency.
• Each scan triggers three sequential model inferences (Alpha, Beta, Gamma), so expect response times of 30 to 90 seconds depending on code length.
• Files over 8000 characters are truncated.
• If the Space has been idle for a while, the first request will take longer because the model needs to load into GPU memory.

---

Related Documentation

For a complete overview of the SecureHeal Arena project, please refer to:

• README.md - Project overview, architecture, and quick start guide.
• TRAINING_EVIDENCE.md - Training curves, reward architecture, and performance benchmarks.
• project_context.md - Detailed hackathon strategy and execution plan.
• hf_blog_post.md - Short blog post explaining the project.
• secureheal_cli.py - CLI source code that calls these endpoints.
• training/train_hf_job.py - GRPO training script.

---

Prepared for the Meta PyTorch OpenEnv Hackathon India 2026 by team codeXcreators.