File Journal & Audit Log

The file journal records every mutation performed against a workspace’s files. Use these endpoints to query the audit log with cursor-based pagination, inspect storage health and pruning state, and force pending writes to be flushed and fsynced to disk.

Query journal entries

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)

Response

200

{
  "count": 3,
  "has_more": true,
  "next_after_id": 100042,
  "entries": [
    {
      "id": 100040,
      "ts": 1719840000000,
      "op": "write",
      "path": "docs/report.md",
      "seq": 42,
      "size_before": 4096,
      "size_after": 8192,
      "before": "5d41402abc4b2a76b9719d911017c592",
      "after": "e3b0c44298fc1c1f3a2bd49ad9b6e3ab",
      "blob": true,
      "blob_before": true,
      "blob_after": true
    },
    {
      "id": 100041,
      "ts": 1719840060000,
      "op": "delete",
      "path": "tmp/scratch.txt"
    },
    {
      "id": 100042,
      "ts": 1719840120000,
      "op": "chmod",
      "path": "scripts/deploy.sh",
      "old_mode": "0644",
      "new_mode": "0755"
    }
  ]
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Journal not enabled"
}

429

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many concurrent journal queries"
}

Example

cURL

curl -X GET "https://api.hoody.com/api/v1/journal?path=docs/&op=write,delete&limit=50&after_id=100000" \
  -H "Authorization: Bearer <token>"

TypeScript

const page = await client.files.journal.query({
  path: "docs/",
  op: "write,delete",
  since: "2024-06-01T00:00:00Z",
  limit: 50,
  after_id: 100000,
});

console.log(page.count, page.has_more, page.next_after_id);

Get journal statistics

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.

Response

200

{
  "total_entries": 1247,
  "total_blobs": 892,
  "total_blob_bytes": 5242880,
  "total_storage_bytes": 6291456,
  "writer_healthy": true,
  "entries_skipped_total": 0,
  "parse_failures": 0,
  "skipped_overflow": 0,
  "newest_entry_ts": 1719840000000,
  "pruned_before_date": "2024-06-01"
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Journal not enabled"
}

429

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many concurrent journal queries"
}

Note

A non-zero skipped_overflow value indicates that the path tracking cap was exceeded for some paths, which degrades completeness detection in the audit log. A non-healthy writer_healthy flag means the background JSONL writer task is not running and journal durability cannot be guaranteed.

Example

cURL

curl -X GET "https://api.hoody.com/api/v1/journal/stats" \
  -H "Authorization: Bearer <token>"

TypeScript

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

if (!stats.writer_healthy || stats.skipped_overflow > 0) {
  console.warn("Journal health degraded", stats);
}

Flush journal to disk

POST /api/v1/journal/flush

Forces all pending journal entries to be written and fsynced to disk. Returns 200 with 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.

Response

200

{
  "flushed": true
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Journal not enabled"
}

503

{
  "flushed": false
}

Caution

A 503 response indicates that the flush did not complete durably or that entries have been lost. Treat this as a data-integrity event and reconcile your local audit state before proceeding with operations that depend on the journal.

Example

cURL

curl -X POST "https://api.hoody.com/api/v1/journal/flush" \
  -H "Authorization: Bearer <token>"

TypeScript

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

if (!result.flushed) {
  throw new Error("Journal flush failed; entries may have been lost");
}