upenn/littleforest-leaf-skill/littleforest-leaf

LittleForest Leaf API

Use the bundled client for authenticated calls. It obtains the API key from LEAF_API_KEY or the macOS Keychain and never prints the credential.

python3 <skill-dir>/scripts/leaf_api.py auth
python3 <skill-dir>/scripts/leaf_api.py accounts
python3 <skill-dir>/scripts/leaf_api.py search sites --search example --limit 25
python3 <skill-dir>/scripts/leaf_api.py request GET '/api/accounts/{accountId}/tags'

Per-user setup

Keep installation-specific values outside the skill directory so the folder can be packaged and shared unchanged.

On macOS, store the user's API key in Keychain with an interactive prompt:

security add-generic-password -U -a littleforest-leaf-api -s codex-littleforest-leaf-api-key -w

On other platforms, provide LEAF_API_KEY through the user's environment or secret manager. Then save the non-secret account UUID in the user's external config:

python3 <skill-dir>/scripts/leaf_api.py config set-account ACCOUNT_UUID

The default config path is ~/.config/littleforest-leaf/config.json. Neither the Keychain item nor this config file belongs in a shared skill archive.

Account selection

Account-specific routes contain {accountId}. Resolve it in this order:

1. --account-id on the current command.
2. LEAF_ACCOUNT_ID.
3. The locally saved default from config set-account.
4. GET /api/accounts/ when it returns exactly one account.

Registry API keys may authenticate successfully while GET /api/accounts/ returns zero accounts. If no account ID is available, ask the user once for the Leaf account UUID, then save it:

python3 <skill-dir>/scripts/leaf_api.py config set-account ACCOUNT_UUID

An account UUID is not a credential. Do not put the API key in skill files, prompts, command arguments, generated reports, or logs.

Workflow

1. Read references/api.md for endpoint routing and request shapes. For an unfamiliar or newly added endpoint, consult the live Leaf API documentation before calling it.
2. Begin with the narrowest read that identifies exact records and IDs. Prefer server-side filters and urls_list over downloading a large registry and filtering locally.
3. For a mutation, inspect the current records first when practical. Run the client command without --execute to show a credential-free dry run, then add --execute only when the user requested that change.
4. Use --allow-destructive only for an explicitly requested permanent deletion. Prefer a recoverable URL archive with {"permanent": false} over hard deletion.
5. Verify the response. For partial-result responses, report updated, skipped, not-found, and failed counts rather than calling the whole operation successful.

Do not reinterpret POST as a write automatically: Leaf uses POST for searches and reports with filter bodies. The client recognizes documented read-only POST routes. Other POST, PUT, PATCH, and DELETE requests remain dry runs unless --execute is supplied.

Registry conventions

• Sites are subdomain/host records. For site_host, send a hostname only: no protocol, path, or trailing slash.
• Pages and PDFs use full URLs.
• TLD search primarily filters and sorts by name, not url.
• Search pages/sites first when a later action needs asset IDs, such as tag assignment.
• List data points before updating values so the name and value shape match the configured type. Dropdown values are arrays; object data points use key-value objects.
• Use enriched search only when report rollups are needed. It is more expensive than ordinary search.
• For large exports and bulk updates, poll the returned job until a terminal state. API-key jobs do not send completion email.

Client notes

Pass JSON inline with --data, from a file with --data-file, or from stdin with --data-file -. Use --output for HTML, ZIP, CSV, or other file responses.

request retries only read operations on transient 429/502/503/504 responses. It never retries a mutation automatically because the API does not document idempotency guarantees for registry writes.