AI-Infra-Guard API Endpoints for Creating Scan Tasks: Complete Reference

AI-Infra-Guard exposes the POST /api/v1/task/create endpoint to initialize new security scans, accepting a JSON body structured as TaskCreateRequest and returning a TaskCreateResponse containing the unique session identifier.

The Tencent AI-Infra-Guard repository provides infrastructure security scanning through a WebSocket-based HTTP API. Programmatically creating scan tasks enables integration into automated security workflows and CI/CD pipelines. This article examines the exact endpoint specifications, payload schemas, and source code implementation for task creation based on the actual codebase.

The Create Scan Task Endpoint

The system registers the task creation route in common/websocket/server.go. Clients submit HTTP POST requests to this endpoint to instantiate new scanning operations against targets such as web applications or source code repositories.

Route Registration and Handler Mapping

The router binds the POST /api/v1/task/create path to the HandleTaskCreate function. This handler, implemented in common/websocket/task.go, serves as the primary entry point for all task creation requests received by the server.

Internal Processing Flow

When HandleTaskCreate receives a request, it executes the following sequence:

1. Unmarshals the request body into a TaskCreateRequest struct defined in common/websocket/api.go
2. Validates required fields including the target URL and scanType designation
3. Invokes TaskManager.AddTaskApi from common/websocket/task_manager.go to register the task internally
4. Generates a unique session identifier for task tracking
5. Returns a TaskCreateResponse JSON object containing the session ID and creation timestamp

Request and Response Structures

The API uses strict Go structs for task creation payloads, with type definitions centralized in common/websocket/api.go and documented via Swagger specifications in docs/docs.go.

TaskCreateRequest Schema

The request body must conform to the TaskCreateRequest structure with the following fields:

• target: The URL or repository path to scan (string, required)
• scanType: The scan category such as "web", "code", or "mcp" (string, required)
• taskName: Optional human-readable identifier (string)
• agentProvider: File path to agent configuration YAML (string, optional)
• extraOptions: Map of scan-specific parameters including depth and timeout (object)

{
  "target": "http://example.com",
  "scanType": "web",
  "taskName": "ProductionSecurityAudit",
  "agentProvider": "/config/provider.yaml",
  "extraOptions": {
    "depth": 3,
    "timeout": 120
  }
}

TaskCreateResponse Schema

On successful creation, the server returns HTTP 200 with a TaskCreateResponse body containing:

• sessionId: Unique identifier for tracking the scan task lifecycle (string)
• createdAt: Unix timestamp in milliseconds indicating creation time (integer)

The response is wrapped in a standard API envelope with status and message fields:

{
  "status": 0,
  "message": "task created successfully",
  "data": {
    "sessionId": "1a2b3c4d5e6f7g8h9i0j",
    "createdAt": 1724587200000
  }
}

Source Code Implementation Details

The task creation logic spans several files within the common/websocket package to separate routing, handling, and persistence concerns.

Task Manager Integration

The HandleTaskCreate handler delegates task persistence to the TaskManager class via the AddTaskApi method. This function resides in common/websocket/task_manager.go and is responsible for registering the task in the internal state machine and initiating the asynchronous scanning workflow.

Swagger Documentation

OpenAPI specifications in docs/docs.go formally document the TaskCreateResponse schema and possible HTTP response codes. These definitions enable automatic client generation and interactive API exploration through Swagger UI.

Practical Usage Example

The following Python script demonstrates creating a scan task against a running AI-Infra-Guard instance:

import requests

url = "http://localhost:8080/api/v1/task/create"
payload = {
    "target": "https://github.com/example/repo",
    "scanType": "code",
    "taskName": "RepositorySecurityScan",
    "extraOptions": {
        "depth": 5,
        "timeout": 300
    }
}

response = requests.post(url, json=payload)
data = response.json()

if data.get("status") == 0:
    print(f"Task created. Session ID: {data['data']['sessionId']}")
else:
    print(f"Error: {data.get('message')}")

Summary

• Primary endpoint: POST /api/v1/task/create is registered in common/websocket/server.go
• Request handler: HandleTaskCreate in common/websocket/task.go processes incoming requests and validates payloads
• Request structure: TaskCreateRequest defined in common/websocket/api.go requires target and scanType fields
• Response structure: TaskCreateResponse returns sessionId and createdAt within a standard API data wrapper
• Internal registration: TaskManager.AddTaskApi in common/websocket/task_manager.go persists task state
• API documentation: OpenAPI schemas reside in docs/docs.go for specification validation

Frequently Asked Questions

What is the exact URL path for creating scan tasks in AI-Infra-Guard?

The API endpoint is strictly POST /api/v1/task/create. This route is hardcoded in the router configuration within common/websocket/server.go and bound to the HandleTaskCreate handler. Requests sent to this path must include a valid JSON body matching the TaskCreateRequest schema defined in common/websocket/api.go.

Which fields are mandatory in the TaskCreateRequest payload?

According to the struct definitions in common/websocket/api.go, the target and scanType fields are required. The target specifies the subject URL or repository path, while scanType determines which scanning engine to invoke (web, code, or mcp). Optional fields include taskName for human-readable identification, agentProvider for custom configuration paths, and extraOptions for scan-specific parameters.

How does the server handle errors during task creation?

The HandleTaskCreate handler returns standard HTTP status codes with structured JSON error responses. Validation failures against the TaskCreateRequest schema return HTTP 400 Bad Request, while internal system failures return HTTP 500 Internal Server Error. Error responses follow the format defined in docs/docs.go, containing status and message fields describing the failure reason.

Where is the session ID generated when creating a new scan task?

The unique session identifier is generated within the TaskManager.AddTaskApi method located in common/websocket/task_manager.go. This ID is created during the internal registration phase before the HandleTaskCreate handler constructs the TaskCreateResponse, ensuring every task receives a distinct tracking identifier returned in the response data object.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}