Clausi API Documentation

Base URL: /api/clausi

Authentication

All endpoints require an OpenAI API key, which can be provided in two ways:

  1. X-OpenAI-Key header
  2. Authorization: Bearer <key> header

Endpoints

1. Health Check

GET /health

Simple health check endpoint to verify API availability.

Response:

{
    "status": "healthy"
}

2. Token Estimation

POST /estimate

Estimates token usage and cost before running a full compliance scan.

Request Body:

{
    "path": "string",
    "regulation": "string",  // Optional, for backward compatibility
    "regulations": ["string"],  // Optional, list of regulations to check
    "mode": "string",
    "metadata": {
        "path": "string",
        "files": [
            {
                "path": "string",
                "content": "string"
            }
        ]
    },
    "output_dir": "string"  // Optional
}

Response:

{
    "total_tokens": 1234,
    "prompt_tokens": 1000,
    "completion_tokens": 234,
    "estimated_cost": 0.002,
    "regulation_breakdown": [
        {
            "regulation": "EU-AIA",
            "total_tokens": 1234,
            "estimated_cost": 0.002
        }
    ],
    "file_breakdown": [
        {
            "path": "path/to/file.py",
            "tokens": 200,
            "estimated_cost": 0.0004,
            "too_large": false
        }
    ]
}

3. Compliance Scan

POST /scan

Runs a full compliance scan and generates a PDF report.

Request Body: Same as /estimate endpoint

Response:

{
    "findings": [
        {
            "clause_id": "A.1.2",
            "violation": true,
            "severity": "high",
            "location": "file.py:123",
            "description": "Description of the finding"
        }
    ],
    "token_usage": {
        "total_tokens": 1234,
        "cost": 0.002
    },
    "report_content": "hex_encoded_report_content",
    "report_filename": "report.pdf"
}

4. Get Report

GET /report/{filename}

Retrieves a previously generated report.

Response:

  • PDF file with application/pdf content type

Error Responses

All endpoints return standard HTTP error codes with JSON responses:

{
    "detail": "Error message"
}

Common error codes:

  • 400: Bad Request (invalid input)
  • 401: Unauthorized (invalid or missing API key)
  • 404: Not Found (report not found)
  • 500: Internal Server Error

Rate Limits

  • No explicit rate limits, but consider OpenAI's API limits
  • Recommended to use the /estimate endpoint before running full scans

Best Practices

  1. Always call /estimate first to understand potential costs
  2. Use the regulations array for multiple regulation checks
  3. Handle the hex-encoded PDF content appropriately in your client
  4. Implement proper error handling for all responses
  5. Monitor token usage and costs through the provided metrics

Example Usage

import requests

headers = {
    "X-OpenAI-Key": "your-openai-key"
}

# Estimate tokens
estimate_response = requests.post(
    "http://your-api/api/clausi/estimate",
    headers=headers,
    json={
        "path": "project",
        "regulations": ["EU-AIA"],
        "mode": "ai",
        "metadata": {
            "path": "project",
            "files": [
                {
                    "path": "file.py",
                    "content": "your code content"
                }
            ]
        }
    }
)

# Run scan if estimate is acceptable
if estimate_response.json()["estimated_cost"] < your_threshold:
    scan_response = requests.post(
        "http://your-api/api/clausi/scan",
        headers=headers,
        json=estimate_response.request.json
    )
    
    # Save the PDF report
    pdf_content = bytes.fromhex(scan_response.json()["report_content"])
    with open(scan_response.json()["report_filename"], "wb") as f:
        f.write(pdf_content)