openapi: 3.0.3
info:
  title: Agent-Shield
  version: 0.1.0
  description: >-
    Security scanner for AI agent workflows. Scan prompts, tool outputs,
    emails and webpages for prompt injection, leaked secrets, exposed PII
    and SSRF-risk URLs before acting on them. Raw content is never stored —
    only a SHA-256 hash and aggregate match counts.
  contact:
    name: Startek Enterprise Solutions LLC
    url: https://agent-shield.startekenterprises.com/
servers:
  - url: https://agent-shield.startekenterprises.com
security:
  - ApiKeyAuth: []
paths:
  /health:
    get:
      summary: Liveness check
      security: []
      responses:
        '200':
          description: Service is up
  /v1/signup:
    post:
      summary: Create an API key (no auth, no email required)
      security: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  description: Human/agent-readable label for the key
                email:
                  type: string
                  description: Optional, for key recovery notices
      responses:
        '200':
          description: API key created
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_key: { type: string }
                  tier: { type: string, example: free }
                  quota_per_day: { type: integer, example: 1000 }
  /v1/scan:
    post:
      summary: Scan text for threats
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content:
                  type: string
                  description: The text to scan (max 200k chars)
                content_type:
                  type: string
                  enum: [text, prompt, tool_output, email, webpage]
                  default: text
                mode:
                  type: string
                  enum: [detect, enforce]
                  default: detect
                  description: detect reports only; enforce adds an action field (block/review/allow)
                offsets:
                  type: boolean
                  default: false
                  description: include character offsets (positions only, never matched text) in findings
                sensitivity:
                  type: string
                  enum: [low, medium, high]
                  description: per-request sensitivity override; default comes from the API key (POST /v1/sensitivity)
      responses:
        '200':
          description: Scan result
          content:
            application/json:
              schema:
                type: object
                properties:
                  verdict: { type: string, enum: [clean, suspicious, malicious] }
                  mode: { type: string, enum: [detect, enforce] }
                  action: { type: string, enum: [allow, review, block], description: 'enforce mode only' }
                  sensitivity: { type: string, enum: [low, medium, high] }
                  scores:
                    type: object
                    properties:
                      prompt_injection: { type: number }
                      secrets_exposure: { type: number }
                      pii_disclosure: { type: number }
                      ssrf_risk: { type: number }
                  findings:
                    type: array
                    items:
                      type: object
                      properties:
                        class: { type: string }
                        match_count: { type: integer }
                        detail: { type: object }
                  analyzer: { type: string }
                  content_hash: { type: string }
                  scanned_chars: { type: integer }
        '401': { description: Missing or invalid API key }
        '429': { description: Daily quota exceeded }
  /v1/subscribe:
    post:
      summary: Upgrade to Pro (returns Stripe Checkout URL)
      responses:
        '200':
          description: Checkout session created
  /v1/sensitivity:
    post:
      summary: Set per-key default sensitivity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sensitivity]
              properties:
                sensitivity:
                  type: string
                  enum: [low, medium, high]
      responses:
        '200':
          description: Sensitivity updated
  /mcp:
    post:
      summary: MCP Streamable HTTP (JSON-RPC 2.0), tool shield.scan
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key