# API Reference

This API reference provides essential information for developers integrating with the SigilAI Cloud Model Context Protocol (MCP) server. It covers authentication, MCP message structure, tool invocation, and general API behavior.

### Endpoint

All MCP communication with the SigilAI Cloud server occurs over HTTPS using Server-Sent Events (SSE).

* **Production Endpoint**: `https://mcp.sigilai.io/sse`  _(This is an example. Always use the endpoint URL provided in your SigilAI account dashboard.)_

### Authentication

Requests to the SigilAI MCP server must be authenticated using an API key.

* **Method**: Bearer Token Authentication.
* **Header**: `Authorization`
* **Value**: `Bearer YOUR_SIGILAI_API_KEY`

Replace `YOUR_SIGILAI_API_KEY` with the actual API key obtained from your SigilAI account dashboard.

**Example Request Header:**

```
Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxx
Accept: text/event-stream
Content-Type: application/json
```

Failure to authenticate correctly will result in an HTTP `401 Unauthorized` or `403 Forbidden` error, or an MCP `error` message.

### MCP Message Structure

SigilAI adheres to the Model Context Protocol. All messages exchanged between the client and server are JSON objects. Key message types include:

* **Client to Server**:
  * `tool_call`: Used to invoke a specific tool.
    * `type`: "tool\_call"
    * `id`: (Optional) A unique ID for the call, will be echoed in the `tool_result`.
    * `name`: The name of the tool to invoke (e.g., "scan\_url", "scan\_file").
    * `parameters`: An object containing the parameters for the tool.
* **Server to Client**:
  * `server_info`: Provides information about the server upon connection.
  * `tool_result`: Contains the result of a `tool_call`.
    * `type`: "tool\_result"
    * `id`: (Optional) The ID from the corresponding `tool_call`.
    * `name`: The name of the tool that was invoked.
    * `result`: A string (typically JSON stringified) containing the tool's output.
  * `error`: Indicates an error occurred.
    * `type`: "error"
    * `message`: A human-readable error message.
    * `code`: (Optional) An error code.

Refer to the official Model Context Protocol specification for complete details on message types and structures.

### Available Tools

The following primary tools are available. Detailed capabilities and tier-specific features are described below for each tool.

#### 1. URL Scanner (`scan_url`)

Scans a URL for security threats.

* **Name**: `scan_url`
* **Parameters**:
  * `url` (string, required): The URL to scan.
    * _Pro/Enterprise Tiers_: May support an array of URLs for batch scanning. Consult your plan details.
  * `userId` (string, optional): An identifier for the end-user or context of the scan.
  * `options` (object, optional): Advanced scanning options (tier-dependent).
    * `force_rescan` (boolean, optional): If true, forces a fresh scan, bypassing any cached results.
    * `analysis_depth` (enum, optional): e.g., "quick", "full".
* **Expected Result (`result` field in `tool_result` message - JSON stringified)**:  \
  A JSON object containing:
  * `url` (string): The submitted URL.
  * `domain` (string): The extracted domain.
  * `isSafe` (boolean): Overall safety assessment.
  * `riskScore` (number, optional): A numerical risk score.
  * `findings` (array of objects): Detailed threats found. Each finding may include `type`, `description`, `confidence`.
  * `isBlacklisted` (boolean): Whether the domain is on known blacklists.
  * `warnings` (array of strings): Contextual warnings.
  * `md5` (string): MD5 hash of the domain.
  * `scanId` (string): A unique identifier for this scan.
  * `timestamp` (string): ISO 8601 timestamp of the scan.    _(example; actual fields may vary slightly.)_

#### 2. File Scanner (`scan_file`)

Scans source code file content for vulnerabilities. (Tool name might also be "SigilAI Code Scanner" or similar; check `server_info` or your dashboard).

