Skip to content
footnote Docs
Install

Administer the service

Change settings, read the history log, and move items in and out. Most of this is for admins, through the API under /api/v1 or the footnote command. For how to call the API, see the HTTP API overview.

Change a setting

GET /settings lists the current version of each limit, threshold, retention period, review time and model.

PUT /settings/{key} takes the version you read, the new value and a reason. A stale version answers 409, and a value the setting does not accept answers 422.

{
"version": 3,
"value": { "person": 600, "ip": 300 },
"reason": "A busy office behind one address"
}

A change applies at once, and the history log keeps it with who made it.

SettingWhat it limits
limits.api_rate_per_minuteRequests to the API, by person and by address
limits.mcp_requests_per_minuteAgent calls, by person and by client label
limits.mcp_rate_per_minuteAgent calls to each tool
limits.agent_draftsDrafts one person’s agents can save
limits.undo_secondsHow long a decision can be undone
privacy.min_countThe smallest count shown
retention.delivery_daysHow long what agents asked about is kept

Switch a tool off for every agent

POST /tools/{tool} takes { enabled, reason }. To do it for one agent, use its Details.

Set a policy for a client label

These have no screen in the web app. GET /clients lists the client labels, and PUT /clients/{label} adds or changes one:

FieldWhat it does
displayNameIts name
toolsAllowedIts tools. Null means every tool that is switched on
ratePerMinuteIts rate. Null means the default client rate
maxResponseBytesThe largest reply, 1,000 to 100,000
enabledWhether it may call at all
reasonWhy, for the history log

A label is never removed. Switch it off instead.

Create a domain

POST /areas creates one with an id that never changes, its name, hue, review time in working days (1 to 30), owners and a reason. It is served from the start.

Owners and admins change a domain’s summary and description with PUT /areas/{id}/description. Both operations need an Idempotency-Key.

To change who looks after a domain, use /assignments/grant and /assignments/revoke, which have no screen in the web app.

Read the history log

Admins can read it. Reading or exporting it is not itself logged.

OperationWhat it does
GET /auditSearches newest first, 50 at a time, by action, actorId, areaId, subjectType, subjectId, from and to
GET /audit/exportWrites JSON Lines, or CSV with format=csv, oldest first, up to 10,000 entries a call
GET /audit/verifyChecks the log’s hash chain

action takes a full name, such as setting.changed, or a prefix, such as proposal.

Import items

POST /imports takes a YAML or JSON item file, up to 5,000 items. Nothing is ever published by an import: an import makes suggestions for owners to review.

  • A dry run is the default, and changes nothing. Each entry gets the checks of the form.
  • An entry with an id suggests a change to that item, and an entry equal to what is live proposes nothing.
  • To apply, send Idempotency-Key. It makes suggestions only when no entry has an error and there are at most 500 to make.
  • submit: false keeps them as drafts.

The templates have an item file and a test question file to start from.

Export an edition

GET /editions/{label}/export gives the edition as one document, for owners and admins: every served item with its digest, the vocabulary, the domains, and the digest it was sealed with.

An item the reader may not see is listed by id and digest only, so the edition’s digest still checks. footnote verify recomputes every digest offline. An export reads back as an import.

Read the item format

GET /schema/item publishes the JSON Schema of the item format. It needs no sign-in.

The footnote command

footnote talks to the service and signs in as a person from the dev people file, so it works with the dev or demo sign-in and not with company sign-in.

Terminal window
npm run footnote -- validate lessons.yaml # no service needed
npm run footnote -- import lessons.yaml --as per_maria@example.test # dry run
npm run footnote -- import lessons.yaml --apply --as per_maria@example.test # suggestions, for review
npm run footnote -- draft item.yaml --as per_maria@example.test # one draft
npm run footnote -- import-tests questions.yaml --as per_maria@example.test # test questions, dry run
npm run footnote -- export --out edition.json --as per_maria@example.test # the live edition
npm run footnote -- verify edition.json # recompute the digests
npm run footnote -- audit --format csv --as per_ravi@example.test
OptionSettingDefault
--asFOOTNOTE_EMAILNone
--urlFOOTNOTE_URLhttp://127.0.0.1:3000
--originFOOTNOTE_ORIGINThe first of FOOTNOTE_WEB_ORIGINS, else the service’s default

--json prints the result as JSON, for scripts and coding agents. The exit status is 0 when done, 1 when the file has problems or the service refused, and 2 for wrong usage.