API Reference

Complete REST API documentation for recording events, uploading evidence, and verifying integrity.

Base URL

https://api.tryengrave.com

Authentication

All API requests require authentication via the X-API-Key header.

X-API-Key: ek_live_your_api_key_here

Events

POST /api/v1/events

Record a new audit event.

Request Body

{
  "event_type": "string",         // Required. Your custom event type
  "event_timestamp": "ISO8601",  // Optional. When the event occurred
  "metadata": { },              // Optional. Flexible JSON metadata
  "user_key": "string"          // Optional. Your unique lookup key
}

Response

{
  "id": "guid",
  "event_type": "string",
  "event_timestamp": "ISO8601",
  "recorded_at": "ISO8601",
  "tx_id": 12345,
  "verification_url": "/api/v1/events/{id}/verify"
}

GET /api/v1/events

List and search events.

Query Parameters

page - Page number (default: 1)
pageSize - Items per page (default: 20, max: 100)
eventType - Filter by event type
from - Start date (ISO8601)
to - End date (ISO8601)
search - Search in metadata

GET /api/v1/events/{'{id}'}

Get details of a specific event by ID.

GET /api/v1/events/{'{id}'}/verify

Verify the cryptographic integrity of an event.

Response

{
  "event_id": "guid",
  "verified": true,
  "tx_id": 12345,
  "verified_at": "ISO8601",
  "message": "Event verified - data integrity confirmed"
}

Evidence

POST /api/v1/events/{'{eventId}'}/evidence

Upload evidence file to an event. Max file size: 500MB.

Request

Content-Type: multipart/form-data

file - The file to upload (required)
user_key - Optional unique lookup key

GET /api/v1/evidence/{'{id}'}

Get evidence metadata.

GET /api/v1/evidence/{'{id}'}/download

Download evidence file.

GET /api/v1/evidence/{'{id}'}/verify

Verify evidence integrity using SHA-256 hash comparison.

Rate Limiting

API requests are rate limited to 100 requests per minute per API key.

When rate limited, you'll receive a 429 Too Many Requests response with a Retry-After header indicating when to retry.