API Reference

gnaw provides multiple interfaces for different use cases and integration scenarios.

Available Interfaces

Interface Comparison

| Interface | Use Case | Performance | Complexity | |-----------|----------|-------------|------------| | CLI | Interactive use, scripting | High | Low | | REST API | Web applications | Medium | Medium | | Webhooks | Real-time events | High | High |

Choosing the Right Interface

**Features:**
- Full gnaw functionality
- Direct file access
- Streaming output
- Rich formatting

**Features:**
- HTTP/HTTPS transport
- JSON responses
- Authentication support
- Rate limiting

**Features:**
- Push notifications
- Event filtering
- Retry mechanisms
- Security tokens

Common Patterns

Authentication

All interfaces support authentication:

# CLI: Environment variables
export GNAW_API_KEY="your-api-key"
gnaw "pattern" file.txt

# REST API: Header authentication
curl -H "Authorization: Bearer your-api-key" \
     -H "Content-Type: application/json" \
     -d '{"pattern": "ERROR", "path": "/var/log/app.log"}' \
     http://localhost:8080/api/search

# Webhooks: Token authentication
curl -X POST \
     -H "X-Webhook-Token: your-webhook-token" \
     -H "Content-Type: application/json" \
     -d '{"event": "error_detected", "data": {...}}' \
     http://localhost:8080/webhooks/error

Error Handling

All interfaces provide consistent error handling:

{
  "error": {
    "code": "INVALID_PATTERN",
    "message": "Invalid regular expression pattern",
    "details": "Unmatched opening bracket at position 5"
  }
}

Rate Limiting

Rate limiting is applied consistently across interfaces:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "retry_after": 60
  }
}

Next Steps

• Explore the CLI Reference
• Learn about the REST API
• Set up Webhooks