UnforgedFolio DevelopersSafetySecurityPricing
Get started
Get started
Contents

Folders

Folders in the shape your team already works in.

The FolioFolder object

Attributes

  • path required Type: string
  • matter required Type: string null
  • subject required Type: string null
  • protected required Type: boolean
  • created_at_ms required Type: integer

FolioFolder on its own page

Protect a folder

POST /folio/folders/protect

Needs folio:settings:manage: Retention classes, reason settings, protected folders, webhooks

Views of records in the folder and every folder below it need a reason even when the organisation's view-reason setting is off. A change, so a reason is required; ledgered.

Parameters

  • Idempotency-Key headerrequired Type: string

    1–255 printable ASCII characters, kept 24 hours.

Request body

FolioFolderRequest

  • folder required Type: string
  • code required Type: string
  • text optional Type: string null

Returns

  • 200 Type: FolioFolderProtected
    Protected
  • 400 Type: Problem
    invalid_request, invalid_version, idempotency_key_required or invalid_signature
  • 401 Type: Problem
    unauthorized
  • 403 Type: Problem
    permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
  • 404 Type: Problem
    not_found
  • 409 Type: Problem
    conflict, idempotency_conflict, idempotency_in_progress or idempotency_not_replayable
  • 413 Type: Problem
    too_large
  • 421 Type: Problem
    wrong_region
  • 429 Type: Problem
    rate_limited or quota_exceeded
  • default Type: Problem
    internal
POST /folio/folders/protect · curl 
curl -X POST "https://api.unforged.sh/folio/folders/protect" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14" \
  -H "Content-Type: application/json" \
  -d '{}'
POST /folio/folders/protect · Python 
import requests

r = requests.post(
    "https://api.unforged.sh/folio/folders/protect",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
    json={},
)
print(r.json())
POST /folio/folders/protect · Node.js 
const res = await fetch('https://api.unforged.sh/folio/folders/protect', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14', 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
});
console.log(await res.json());

Ask to remove a folder's protection

POST /folio/folders/unprotect

Needs folio:settings:manage: Retention classes, reason settings, protected folders, webhooks

Nothing changes until a different person approves (POST /folio/approvals/{id}/approve, which then also needs folio:settings:manage). 409 when the folder is not protected, or a folder above it is (a sub-folder cannot opt out of its parent's protection).

Parameters

  • Idempotency-Key headerrequired Type: string

    1–255 printable ASCII characters, kept 24 hours.

Request body

FolioFolderRequest

  • folder required Type: string
  • code required Type: string
  • text optional Type: string null

Returns

  • 201 Type: FolioApproval
    The approval request
  • 400 Type: Problem
    invalid_request, invalid_version, idempotency_key_required or invalid_signature
  • 401 Type: Problem
    unauthorized
  • 403 Type: Problem
    permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
  • 404 Type: Problem
    not_found
  • 409 Type: Problem
    conflict, idempotency_conflict, idempotency_in_progress or idempotency_not_replayable
  • 413 Type: Problem
    too_large
  • 421 Type: Problem
    wrong_region
  • 429 Type: Problem
    rate_limited or quota_exceeded
  • default Type: Problem
    internal
POST /folio/folders/unprotect · curl 
curl -X POST "https://api.unforged.sh/folio/folders/unprotect" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14" \
  -H "Content-Type: application/json" \
  -d '{}'
POST /folio/folders/unprotect · Python 
import requests

r = requests.post(
    "https://api.unforged.sh/folio/folders/unprotect",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
    json={},
)
print(r.json())
POST /folio/folders/unprotect · Node.js 
const res = await fetch('https://api.unforged.sh/folio/folders/unprotect', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14', 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
});
console.log(await res.json());

Rename a folder

POST /folio/folders/rename

Needs folio:records:write: File records, create folders, extend retention

Renames the last segment of path. Everything in the folder and below it keeps its place, and its path changes with it. A change, so a reason with details is required; every document gets its own ledger entry. 409 with a sentence when the folder holds a hold, an open reason, a regulator grant, a waiting approval, queued or open work, a document still being filed, more than 2,000 documents, or when the new name already exists. A protected folder returns 202 with an approval (rename_folder) that a different person decides, which then also needs folio:settings:manage.

Parameters

  • Idempotency-Key headerrequired Type: string

    1–255 printable ASCII characters, kept 24 hours.

Request body

FolioFolderRename

  • path required Type: string

    The folder to rename.

  • name required Type: string

    Its new last segment

  • code required Type: string

    The reason code.

  • text optional Type: string null

    The reason's details (at least 10 characters).

Returns

  • 200 Type: FolioFolderRenamed
    The rename
  • 202 Type: FolioApproval
    The approval request; nothing has changed yet
  • 400 Type: Problem
    invalid_request, invalid_version, idempotency_key_required or invalid_signature
  • 401 Type: Problem
    unauthorized
  • 403 Type: Problem
    permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
  • 404 Type: Problem
    not_found
  • 409 Type: Problem
    conflict, idempotency_conflict, idempotency_in_progress or idempotency_not_replayable
  • 413 Type: Problem
    too_large
  • 421 Type: Problem
    wrong_region
  • 429 Type: Problem
    rate_limited or quota_exceeded
  • default Type: Problem
    internal
