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

> Discover AI-Infra-Guard API endpoints for scan tasks. Learn how to use POST /api/v1/task/create to initialize security scans with TaskCreateRequest and get TaskCreateResponse.

- Repository: [Tencent/AI-Infra-Guard](https://github.com/tencent/AI-Infra-Guard)
- Tags: api-reference
- Published: 2026-08-25

---

**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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/api.go) and documented via Swagger specifications in [`docs/docs.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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)

```json
{
  "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:

```json
{
  "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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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:

```python
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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/server.go)
- **Request handler**: `HandleTaskCreate` in [`common/websocket/task.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/task.go) processes incoming requests and validates payloads
- **Request structure**: `TaskCreateRequest` defined in [`common/websocket/api.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/task_manager.go) persists task state
- **API documentation**: OpenAPI schemas reside in [`docs/docs.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/common/websocket/api.go).

### Which fields are mandatory in the TaskCreateRequest payload?

According to the struct definitions in [`common/websocket/api.go`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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`](https://github.com/Tencent/AI-Infra-Guard/blob/main/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.