Navigation
VigilbaseDocs

    Type at least two letters.

    Open Vigilbase One
    Agent APIAgent tools

    Run an agent tool

    Runs a non-intrusive scan: security-headers grades a URL's HTTP security headers, email-security a domain's email authentication records. Each client IP and each target gets 20 scans an hour, with or without an API key; anonymous scans also spend the network's daily free tool allowance. A scan that ran but reported an error answers 422 with the scanner's output and no grade. Other tool names answer 404 with where they run instead.

    Deprecated aliases: POST https://vigilbase.com/api/v1/agent/tools/{toolName}/execute (410 Gone from 2027-02-01), POST https://vigilbase.com/api/agent/tools/{toolName}/execute (410 Gone from 2027-02-01). They answer with the same bodies, with a Deprecation header and a successor-version link to this URL. Until their Sunset date; from then on they answer 410 Gone with the successor URL.

    POST/agent/tools/{toolName}/execute

    Authorizations

    Optional. Without a key, requests use the anonymous free tier. Send one of these headers:

    Authorizationstringheader

    Developer API key (prefix vb_dev_), as a Bearer token or in the X-Api-Key header. Format: Bearer <token>. Scope: tools:execute.

    Path Parameters

    toolNamestringrequired

    The tool to run: security-headers or email-security.

    pattern ^[a-z0-9][a-z0-9-]{0,63}$

    Body

    application/json
    targetstringrequired

    Scan target. For security-headers prefer a full URL; for email-security use an apex domain.

    min length 1max length 2048

    Response

    application/json

    Success

    successbooleanrequired
    Value:true
    apiVersionstring
    toolNamestringrequired
    targetstringrequired
    gradeanyrequired
    gradeScorenumber | nullrequired
    resultanyrequired

    What the scanner returned.

    errornull

    Always null on success; failures are problem details.

    uiUrlstringuri
    skillUrlstringuri
    4 response headers
    X-Request-Idstring

    The request ID: yours when it was well-formed, otherwise a new one. Quote it to support.

    API-Versionstring

    The major API version (informational; the version is in the path).

    RateLimitstring

    Remaining quota under the "default" policy (draft-ietf-httpapi-ratelimit-headers-11).

    RateLimit-Policystring

    The "default" policy: quota and window (draft-ietf-httpapi-ratelimit-headers-11).

    Was this page helpful?