File Journal & Audit Log

Query file mutation events, inspect journal storage usage, and force a durable flush to disk. Use these endpoints to build audit trails, replicate changes to a remote system, or investigate when a specific file was modified.

Querying the Journal

`GET /api/v1/journal`

Query file mutation journal entries with optional filters. Supports cursor-based pagination via after_id.

Parameters

Name	In	Type	Required	Description
`path`	query	string	No	Filter entries by path prefix
`op`	query	string	No	Filter by operation type(s), comma-separated (e.g. `write,delete`)
`since`	query	string	No	Filter entries since timestamp (RFC3339 or Unix ms)
`limit`	query	integer	No	Max entries to return. Default: `100`
`after_id`	query	integer	No	Cursor: return entries with id > after_id. Default: `0`

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/journal?path=/var/log&op=write,delete&limit=50" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

const result = await client.files.journal.query({ path: '/var/log', op: 'write,delete', limit: 50 });

Response

Returned when entries matching the query were found.

{
  "count": 2,
  "entries": [
    {
      "id": 1042,
      "ts": 1717200000000,
      "op": "write",
      "path": "/var/log/app.log",
      "size_before": 1024,
      "size_after": 2048,
      "after": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "before": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "blob": true,
      "blob_after": true,
      "blob_before": true,
      "seq": 17
    },
    {
      "id": 1043,
      "ts": 1717200060000,
      "op": "delete",
      "path": "/tmp/oldfile.txt",
      "size_before": 512,
      "blob": true,
      "blob_after": false,
      "blob_before": true,
      "seq": 4
    }
  ],
  "has_more": true,
  "next_after_id": 1043
}

`GET /api/v1/journal/stats`

Returns storage statistics for the journal system including entry counts, blob storage usage, writer health, and pruning info.

This endpoint takes no parameters.

Request

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/journal/stats" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

const stats = await client.files.journal.getStats();

Response

Returned when storage statistics were retrieved successfully.

{
  "total_entries": 12500,
  "total_blobs": 8200,
  "total_blob_bytes": 524288000,
  "total_storage_bytes": 524338000,
  "writer_healthy": true,
  "entries_skipped_total": 0,
  "parse_failures": 0,
  "skipped_overflow": 0,
  "newest_entry_ts": 1717200060000,
  "pruned_before_date": "2024-05-01"
}

Flushing the Journal

`POST /api/v1/journal/flush`

Forces all pending journal entries to be written and fsynced to disk. Returns flushed=true if all entries were durably persisted, or 503 with flushed=false if flush failed or entries were lost.

This endpoint takes no parameters.

Request

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/journal/flush" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

const result = await client.files.journal.flush();

Response

Returned when pending entries were durably persisted to disk.

{
  "flushed": true
}

Returned when the flush operation failed or entries were lost. The response indicates that the flush was not durable.

{
  "flushed": false
}