Overview

The Save API (running on port 3001 by default) serves as a proxy to fetch HTML content from a user-provided URL. It then forwards this HTML content to the Scan API for accessibility analysis.

Main Endpoint: POST /

This is the primary endpoint for the Save API. It fetches content from the specified URL and sends it for scanning.

Request

Responses

Success

If the URL is fetched successfully and the Scan API processes the content, this endpoint will return a JSON response. This response includes all fields from the Scan API's successful scan result, and additionally includes the fetched HTML content of the target URL under the htmlContent key. The HTTP status code will match the Scan API's response status (typically 200 OK for a successful scan).

Example Success Response Structure:

{
    // Fields from the Scan API response (e.g., scan summary, issues found)
    "originalScanField1": "value1",
    "originalScanField2": { /* ... */ },
    // ... other fields from Scan API ...

    // Added by the Save API
    "htmlContent": "<!DOCTYPE html><html><head>...</head><body>...</body></html>"
}

For details on the fields returned by the Scan API part of the response, please refer to the Scan API Documentation.

Error Responses


Note: More specific user-friendly messages are provided for common HTTP errors:
  • 401 Unauthorized: "Access to [urlToSave] was unauthorized (401). Authentication might be required."
  • 403 Forbidden: "Access to [urlToSave] was forbidden (403). The site might be blocking automated access."
  • 404 Not Found: "The URL [urlToSave] was not found (404). Please check the URL."
The generic message format (e.g., for other statuses) is shown in the example.
Status Code Condition Response Body Example
400 Bad Request URL is missing in the request body. 
{
    "success": false,
    "message": "URL is required in the request body."
}
400 Bad Request Invalid URL format (fails initial regex check). 
{
    "success": false,
    "message": "Invalid URL format. Please provide a valid URL (e.g., example.com, http(s)://example.com)."
}
400 Bad Request Invalid URL structure or protocol (fails advanced parsing, e.g., missing hostname, non-http/https protocol after normalization). 
{
    "success": false,
    "message": "Invalid URL: [Details from parser, e.g., 'Hostname is missing.' or 'Invalid protocol: foo:']. Please ensure the URL is correctly formatted and uses http or https."
}
Dynamic (e.g., 404, 500) Failed to fetch the external URL. Status code matches the external server's response. 
// Generic message format:
{
    "success": false,
    "message": "Failed to fetch URL [urlToSave]. Status: [status] [statusText]."
}
Dynamic (e.g., 400, 500) The Scan API service returned an error. Status code matches the Scan API's response. 
{
    "success": false,
    "message": "Scan service failed. Detail: [detailMessageFromScanAPI]"
}
500 Internal Server Error A general error occurred while processing the URL. 
{
    "success": false,
    "message": "Error processing [urlToSave]: [errorMessage]"
}

Status Endpoint: GET /status

Provides the operational status of the Save API.

Request

Response (Success 200 OK)

{
    "status": "active",
    "service": "save-api",
    "timestamp": "ISO_Date_String (e.g., 2023-10-27T10:00:00.000Z)"
}

Internal Configuration Endpoint: POST /set-internal-scan-mode

This endpoint is primarily for internal/development use. It allows dynamic configuration of the internal Scan API service URL that this Save API instance will communicate with.

Request

Responses

Success (200 OK)

When target is local:

{
    "success": true,
    "message": "Save service scan target set to local."
}

When target is server:

{
    "success": true,
    "message": "Save service scan target set to server."
}

Error (400 Bad Request)

If the target parameter is invalid or missing:

{
    "success": false,
    "message": "Invalid target parameter. Use \"local\" or \"server\"."
}