HOLE Foundation API

Welcome to the HOLE Foundation API documentation. Our unified API provides access to transparency laws, legal document search, FOIA request management, and AI-powered legal research.

What is the HOLE Foundation API?

The HOLE Foundation API is a comprehensive platform for accessing:

• Transparency Laws - Complete database of US transparency and public records laws across 52 jurisdictions
• Legal Document Search - Hybrid vector + keyword search across legal documents and statutes
• FOIA Dashboard - Manage Freedom of Information Act requests with tracking and automation
• AI Legal Research - Chat with an AI assistant trained on transparency law

Key Features

🔍 Powerful Search

Hybrid search combining vector embeddings (semantic) with keyword matching for precise legal research:

1
const results = await client.vectorSearch.search({
2
  query: "FOIA exemptions for national security",
3
  limit: 10,
4
  includeContext: true
5
});

📚 Comprehensive Data

Access to:

• 52 jurisdictions (Federal + 50 states + DC)
• 990+ rights of access with full statutory text
• 365+ exemptions categorized and cross-referenced
• Complete statute citations and legal analysis

🤖 AI-Powered

Stream responses from an AI assistant trained on transparency law:

1
for chunk in client.chat.send_message(
2
    message="What are common FOIA exemptions?",
3
    stream=True
4
):
5
    print(chunk, end="")

🔐 Secure Authentication

Enterprise-grade security with Auth0 JWT authentication:

• OAuth 2.0 / OIDC support
• Machine-to-machine (M2M) authentication
• Row-level security on sensitive data
• API key management

Quick Start

1. Get API Access

Contact us to get your Auth0 credentials and API access.

2. Install SDK

$
npm install @hole-foundation/api

3. Make Your First Request

1
import { HoleFoundationClient } from '@hole-foundation/api';
2
3
const client = new HoleFoundationClient({
4
  environment: 'https://api.theholefoundation.org',
5
  token: process.env.AUTH0_TOKEN
6
});
7
8
const jurisdictions = await client.transparency.listJurisdictions();
9
console.log(`Found ${jurisdictions.length} jurisdictions`);

API Categories

Health

System health checks and status monitoring.

Endpoints:

• GET /api/health - Check API status

Vector Search

Hybrid semantic + keyword search for legal documents.

Endpoints:

• POST /api/v1/search - Search documents
• GET /api/v1/documents/{id} - Get document details

Transparency

Access to US transparency and public records laws.

Endpoints:

• GET /api/v2/transparency/jurisdictions - List jurisdictions
• GET /api/v2/transparency/rights - Search rights of access
• GET /api/v2/transparency/exemptions - Search exemptions
• GET /api/v2/transparency/statutes - Get statute text

FOIA Dashboard

Manage FOIA requests (requires authentication).

Endpoints:

• POST /api/foia/requests - Create request
• GET /api/foia/requests - List your requests
• GET /api/foia/requests/{id} - Get request details
• PATCH /api/foia/requests/{id} - Update request

Chat

AI-powered legal research assistant.

Endpoints:

• POST /api/chat - Send message (supports streaming)

Authentication

All authenticated endpoints require an Auth0 JWT Bearer token:

$
curl -X GET "https://api.theholefoundation.org/api/foia/requests" \
>
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

See the Authentication Guide for details on obtaining tokens.

Rate Limits

Support

Need help? We’re here:

• 📧 Email: api@theholefoundation.org
• 💬 Discord: Join our community
• 🐛 Issues: GitHub Issues

Next Steps

• Authentication Guide - Learn how to authenticate
• Quick Start Tutorial - Build your first integration
• API Reference - Complete API documentation
• SDK Documentation - Language-specific guides