Guard

API Reference

Complete API documentation for AIVory Guard’s MCP tools and REST endpoints.

5 MCP tools available for AI assistant integration
Bearer token authentication required for all API requests
14+ languages supported including JavaScript, Python, Java, and Go
Structured responses with violations, severity levels, and fix suggestions

Authentication

All API requests (except /api/health) require Bearer token authentication:

Authorization: Bearer your_aivory_api_key

Note Get your API key at https://app.aivory.net/tokens. Keep your key secure and never commit it to version control.

MCP Tools Overview

When using AIVory Guard via MCP integration, these tools are available to your AI assistant:

scan_code

Scan a single file for compliance violations

batch_scan

Scan multiple files efficiently in one request

get_config

Retrieve current compliance configuration

get_rules

List all available compliance rules

health_check

Verify backend connectivity and status

MCP Tool Details

scan_code - Single File Scanning

Scan a single file for compliance violations.

Parameters:

{
  code: string;        // Source code to scan
  language: string;    // Programming language (e.g., "python", "javascript")
  filename?: string;   // Optional filename (default: "main.{ext}")
  standards?: string[]; // Optional compliance standards to check
}

Returns:

{
  status: "completed" | "error";
  violations: Violation[];
  summary: {
    total_violations: number;
    critical: number;
    high: number;
    medium: number;
    low: number;
  };
}

Example (via AI assistant):

You: "Scan this authentication function for OWASP violations"

AI: [Uses scan_code tool automatically]

batch_scan - Multi-File Scanning

Scan multiple files efficiently in a single request.

Parameters:

{
  files: Array<{
    code: string;
    language: string;
    filename?: string;
  }>;
  standards?: string[];
}

Returns:

{
  status: "completed" | "error";
  results: Array<{
    filename: string;
    violations: Violation[];
    summary: ViolationSummary;
  }>;
  overall_summary: ViolationSummary;
}

Example (via AI assistant):

You: "Scan all files in the /api directory"

AI: [Uses batch_scan tool to scan multiple files at once]

Note Use batch_scan instead of multiple scan_code calls for better performance when scanning entire directories or projects.

get_config - Configuration Retrieval

Retrieve current compliance configuration and enabled standards.

Parameters: None

Returns:

{
  standards: string[];  // List of enabled compliance standards
  server_url: string;   // Current backend URL
  version: string;      // AIVory Guard version
}

Example (via AI assistant):

You: "What compliance standards are you checking?"

AI: [Uses get_config tool]

get_rules - Rule Discovery

List all available compliance rules and their descriptions.

Parameters:

{
  standard?: string;  // Optional filter by standard (e.g., "OWASP", "GDPR")
}

Returns:

{
  rules: Array<{
    id: string;
    standard: string;
    category: string;
    severity: "critical" | "high" | "medium" | "low";
    description: string;
  }>;
  total_rules: number;
}

Example (via AI assistant):

You: "What GDPR rules do you check?"

AI: [Uses get_rules with standard filter]

health_check - Service Status

Verify backend connectivity and service status.

Parameters: None

Returns:

{
  status: "healthy" | "degraded" | "down";
  server_url: string;
  latency_ms: number;
  version: string;
}

Example (via AI assistant):

You: "Is AIVory Guard working?"

AI: [Uses health_check tool]

Data Types

Violation Interface

interface Violation {
  severity: "critical" | "high" | "medium" | "low";
  standard: string;        // e.g., "OWASP", "GDPR"
  rule: string;            // e.g., "A03:2021 - Injection"
  message: string;         // Human-readable violation description
  line: number;            // Line number where violation occurs
  column: number;          // Column number where violation occurs
  suggestion: string;      // How to fix the violation
  code_snippet?: string;   // Optional code context
}

ViolationSummary Interface

interface ViolationSummary {
  total_violations: number;
  critical: number;
  high: number;
  medium: number;
  low: number;
}

Supported Languages

AIVory Guard supports these programming languages:

JavaScript / TypeScript

Web and Node.js applications

Python

Data science, web, and scripting

Java

Enterprise applications

Cloud-native and systems

.NET applications

PHP

Web applications

Ruby

Web and scripting

Swift / Kotlin

Mobile development

Rust

Systems programming

C / C++

Systems and embedded

Scala

JVM applications

Shell / SQL

Scripts and queries

Note Use language identifiers like: javascript, typescript, python, java, go, csharp, php, ruby, swift, kotlin, rust, c, cpp, scala, bash, sql.

Error Codes

Code	HTTP Status	Description
`AUTH_ERROR`	401	Invalid or missing API key
`RATE_LIMIT`	429	Too many requests
`INVALID_REQUEST`	400	Malformed request body
`UNSUPPORTED_LANGUAGE`	400	Language not supported
`SERVER_ERROR`	500	Internal server error
`TIMEOUT`	504	Request timeout

Error Response Format

{
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "details": "Additional error details (optional)"
}

Warning Always check for errors in your integration. Handle AUTH_ERROR by prompting for a valid API key, and RATE_LIMIT by implementing exponential backoff.

Rate Limits

Tier	Requests/Minute	Requests/Day
Free	60	1,000
Pro	300	10,000
Enterprise	Custom	Custom

Note When rate limited, you’ll receive a 429 Too Many Requests response with a retry_after_seconds field indicating when to retry.

Rate Limit Response Example

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT",
  "retry_after_seconds": 60
}

Next Steps

Usage Guide

Learn how to use the API effectively

Configuration

Configure your compliance setup

FAQ

Common questions and answers