{
  "openapi": "3.1.0",
  "info": {
    "title": "ScanTheLink Agent API Pilot",
    "version": "1.0.0-pilot",
    "description": "Curated pilot schema for approved ScanTheLink Agent API clients. This is not the public FastAPI /openapi.json export."
  },
  "servers": [
    {
      "url": "https://scanthelink.com"
    }
  ],
  "x-scanthelink-agent-pilot": {
    "phase": "test_buildout",
    "public_payment_launch": false,
    "agent_vip_scan_offer": {
      "offer_id": "agent_vip_scan_usd_1_test_phase",
      "amount": 1,
      "currency": "USD",
      "starter_credits": 10,
      "starter_credit_reason": "test_service_give_feedback_find_bugs",
      "availability": "manual_approval_limited_capacity",
      "notes": "Approved agent accounts receive 10 free starter credits to test ScanTheLink, give feedback, and help identify bugs or missing fields. After the starter credits, they can request Agent VIP Scans for USD 1 per accepted VIP scan during the test and build-out phase."
    },
    "recommended_agent_use": [
      "client audit summary",
      "sales conversation support",
      "proposal preparation",
      "CRM lead qualification",
      "token-saving server-side signal collection"
    ]
  },
  "paths": {
    "/api/v1/scans": {
      "post": {
        "operationId": "createScanTheLinkAgentScan",
        "summary": "Create a ScanTheLink agent scan",
        "description": "Creates a queued website or public profile scan for an approved Agent API key. Use a stable Idempotency-Key per target attempt.",
        "security": [
          {
            "AgentBearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 255
            },
            "description": "Stable retry key. Reusing the same key returns the original request without reserving another credit."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentScanCreateRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Scan accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentScanAcceptedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid target or request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid Agent API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "No pilot credits remaining",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Key paused, revoked, expired, or missing required scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Agent rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scans/{agent_request_id}": {
      "get": {
        "operationId": "getScanTheLinkAgentScanStatus",
        "summary": "Get ScanTheLink agent scan status",
        "description": "Returns the stable status/result envelope for a queued, running, done, or failed agent scan.",
        "security": [
          {
            "AgentBearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "agent_request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scan status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentScanStatusResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid Agent API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Agent scan request not found for this key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AgentBearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "AgentScanCreateRequest": {
        "type": "object",
        "required": ["target"],
        "properties": {
          "target": {
            "type": "string",
            "minLength": 3,
            "maxLength": 500,
            "description": "Public URL, YouTube channel, Facebook page, or X profile."
          },
          "scan_type": {
            "type": "string",
            "enum": ["auto", "website", "youtube", "facebook", "x"],
            "default": "auto"
          },
          "scan_depth": {
            "type": "string",
            "enum": ["basic", "deep"],
            "default": "basic",
            "description": "Deep scans require approved scope."
          }
        },
        "additionalProperties": false
      },
      "AgentCredits": {
        "type": "object",
        "required": ["remaining"],
        "properties": {
          "remaining": {
            "type": "integer"
          }
        },
        "additionalProperties": false
      },
      "AgentScanAcceptedResponse": {
        "type": "object",
        "required": ["schema_version", "request_id", "agent_request_id", "status", "status_url", "credits"],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "scanthelink.agent_scan.v1"
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "agent_request_id": {
            "type": "string",
            "format": "uuid"
          },
          "scan_id": {
            "type": ["string", "null"],
            "format": "uuid"
          },
          "status": {
            "type": "string"
          },
          "status_url": {
            "type": "string",
            "format": "uri"
          },
          "credits": {
            "$ref": "#/components/schemas/AgentCredits"
          }
        },
        "additionalProperties": false
      },
      "AgentScanStatusResponse": {
        "type": "object",
        "required": ["schema_version", "request_id", "agent_request_id", "status", "credits", "signals", "scores", "findings", "meta"],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "scanthelink.agent_scan.v1"
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "agent_request_id": {
            "type": "string",
            "format": "uuid"
          },
          "scan_id": {
            "type": ["string", "null"],
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "running", "done", "failed"]
          },
          "credits": {
            "$ref": "#/components/schemas/AgentCredits"
          },
          "signals": {
            "type": "object"
          },
          "scores": {
            "type": "object"
          },
          "findings": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "meta": {
            "type": "object"
          },
          "error": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AgentErrorDetail"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false
      },
      "AgentErrorDetail": {
        "type": "object",
        "required": ["code", "message", "retryable"],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          },
          "action": {
            "type": ["string", "null"]
          }
        },
        "additionalProperties": false
      },
      "AgentErrorResponse": {
        "type": "object",
        "required": ["schema_version", "request_id", "error"],
        "properties": {
          "schema_version": {
            "type": "string",
            "const": "scanthelink.agent_error.v1"
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "error": {
            "$ref": "#/components/schemas/AgentErrorDetail"
          }
        },
        "additionalProperties": false
      }
    }
  }
}