File Journal & Audit Log

The file journal records every mutation performed on files inside a container, capturing creates, writes, deletes, moves, copies, chmod/chown changes, and directory operations. Use these endpoints to audit changes, flush pending entries durably to disk, and monitor journal health and storage usage.

All endpoints in this page are scoped to a single container. The base URL embeds the project ID, container ID, and server region.

Query journal entries

GET /api/v1/journal

Returns a paginated list of journal entries. Supports filtering by path prefix, operation type, time range, and cursor-based pagination using 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://proj-acme-cnt-workspace01-files-1.eu-west-1.containers.hoody.icu/api/v1/journal?path=%2Fsrc%2Fapi&op=write%2Cdelete&since=2025-01-15T00%3A00%3A00Z&limit=50&after_id=12480" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from "hoody-sdk";

const client = new HoodyClient({ token: process.env.HOODY_TOKEN });

const page = await client.files.journal.query({
  path: "/src/api",
  op: "write,delete",
  since: "2025-01-15T00:00:00Z",
  limit: 50,
  after_id: 12480
});

{
  "count": 2,
  "has_more": true,
  "next_after_id": 12531,
  "entries": [
    {
      "id": 12481,
      "ts": 1736899200000,
      "op": "write",
      "path": "/src/api/handlers.ts",
      "before": "9b2c5e1a7d8f4b3c6a0e5d2f8a1c4b7e9d3f6a2c5e8b1d4f7a0c3e6b9d2f5a8c",
      "after": "3f7a8c2d1e9b4c5a6f0d3e8b1c2a4f5d7e9c0b3a6f8d1e4c7b2a5f8d3c6e9b0a",
      "size_before": 4210,
      "size_after": 4387,
      "blob_before": true,
      "blob_after": true,
      "blob": true,
      "seq": 17,
      "source": null,
      "dest": null,
      "hash": null,
      "old_mode": null,
      "new_mode": null,
      "old_owner": null,
      "new_owner": null,
      "old_group": null,
      "new_group": null,
      "reason": null
    },
    {
      "id": 12490,
      "ts": 1736899260000,
      "op": "delete",
      "path": "/src/api/legacy.ts",
      "before": "5a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b",
      "after": null,
      "size_before": 1820,
      "size_after": null,
      "blob_before": true,
      "blob_after": false,
      "blob": true,
      "seq": 4,
      "source": null,
      "dest": null,
      "hash": null,
      "old_mode": null,
      "new_mode": null,
      "old_owner": null,
      "new_owner": null,
      "old_group": null,
      "new_group": null,
      "reason": null
    }
  ]
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Journal is not enabled for this container"
}

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many concurrent journal queries; retry after a short delay"
}

Operation types

The op field of each entry is one of the following values:

create, write, append, delete, touch, moved_from, moved_to, copied_from, copied_to, dir_moved_from, dir_moved_to, dir_copied_from, dir_copied_to, dir_deleted, mkdir, chmod, chown, gap

Get journal statistics

GET /api/v1/journal/stats

Returns storage statistics for the journal system, including total entries, blob storage usage, writer health, parse failure counts, and pruning information.

curl -X GET "https://proj-acme-cnt-workspace01-files-1.eu-west-1.containers.hoody.icu/api/v1/journal/stats" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from "hoody-sdk";

const client = new HoodyClient({ token: process.env.HOODY_TOKEN });

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

{
  "total_entries": 15842,
  "total_blobs": 9421,
  "total_blob_bytes": 134217728,
  "total_storage_bytes": 142606336,
  "writer_healthy": true,
  "entries_skipped_total": 0,
  "parse_failures": 0,
  "skipped_overflow": 0,
  "newest_entry_ts": 1736899320000,
  "pruned_before_date": "2024-12-01"
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Journal is not enabled for this container"
}

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Too many concurrent journal queries; retry after a short delay"
}

Response fields

total_entries — Total number of journal entries across all day files.
total_blobs — Total number of content blobs stored.
total_blob_bytes — Total bytes used by content blobs.
total_storage_bytes — Total bytes used by journal (entries + blobs).
writer_healthy — Whether the background JSONL writer task is healthy.
entries_skipped_total — Number of paths with entries that were dropped (writer outage).
parse_failures — Count of corrupted/malformed JSONL lines encountered during scans.
skipped_overflow — Count of dropped paths that exceeded the tracking cap. Non-zero means completeness detection is degraded.
newest_entry_ts — Timestamp (Unix ms) of the most recent entry, or null if no entries.
pruned_before_date — ISO date (YYYY-MM-DD) before which all day files have been pruned, or null if no pruning.

Flush journal to disk

POST /api/v1/journal/flush

Forces all pending journal entries to be written and fsync’d to disk. Returns 200 with flushed=true when all entries were durably persisted, or 503 with flushed=false when the flush failed or entries were lost.

curl -X POST "https://proj-acme-cnt-workspace01-files-1.eu-west-1.containers.hoody.icu/api/v1/journal/flush" \
  -H "Authorization: Bearer <token>"

import { HoodyClient } from "hoody-sdk";

const client = new HoodyClient({ token: process.env.HOODY_TOKEN });

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

{
  "flushed": true
}

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Journal is not enabled for this container"
}

{
  "flushed": false
}