Agent API

The Agent API runs the two non-intrusive tools, Security headers and Email security, over HTTP. It needs no Turnstile check and no email verification, and works without an API key. All paths are on https://vigilbase.com.

Endpoints

Other tools are not on this API. website-security, react2shell and fortibleed-check run in the browser with email verification, or through Vigilbase One with a signed-in CLI. Asking for them returns 404 with a message that says so.

Run a check

Send a JSON body with one field, target, for example {"target":"https://example.com"}. For security-headers it is a URL or domain (https:// is assumed when you leave out the scheme); for email-security it is a domain.

A successful response looks like this:

{
  "success": true,
  "apiVersion": "1",
  "toolName": "security-headers",
  "target": "https://example.com",
  "grade": "B",
  "gradeScore": 72,
  "result": { "status": "warnings", "message": "...", "details": { } },
  "error": null,
  "uiUrl": "https://vigilbase.com/tools/security-headers",
  "skillUrl": "https://vigilbase.com/agent-skills/security-headers.md"
}

result holds the full scan result, in the same shape the tool page uses. The body may be at most 8 KiB and target at most 2,048 characters.

curl -sS -X POST https://vigilbase.com/api/v1/agent/tools/email-security/execute \
  -H 'content-type: application/json' \
  -d '{"target":"example.com"}'

const response = await fetch(
  "https://vigilbase.com/api/v1/agent/tools/email-security/execute",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ target: "example.com" }),
  },
);
const data = (await response.json()) as { success: boolean; grade: string | null };

Authentication

You can call the API anonymously, or send a developer API key to raise the rate limit. Put the key in either header:

Authorization: Bearer <api_key>
X-Api-Key: <api_key>

An invalid or expired key returns 401; it does not fall back to anonymous access. Create keys in Vigilbase One; see API keys.

Rate limits and quotas

Two limits apply.

The scan quota is shared with the browser tools and counts the same way with or without a key. GET /api/v1/agent/tools returns both limits in its rateLimit field.

Every response carries rate limit headers: RateLimit, RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and the X-RateLimit-* equivalents.

When a limit is used up, the API returns 429 with code rate_limit_exceeded, a Retry-After header and retryAfterSec in the body. Wait that many seconds before trying again. A spent scan quota can mean a wait of up to an hour, and no scan ran.

Errors

Errors use application/problem+json:

{
  "success": false,
  "error": { "code": "rate_limit_exceeded", "message": "...", "hint": "..." },
  "type": "https://vigilbase.com/developers/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "...",
  "code": "rate_limit_exceeded",
  "retryAfterSec": 1800
}

Versioning

Responses carry API-Version: 1. The older unversioned paths under /api/agent/tools still work but send Deprecation and Sunset headers; they are due to be retired on 1 September 2027. Use the /api/v1/ paths.

Reference

See the API reference for every field, or fetch the OpenAPI document at https://vigilbase.com/openapi.json.