Resources

Changelog

All notable changes to the HOLE Foundation API will be documented here.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[2.0.0] - 2024-01-15

Added

  • OpenAPI 3.1.0 Specification: Complete API specification with all endpoints documented
  • TypeScript SDK: Auto-generated SDK with full type safety
  • Python SDK: Auto-generated SDK with async support
  • Fern Documentation: Interactive API documentation at theholetruth.org/docs
  • Chat API: AI-powered legal research assistant using Claude AI
  • Streaming Support: Server-Sent Events (SSE) for real-time chat responses
  • Rate Limiting: Tiered rate limits with automatic tracking
  • Conversation Memory: Multi-turn chat conversations with context preservation
  • Enhanced Error Responses: Structured error format with request IDs and detailed messages

Changed

  • Breaking: Authentication now requires JWT Bearer tokens (was API keys)
  • Breaking: All endpoints now return structured JSON responses
  • Breaking: Error responses use new standardized format
  • Vector Search: Improved relevance scoring algorithm
  • Transparency API: Updated to include 2024 statute amendments
  • FOIA Dashboard: Enhanced tracking with automatic deadline calculations

Deprecated

  • API key authentication (will be removed in v3.0.0)
  • Legacy error format (still supported until v3.0.0)

Fixed

  • Vector Search: Fixed incorrect scoring for multi-word queries
  • Transparency API: Corrected jurisdiction codes for territories
  • FOIA Dashboard: Fixed timezone issues in deadline calculations

Security

  • Implemented Auth0 JWT validation with JWKS verification
  • Added rate limiting to prevent abuse
  • Enhanced input validation on all endpoints

[1.2.0] - 2023-12-01

Added

  • FOIA Dashboard: Document attachment support
  • Transparency API: Case law citations
  • Vector Search: Filter by date range
  • New endpoint: /api/transparency/jurisdictions/{id}/statutes

Changed

  • Improved search relevance for legal citations
  • Enhanced metadata in transparency records
  • Optimized database queries for better performance

Fixed

  • Vector Search: Fixed pagination offset calculation
  • FOIA Dashboard: Fixed status transition validation
  • Transparency API: Corrected exemption categorization

[1.1.0] - 2023-10-15

Added

  • FOIA Dashboard: Request status tracking
  • Transparency API: Exemption search
  • Vector Search: Hybrid search (vector + keyword)
  • Support for custom domain documentation

Changed

  • Increased default search limit from 10 to 25
  • Improved error messages for validation failures
  • Updated database schema for better performance

Fixed

  • Fixed memory leak in vector search
  • Corrected jurisdiction abbreviations
  • Fixed date formatting in API responses

[1.0.0] - 2023-08-01

Added

  • Initial public release
  • Health check endpoint
  • Vector Search API (basic)
  • Transparency Laws API
    • Jurisdictions endpoint
    • Rights of access endpoint
    • Exemptions endpoint
    • Statutes endpoint
  • FOIA Dashboard API (basic)
    • Create requests
    • List requests
    • Get request details
  • Authentication via API keys
  • Basic rate limiting (100 req/day)

Known Issues

  • Vector search relevance needs improvement
  • Limited error details
  • No streaming support

[0.9.0] - 2023-06-15 (Beta)

Added

  • Beta release for testing
  • Core vector search functionality
  • Basic transparency data endpoints
  • Preliminary documentation

Known Issues

  • API subject to breaking changes
  • Limited test coverage
  • Documentation incomplete

Upcoming Changes

Version 2.1.0 (Q1 2024)

  • Advanced analytics for FOIA requests
  • Bulk operations for transparency data
  • Webhook support for request updates
  • GraphQL API endpoint
  • Enhanced search filters

Version 2.2.0 (Q2 2024)

  • Real-time collaboration features
  • Custom report generation
  • Advanced AI analysis tools
  • Mobile SDK (iOS/Android)

Version 3.0.0 (Q3 2024)

  • Remove deprecated API key authentication
  • Remove legacy error format
  • Breaking: New search relevance algorithm
  • Breaking: Updated response structures

Migration Guides

Migrating from v1.x to v2.0

Authentication

Before (v1.x):

1const client = new HoleFoundationClient({
2  apiKey: 'sk_live_...'
3});

After (v2.0):

1const client = new HoleFoundationClient({
2  token: 'eyJhbGciOiJSUzI1NiIs...'  // JWT from Auth0
3});

Error Handling

Before (v1.x):

1{
2  "error": "Invalid query"
3}

After (v2.0):

1{
2  "error": {
3    "code": "VALIDATION_REQUIRED_FIELD",
4    "message": "The 'query' field is required",
5    "status": 400,
6    "request_id": "req_123"
7  }
8}

Search Response

Before (v1.x):

1{
2  "results": [...]
3}

After (v2.0):

1{
2  "results": [...],
3  "total": 150,
4  "query": "FOIA exemptions",
5  "took_ms": 45
6}

See Migration Guide for complete details.

Deprecation Policy

Features marked as deprecated will:

  1. Be noted in changelog when deprecated
  2. Continue working for at least 6 months
  3. Show deprecation warnings in responses
  4. Be removed in next major version

API Versioning

Version Format

We use semantic versioning (MAJOR.MINOR.PATCH):

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes (backward compatible)

Breaking Changes

Breaking changes are only introduced in major versions and include:

  • Removing endpoints
  • Changing request/response formats
  • Modifying authentication methods
  • Altering default behavior

Backward Compatibility

Minor and patch versions maintain backward compatibility:

  • New optional parameters
  • Additional response fields
  • New endpoints
  • Bug fixes

Release Schedule

  • Major versions: Annually (Q3)
  • Minor versions: Quarterly
  • Patch versions: As needed (typically bi-weekly)
  • Security patches: Immediately

Beta Features

Features marked as “Beta” are:

  • Fully functional but subject to change
  • Available for testing and feedback
  • May have breaking changes without major version bump
  • Documented with “Beta” label

Current beta features:

  • None (v2.0.0 is stable)

Sunset Policy

When we sunset an API version:

  1. 12 months notice via email and docs
  2. Deprecation warnings in all responses
  3. Migration guide published
  4. Support period of 6 months after deprecation
  5. Final sunset with redirect to latest version

Stay Updated

Subscribe to API updates:

Providing Feedback

Help shape the API:

Historical Versions

Documentation for previous versions:

Current Version: 2.0.0 Released: January 15, 2024 Status: Stable Next Release: v2.1.0 (March 2024)