* **Name**: `scan_file` (or as specified by the server)
* **Parameters**:
  * **Single File Scan (All Tiers)**:
    * `file` (object, required):
      * `path` (string, required): Relative path of the file (e.g., "src/app.js").
      * `content` (string, required): The source code content.
  * **Batch File Scan (Pro/Enterprise Tiers)**:
    * `files` (array of file objects, required): Each object with `path` and `content`.
  * **Repository Scan (Enterprise Tier)**:
    * `repositoryUrl` (string, required): URL of the Git repository.
  * **Common Optional Parameters**:
    * `analysisProfile` (string, optional): e.g., "quick\_scan", "deep\_analysis".
    * `manifestFileContent` (object, optional): Content of manifest files (e.g., `{"package.json": "...", "yarn.lock": "..."}`) for dependency scanning.
    * `options` (object, optional): Advanced options (tier-dependent).
* **Expected Result (`result` field in `tool_result` message - JSON stringified)**:  \
  A JSON object (for single file) or an array/summary (for batch/repo) containing:
  * `filePath` (string): Path of the scanned file.
  * `scanId` (string): Unique scan identifier.
  * `timestamp` (string): ISO 8601 timestamp.
  * `status` (string): e.g., "completed", "error".
  * `summary` (object): Counts of findings by severity (critical, high, etc.), overall safety assessment.
  * `findings` (array of objects): Detailed vulnerabilities. Each finding may include `ruleId`, `analysisType`, `severity`, `message`, `lineStart`, `lineEnd`, `codeSnippet`, `remediation`, `cwe`, `owasp`.
  * `dependencies` (object, optional): Results from dependency scanning, including vulnerable packages.    _(example; actual fields may vary slightly.)_

#### 3. Diagnostic Tool (e.g., `ping_server`)

A simple tool to verify connectivity and server responsiveness. The exact name and functionality may vary.

* **Name**: (e.g., `ping_server`, `test_connection` - check `server_info` or dashboard)
* **Parameters**: Typically none, or an optional `message` string.
*   **Expected Result**: A simple JSON object confirming success, possibly echoing the message and providing a server timestamp.

    ```json
    {
      "status": "success",
      "message": "Pong from SigilAI MCP Server!",
      "serverTime": "2023-10-27T12:00:00Z"
    }
    ```

### Rate Limits

API requests and tool invocations are subject to rate limits based on your subscription tier.

* **Free/Open Beta Tier**: Limited requests per hour/day, suitable for evaluation.
* **Pro Tier**: Significantly higher limits for production use.
* **Enterprise Tier**: Custom high-volume limits, often with dedicated throughput.

If you exceed your rate limit, the server will typically respond with an HTTP `429 Too Many Requests` status code or an MCP `error` message. Implement retry logic with exponential backoff in your client. Specific rate limit details are provided in your SigilAI account dashboard or plan agreement.

### Error Handling

The SigilAI MCP server will return errors using standard HTTP status codes for connection-level or authentication issues, and MCP `error` messages for protocol or tool-level issues.

* **Common HTTP Errors**:
  * `401 Unauthorized`: Invalid or missing API key.
  * `403 Forbidden`: API key is valid but does not have permission for the requested action/tier.
  * `429 Too Many Requests`: Rate limit exceeded.
  * `5xx Server Error`: An unexpected error occurred on the server-side.
*   **MCP `error` Message**:

    ```json
    {
      "type": "error",
      "message": "A human-readable description of the error.",
      "code": "OPTIONAL_ERROR_CODE", // e.g., "INVALID_PARAMETERS", "TOOL_EXECUTION_FAILED"
      "details": { /* Optional additional error details */ }
    }
    ```

Your client should be prepared to handle these errors gracefully.

### Client Libraries

SigilAI may provide official client libraries for popular programming languages (e.g., Node.js, Python) to simplify integration. These libraries typically handle:

* MCP message construction and parsing.
* SSE connection management.
* Authentication header injection.
* Convenience methods for tool calls.

Check the SigilAI developer portal or your account dashboard for available client libraries and their documentation. Using an official library is highly recommended.

***

This concludes the Technical Guide section. Next: [Resources](../resources)
