{
  "openapi": "3.1.0",
  "info": {
    "title": "SLF Guardian Security API",
    "version": "1.2.0",
    "summary": "Security checks an AI agent can call before it delivers code, installs a dependency or trusts a website.",
    "description": "Three tools, one HTTP call each, JSON in and JSON out. audit_code statically audits source code for malware, exfiltration and hard-coded secrets without executing it. check_package verifies that a PyPI or npm dependency actually exists and is safe to install. scan_site checks a website passively from the outside. An agent can create its own key without human involvement: POST /v1/keys. 25 calls are free, then 0.01 USD per call.",
    "contact": {
      "name": "SLF Guardian",
      "email": "team@slfguardian.com",
      "url": "https://slfguardian.com/api"
    },
    "termsOfService": "https://slfguardian.com/terms"
  },
  "servers": [
    {
      "url": "https://slfguardian.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/keys": {
      "post": {
        "operationId": "createKey",
        "summary": "Create an API key. No human approval, no card; returns the raw key once.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "label": {
                    "type": "string",
                    "description": "Free-text label, e.g. the agent name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Key created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "key": {
                      "type": "string",
                      "description": "Shown once; store it."
                    },
                    "credits": {
                      "type": "integer"
                    },
                    "price_usd_per_call": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many keys from this address today."
          }
        }
      }
    },
    "/v1/audit": {
      "post": {
        "operationId": "auditCode",
        "summary": "Audit source code before delivering, committing or executing it.",
        "description": "Static text analysis: the code is never executed and no URL in it is fetched, so hostile input is safe to submit. Detects remote execution (curl | bash, eval of a fetched response, reverse shells), exfiltration of environment variables and credential files, destructive commands, base64 or hex payloads that decode to code, hard-coded API keys and private keys (returned redacted), npm install hooks, typo-squatted package names and unsafe patterns such as shell=True, pickle.loads, yaml.load, disabled TLS verification and SQL built by concatenation. Code is audited in memory and not stored.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "A single snippet or file."
                  },
                  "path": {
                    "type": "string",
                    "description": "File name for the snippet; the extension selects language rules."
                  },
                  "files": {
                    "type": "array",
                    "description": "Several files at once, up to 40 and 400 KB in total.",
                    "items": {
                      "type": "object",
                      "required": [
                        "path",
                        "content"
                      ],
                      "properties": {
                        "path": {
                          "type": "string"
                        },
                        "content": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "verdict": {
                      "type": "string",
                      "enum": [
                        "pass",
                        "warn",
                        "review",
                        "block"
                      ]
                    },
                    "safe_to_deliver": {
                      "type": "boolean",
                      "description": "False for review and block. The single boolean an agent can branch on."
                    },
                    "score": {
                      "type": "integer"
                    },
                    "grade": {
                      "type": "string"
                    },
                    "counts": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "integer"
                      }
                    },
                    "findings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "cat": {
                            "type": "string"
                          },
                          "sev": {
                            "type": "string",
                            "enum": [
                              "critical",
                              "high",
                              "medium",
                              "low"
                            ]
                          },
                          "path": {
                            "type": "string"
                          },
                          "line": {
                            "type": "integer"
                          },
                          "evidence": {
                            "type": "string"
                          },
                          "note": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "packages": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "credits_left": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad input; not billed."
          },
          "401": {
            "description": "Unknown or disabled key."
          },
          "402": {
            "description": "Out of credits."
          },
          "429": {
            "description": "Rate limited."
          }
        }
      }
    },
    "/v1/package": {
      "post": {
        "operationId": "checkPackage",
        "summary": "Check whether a PyPI or npm package is real and safe to install.",
        "description": "Asks the registry and OSV directly. A name that does not exist comes back as block, because installing an invented name is how slopsquatting attacks land. Also reports near-misses of popular package names, known vulnerabilities, age, download volume, npm install scripts and deprecated or yanked releases. Up to 20 packages per call, one credit per call.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ecosystem": {
                    "type": "string",
                    "enum": [
                      "pypi",
                      "npm"
                    ]
                  },
                  "name": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string",
                    "description": "Optional; pins the vulnerability check to one version."
                  },
                  "packages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "ecosystem",
                        "name"
                      ],
                      "properties": {
                        "ecosystem": {
                          "type": "string",
                          "enum": [
                            "pypi",
                            "npm"
                          ]
                        },
                        "name": {
                          "type": "string"
                        },
                        "version": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Package verdicts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "verdict": {
                      "type": "string",
                      "enum": [
                        "pass",
                        "warn",
                        "review",
                        "block"
                      ]
                    },
                    "safe_to_install": {
                      "type": "boolean"
                    },
                    "exists": {
                      "type": "boolean"
                    },
                    "suggestion": {
                      "type": "string",
                      "description": "Popular package this name resembles, if any."
                    },
                    "flags": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "sev": {
                            "type": "string"
                          },
                          "note": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "advisories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "summary": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "facts": {
                      "type": "object",
                      "properties": {
                        "latest_version": {
                          "type": "string"
                        },
                        "releases": {
                          "type": "integer"
                        },
                        "first_release_days_ago": {
                          "type": "integer"
                        },
                        "last_release_days_ago": {
                          "type": "integer"
                        },
                        "downloads_last_month": {
                          "type": "integer"
                        },
                        "install_scripts": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "block": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Batch mode: names that must not be installed."
                    },
                    "review": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "credits_left": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown ecosystem or invalid name; not billed."
          }
        }
      }
    },
    "/v1/scan": {
      "post": {
        "operationId": "scanSite",
        "summary": "Passive outside-in security check of a website.",
        "description": "Looks at the site as an ordinary visitor: malware and spam injection traces, hidden redirects, SSL/TLS certificate state, security headers, software versions visible from outside and SPF/DMARC email spoofing protection. Does not log in, does not run attack tests and does not slow the site down.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "Domain or URL, e.g. example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scan result with score, grade and findings by category."
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "operationId": "getUsage",
        "summary": "Credits left and calls made for the current key.",
        "responses": {
          "200": {
            "description": "Usage.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "credits_left": {
                      "type": "integer"
                    },
                    "calls": {
                      "type": "integer"
                    },
                    "price_usd_per_call": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/prompt": {
      "post": {
        "summary": "Check text, HTML or a page for prompt injection",
        "description": "Static analysis of untrusted content for instructions aimed at a model: CSS-hidden text, HTML comments, zero-width and Unicode tag smuggling, chat template markers, system-prompt or credential exfiltration, silent-mode and approval-forcing phrasing, markdown image exfiltration. The content is never followed or executed. Returns verdict (pass/warn/review/block), injection_detected and clean_text.",
        "operationId": "v1_prompt",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "html": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string",
                    "description": "public page to fetch and check"
                  }
                },
                "required": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "verdict, injection_detected, findings, clean_text",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "missing or unknown key"
          },
          "402": {
            "description": "no credits left; body lists how to pay"
          },
          "429": {
            "description": "rate limit"
          }
        }
      }
    },
    "/v1/command": {
      "post": {
        "summary": "Check whether a shell or SQL command can be undone",
        "description": "Static analysis of a command before it runs: recursive and system-path deletes, disk writes, history wiping, firewall changes, force push, hard reset, docker volume and kubernetes deletes, terraform destroy, cloud deletion, DROP/TRUNCATE, DELETE or UPDATE with no WHERE. Nothing is executed and no variable is expanded. Returns verdict, reversible, safe_to_run, needs_human_approval and a safer alternative per finding.",
        "operationId": "v1_command",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "command": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string",
                    "enum": [
                      "shell",
                      "sql",
                      "auto"
                    ]
                  },
                  "commands": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    },
                    "description": "up to 20 in one call"
                  }
                },
                "required": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "verdict, reversible, safe_to_run, findings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "missing or unknown key"
          },
          "402": {
            "description": "no credits left; body lists how to pay"
          },
          "429": {
            "description": "rate limit"
          }
        }
      }
    },
    "/v1/domain": {
      "post": {
        "summary": "Check whether a domain looks legitimate",
        "description": "Public registration record (RDAP) and DNS plus hostname analysis: registration age, registry status, resolution, brand lookalikes and typo-squats, brand in a subdomain, punycode and mixed-script labels, shorteners, disposable hosting, abuse-heavy TLDs and phishing wording. The site itself is not contacted; use /v1/scan for the page. Returns verdict, safe_to_trust and safe_to_open.",
        "operationId": "v1_domain",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string",
                    "description": "domain or full URL"
                  },
                  "domains": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "up to 20 in one call"
                  }
                },
                "required": []
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "verdict, safe_to_trust, findings, facts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "missing or unknown key"
          },
          "402": {
            "description": "no credits left; body lists how to pay"
          },
          "429": {
            "description": "rate limit"
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "summary": "Aggregate findings across all callers",
        "description": "Counts only: which finding categories fire most often and which package names come back missing or typo-squatted. No submitted code, text, command or URL is stored, and no row is linked to a caller. No API key required.",
        "operationId": "stats",
        "security": [],
        "responses": {
          "200": {
            "description": "Aggregate counters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer slf_live_..."
      }
    }
  }
}