Skip to content
footnote Docs
Install

HTTP API overview

Everything the web app does goes through the same HTTP API, under /api/v1. This page says how to call it. Every operation, with its fields, is in the generated OpenAPI description.

Sign in

The API uses the web app’s session. Sign in as a person, then send with each change:

WhatWhy
The cookieThe session, for every call
OriginOne of the allowed web origins, FOOTNOTE_WEB_ORIGINS
x-footnote-csrfThe session’s token, on every change

To script against it with the dev or demo sign-in, use the footnote command, which handles all three. It cannot sign in through company sign-in.

GET /api/v1/auth/methods says how this install signs people in, whether it is the demo, and the label naming it (FOOTNOTE_PROFILE_LABEL).

Safe retries

Changes that take an Idempotency-Key header can be sent twice. The key is 8 to 128 printable characters and belongs to the person for 24 hours.

You sendYou get
The same request with the same keyThe first response again
Other content with the same key422
The same key while the first is running409

Stale writes

Reads give a revision, and changes send it back. If someone changed the record in between, the answer is 409, and for a suggestion it carries the current record. Read it again, then retry.

Undo

A decision that can be taken back answers with undo: a token, and until, the time the service stops taking it (the Undo window after the decision, 15 seconds by default; null when it is taken at any time). Send the token to POST /api/v1/decisions/undo, as the same person, before then.

Answers that say no

StatusWhat it means
400The request is not in the right form
401Nobody is signed in
403The person may not do this
404Not found, or the person may not read it
409The record moved, or the key is in use
412What the request depends on does not exist yet
422The content was refused. The answer says what is wrong
429Over a limit. Retry-After says how many seconds to wait

Limits

Each person may send 600 requests a minute, and each address 120 before sign-in. Admins change this with limits.api_rate_per_minute. /health, /health/ready and /metrics are not limited.

What the API covers

PartPaths under /api/v1What it is for
Context/library, /items, /context, /drafts, /searchRead, change, publish and restore context items
Suggestions/proposalsSave, send and withdraw suggestions
Review/review, /decisionsRead a suggestion, publish it or return it
Inbox/inbox, /setupThe cards each person sees, and the setup checklist
Domains/areas, /assignmentsCreate domains and say who looks after them
People/members, /invites, /rolesWho is in the workspace, and their roles
Comments/comments, /reactionsThreads under a suggestion or a context item
Reports/reportsNamed reports from Ask
Conflicts/conflictsRead and settle pairs that disagree
Definitions/catalogue, /terms, /definitionsMetrics, dimensions, terms and synonyms
Ask/ask, /figures, /try-itAnswers, Asked this week and figures
Saved questions/saved-questionsKeep and check questions for a domain
Alerts/alertsAlert rules, mutes and what they raised
Observability/observabilityWhat agents asked and what they got, as counts
Integrations/sourcesConnect, test, read and disconnect a tool
Agents/connect, /agents, /connections, /access-keys, /agent-policiesConnected agents, tools, access keys and policies
Administration/settings, /audit, /editions, /imports, /operationsSettings, the history log, imports, exports and jobs

Some operations have no screen in the web app. Administer the service lists the common ones.