API Reference

The LogVault API is built on REST principles. We enforce HTTPS in production and use standard HTTP response codes.

Base URL

Bash

1https://api.logvault.eu/v1

Authentication

Pass your API key in the x-api-key header or as Authorization: Bearer. Get your API key from the Dashboard → Settings → API Keys.

Bash

1curl https://api.logvault.eu/v1/events \
2  -H "Content-Type: application/json" \
3  -H "x-api-key: lv_live_YOUR_API_KEY" \
4  -d '{
5    "action": "user.login",
6    "user_id": "u_123",
7    "resource": "dashboard"
8  }'

Rate Limiting

API requests are rate-limited per organization. Standard tiers:

Free

100 requests/minute

Starter

1,000 requests/minute

Growth

10,000 requests/minute

Enterprise

Custom limits

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error Handling

All errors follow RFC 7807 format:

JSON

1{
2  "type": "about:blank",
3  "title": "Validation Error",
4  "status": 422,
5  "detail": "One or more fields failed validation",
6  "instance": "/v1/events",
7  "request_id": "550e8400-e29b-41d4-a716-446655440000",
8  "errors": [
9    {
10      "field": "body.user_id",
11      "message": "field required",
12      "code": "value_error.missing"
13    }
14  ]
15}

Common status codes: 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 422 (Validation Error), 429 (Rate Limited), 500 (Server Error).

Health Endpoints

Use these endpoints to monitor API availability and dependency status.

GET/health

Basic liveness check. Returns 200 if the API is running. No authentication required.

JSON

1{
2  "status": "healthy",
3  "service": "logvault-api",
4  "version": "3490905",
5  "environment": "production",
6  "uptime_seconds": 3600,
7  "timestamp": "2025-11-30T12:00:00Z"
8}

GET/health/ready

Readiness probe. Returns 200 only if the database is healthy. Returns 503 if not ready.

GET/health/deep

Deep health check with dependency status (Supabase, Redis).

JSON

1{
2  "status": "healthy",
3  "service": "logvault-api",
4  "checks": {
5    "supabase": { "status": "healthy", "latency_ms": 12.5 },
6    "redis": { "status": "healthy", "latency_ms": 2.1 }
7  }
8}

Events

POST/v1/events

Ingest a new audit event. Events are cryptographically signed, hash-chained, and immutable.

Request

JSON

1{
2  "action": "user.created",
3  "user_id": "u_123",
4  "resource": "team_A",
5  "metadata": {
6    "ip": "1.2.3.4",
7    "user_agent": "Mozilla/5.0..."
8  }
9}

Response (201 Created)

JSON

1{
2  "id": "550e8400-e29b-41d4-a716-446655440000",
3  "action": "user.created",
4  "user_id": "u_123",
5  "resource": "team_A",
6  "timestamp": "2025-11-30T10:30:00Z",
7  "signature": "hmac_sha256_abc123...",
8  "chain_hash": "sha256_def456...",
9  "prev_hash": "sha256_ghi789..."
10}

GET/v1/events

Retrieve a paginated list of events. Supports filtering by user_id, action, resource, and date range.

Query Parameters

Bash

1?page=1
2&page_size=50
3&user_id=u_123
4&action=user.login
5&start_date=2025-01-01
6&end_date=2025-01-31

Response (200 OK)

JSON

1{
2  "events": [...],
3  "total": 150,
4  "page": 1,
5  "page_size": 50,
6  "has_next": true
7}

GET/v1/events/search

Hybrid search using full-text + semantic search. Supports natural language queries.

Bash

1GET /v1/events/search?q=failed+login+attempts&page=1&page_size=50

GET/v1/events/export

Export events as CSV. Supports filtering by date range, user_id, and action.

Bash

1GET /v1/events/export?start_date=2025-01-01&end_date=2025-01-31

Returns: Content-Type: text/csv

GET/v1/events/{event_id}/verify

Verify the cryptographic signature of an event.

JSON

1{
2  "event_id": "550e8400-e29b-41d4-a716-446655440000",
3  "valid": true,
4  "signature": "hmac_sha256_abc123...",
5  "expected_signature": "hmac_sha256_abc123...",
6  "tampered": false,
7  "verified_at": "2025-11-30T10:30:00Z"
8}

GET/v1/events/{event_id}/proof

Get cryptographic proof for an event including chain context.

JSON

1{
2  "event": { ... },
3  "proof": {
4    "signature": "hmac_sha256_abc123...",
5    "chain_hash": "sha256_def456...",
6    "prev_hash": "sha256_ghi789...",
7    "chain_position": 42
8  },
9  "previous_event": { ... },
10  "next_event": { ... },
11  "verification_instructions": "..."
12}

Chain Integrity

Verify the cryptographic hash chain that links all audit events.

GET/v1/chain/verify

Verify the entire audit log chain integrity.

Query Parameters

Bash

1?start_date=2025-01-01
2&end_date=2025-01-31
3&limit=1000

Response (200 OK)

JSON

1{
2  "is_valid": true,
3  "events_checked": 1523,
4  "first_event_id": "...",
5  "last_event_id": "...",
6  "verified_at": "2025-11-30T10:30:00Z"
7}

GET/v1/chain/stats

Get statistics about the hash chain.

JSON

1{
2  "total_events": 1523,
3  "chained_events": 1520,
4  "legacy_events": 3,
5  "chain_coverage_percent": 99.8,
6  "first_chained_event": { ... },
7  "last_chained_event": { ... }
8}

API Keys

POST/v1/keys/rotate

Rotate an API key with optional grace period for zero-downtime rotation.

Request

JSON

1{
2  "key_id": "key_abc123",
3  "grace_hours": 24
4}

Response (200 OK)

JSON

1{
2  "new_key_id": "key_def456",
3  "new_api_key": "lv_live_...",
4  "old_key_expires_at": "2025-12-01T10:30:00Z",
5  "message": "Save your new API key now!"
6}

Organizations

POST/v1/organizations

Create a new organization. Returns an API key for immediate use.

Request

JSON

1{
2  "name": "Acme Corp",
3  "email": "admin@acme.com",
4  "tier": "starter"
5}

Response (201 Created)

JSON

1{
2  "success": true,
3  "organization": {
4    "org_id": "550e8400-...",
5    "name": "Acme Corp",
6    "tier": "starter",
7    "monthly_limit": 100000,
8    "retention_days": 365
9  },
10  "api_key": "lv_live_...",
11  "message": "⚠️ Save your API key now!"
12}

Full OpenAPI Specification

For a complete, interactive specification of all endpoints, visit our Swagger UI.

Open Swagger UI↗