Introduction

Welcome to Gödel's Sieve API

Gödel's Sieve is a security analysis platform that provides advanced threat detection through a simple RESTful API. Upload files for deep security analysis and integrate threat detection seamlessly into your workflows.

What is Gödel's Sieve?

Gödel's Sieve analyzes files for security threats, malware, suspicious patterns, and potential vulnerabilities using advanced machine learning models and behavioral analysis. Our API enables developers to:

• Scan files for security threats and malware
• Analyze results with detailed threat scores and severity ratings
• Track activity with comprehensive analytics and reporting
• Secure access using Personal Access Tokens (PAT)

Key Features

Security Scanning

• Upload files up to 32 MB for analysis
• Real-time threat detection and classification
• Detailed threat scores, severity levels, and risk categorization
• Support for compressed file uploads and archives
• Comprehensive scan history and results

API Authentication

• Secure Personal Access Token (PAT) based authentication
• Configurable token expiration
• Easy token management and revocation

Analytics & Reporting

• Daily scan activity trends
• Threat detection summaries
• Usage statistics and metrics

API Capabilities

This documentation covers the complete Gödel's Sieve API:

File Scanning

• Submit files for security analysis
• List scans with filtering and pagination
• Retrieve scan details including threat analysis results

API Key Management

• Create Personal Access Tokens for authentication
• Revoke tokens when compromised or no longer needed

User Management

• Update profile information
• Change password with session revocation
• Manage active sessions across devices

Analytics

• Daily scan trends over 30-day periods
• Summary statistics for threat detection
• Usage metrics for capacity planning

Quick Start

1. Obtain Your API Key

Create a Personal Access Token from the API Keys page in the dashboard, or via the API:

curl -X POST https://api.sieve.godel-labs.ai/api/keys \
  -H "X-API-Key: <EXISTING_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name":"My API Key","expiresIn":180}'

2. Submit a File for Scanning

curl -X POST https://api.sieve.godel-labs.ai/api/upload \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/file.pdf"

3. Retrieve Scan Results

curl https://api.sieve.godel-labs.ai/api/scans/SCAN_ID \
  -H "X-API-Key: YOUR_API_KEY"

Base URL

All API requests should be made to:

https://api.sieve.godel-labs.ai/api

Authentication

All API requests require authentication using a Personal Access Token (PAT) via the X-API-Key header:

X-API-Key: gds_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

See the Authentication page for detailed information on obtaining and using API keys.

Response Format

All API responses are returned as JSON:

{
  "success": true,
  "data": {
    // Response data
  }
}

Error responses follow this format:

{
  "error": "Error message",
  "details": "Additional context (when available)"
}

Common HTTP Status Codes

Rate Limits

• File uploads: Maximum 32 MB per file
• Scan requests: Free tier 5 per 5 min / 20 per hour; premium tier 10,000 per 5 min / 20,000 per hour
• API key generation: 3 per hour / 10 per day (free tier)

Best Practices

Security

• Never commit API keys to version control
• Use environment variables to store keys
• Rotate keys regularly (every 90-180 days)
• Set expiration dates on all tokens
• Revoke immediately if a key is compromised

Integration

• Handle rate limits gracefully with exponential backoff
• Poll scan results rather than keeping connections open
• Cache results when appropriate to reduce API calls
• Use webhooks (when available) instead of polling
• Implement proper error handling for all status codes

Performance

• Compress large files before upload when possible
• Batch operations when supported
• Use pagination for list endpoints
• Filter results at the API level rather than client-side

Support

For questions, issues, or feature requests:

• Documentation: Browse the API reference in the sidebar
• Technical Support: Contact support via the dashboard
• Security Issues: Report immediately to security@example.com

Next Steps

• Learn about Authentication with Personal Access Tokens
• Explore the Scan endpoint to start scanning files
• Check Analytics for usage insights