POST /folio/folders/rename · curl 
curl -X POST "https://api.unforged.sh/folio/folders/rename" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14" \
  -H "Content-Type: application/json" \
  -d '{}'
POST /folio/folders/rename · Python 
import requests

r = requests.post(
    "https://api.unforged.sh/folio/folders/rename",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
    json={},
)
print(r.json())
POST /folio/folders/rename · Node.js 
const res = await fetch('https://api.unforged.sh/folio/folders/rename', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14', 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
});
console.log(await res.json());

List folders

GET /folio/folders

Needs folio:records:read: See filed records, folders and metadata

The folders directly below parent (the top level when omitted), by path.

Parameters

  • parent queryoptional Type: string
  • after queryoptional Type: string

    The previous page's next_after.

  • limit queryoptional Type: integer

Returns

  • 200 Type: FolioFolderPage
    A page of folders
  • 400 Type: Problem
    invalid_request, invalid_version, idempotency_key_required or invalid_signature
  • 401 Type: Problem
    unauthorized
  • 403 Type: Problem
    permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
  • 404 Type: Problem
    not_found
  • 421 Type: Problem
    wrong_region
  • 429 Type: Problem
    rate_limited or quota_exceeded
  • default Type: Problem
    internal
GET /folio/folders · curl 
curl "https://api.unforged.sh/folio/folders" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14"
GET /folio/folders · Python 
import requests

r = requests.get(
    "https://api.unforged.sh/folio/folders",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
)
print(r.json())
GET /folio/folders · Node.js 
const res = await fetch('https://api.unforged.sh/folio/folders', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14' },
});
console.log(await res.json());
Response 200 
{
  "folders": [
    {
      "path": "clients",
      "matter": null,
      "subject": null,
      "protected": false,
      "created_at_ms": 1790000000000
    }
  ],
  "next_after": null
}

Create a folder

POST /folio/folders

Needs folio:records:write: File records, create folders, extend retention

Creates the folder and any missing ancestors. Its matter and subject are inherited by what is filed into it. No reason is needed; ledgered as folder.created. 409 if it exists.

Parameters

  • Idempotency-Key headerrequired Type: string

    1–255 printable ASCII characters, kept 24 hours.

Request body

FolioFolderCreate

  • path required Type: string
  • matter optional Type: string
  • subject optional Type: string

Returns

  • 201 Type: FolioFolder
    Created
  • 400 Type: Problem
    invalid_request, invalid_version, idempotency_key_required or invalid_signature
  • 401 Type: Problem
    unauthorized
  • 403 Type: Problem
    permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
  • 404 Type: Problem
    not_found
  • 409 Type: Problem
    conflict, idempotency_conflict, idempotency_in_progress or idempotency_not_replayable
  • 421 Type: Problem
    wrong_region
  • 429 Type: Problem
    rate_limited or quota_exceeded
  • default Type: Problem
    internal
POST /folio/folders · curl 
curl -X POST "https://api.unforged.sh/folio/folders" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14" \
  -H "Content-Type: application/json" \
  -d '{
  "path": "clients/smith",
  "matter": "M-1042"
}'
POST /folio/folders · Python 
import requests

r = requests.post(
    "https://api.unforged.sh/folio/folders",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
    json={
        "path": "clients/smith",
        "matter": "M-1042"
    },
)
print(r.json())
POST /folio/folders · Node.js 
const res = await fetch('https://api.unforged.sh/folio/folders', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "path": "clients/smith",
    "matter": "M-1042"
  }),
});
console.log(await res.json());

A folder

GET /folio/folders/detail

Needs folio:records:read: See filed records, folders and metadata

One folder, with the number of filed records and folders directly in it.

Parameters

  • path queryrequired Type: string

Returns

  • 200 Type: FolioFolderDetail
    The folder
  • 400 Type: Problem
    invalid_request, invalid_version, idempotency_key_required or invalid_signature
  • 401 Type: Problem
    unauthorized
  • 403 Type: Problem
    permission_denied, org_suspended, or address_not_allowed (your organisation only accepts requests from the addresses it has listed)
  • 404 Type: Problem
    not_found
  • 421 Type: Problem
    wrong_region
  • 429 Type: Problem
    rate_limited or quota_exceeded
  • default Type: Problem
    internal
GET /folio/folders/detail · curl 
curl "https://api.unforged.sh/folio/folders/detail?path=<path>" \
  -H "Authorization: Bearer $UNFORGED_KEY" \
  -H "Unforged-Version: 2026-10-14"
GET /folio/folders/detail · Python 
import requests

r = requests.get(
    "https://api.unforged.sh/folio/folders/detail?path=<path>",
    headers={"Authorization": f"Bearer {UNFORGED_KEY}", "Unforged-Version": "2026-10-14"},
)
print(r.json())
GET /folio/folders/detail · Node.js 
const res = await fetch('https://api.unforged.sh/folio/folders/detail?path=<path>', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.UNFORGED_KEY}`, 'Unforged-Version': '2026-10-14' },
});
console.log(await res.json());