Influence API

A plain JSON API for pages, files, spaces and search. Everything here is what the app itself uses.

Getting started

Everything the app does goes through this API. Make a token under Workspace. It acts as you, with exactly your permissions, so it can't read a page you can't.

export INF="https://harrowsoft.com/influence/api"
export TOKEN="your token"

curl -H "Authorization: Bearer $TOKEN" "$INF/search?q=deploy"

Send and receive JSON. Times are milliseconds since 1970, in UTC. When something goes wrong you get a status code and {"error": "A sentence you can show someone"}. A token can make 1,200 requests a minute. Past that you get a 429, and waiting a moment is enough.

Pages

The easiest way to write a page from a script is in Markdown.

curl -X POST "$INF/pages" -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"space": "ENG", "title": "How we deploy", "markdown": "## Before you start\n\n- Tests are green\n- Someone read the diff"}'

POST /pages	Make a page: space, and optionally title, parent, markdown, template, kind (page or board).
GET /page/{id}	One page with its words, comments, files, labels and versions so far.
GET /page/{id}/brief	A short look at one page: where it lives, how fresh it is, and how it starts.
POST /page/{id}/schedule	Publish a draft by itself at a moment you pick (at, milliseconds since 1970, within a year), or send null to keep it a plain draft.
GET /page/{id}/body	Just the title and the words.
PATCH /page/{id}	Change title, owner, labels or wide.
DELETE /page/{id}	Moves it to the trash.
POST /page/{id}/restore	Brings it back.
POST /page/{id}/move	Move it: parent, and optionally before.
POST /page/{id}/copy	A copy of it, with its files.
GET /page/{id}/export/{kind}	Download it: md, html or doc.
GET /page/{id}/versions	Every saved version.
GET /page/{id}/version/{num}	One old version.
POST /page/{id}/verify	Say it's still right, for a while.
POST /page/{id}/comments	Add a comment: body.
PATCH /comment/{id}	Change your comment: body.
DELETE /comment/{id}	Delete your comment.
POST /comment/{id}/resolve	Mark it done.
POST /page/{id}/watch	Follow it, or stop following it.

Files

curl -X POST "$INF/page/123/files" -H "Authorization: Bearer $TOKEN" -H "x-filename: plan.pdf" \
  -H "x-new-version: 1" -H "content-type: application/pdf" --data-binary @plan.pdf

POST /page/{id}/files	Upload a file as the raw body, with its name in x-filename. Up to 50 MB. With x-new-version: 1, a file of the same name gets a new version instead of a twin.
GET /file/{id}	Download the current version.
DELETE /file/{id}	Delete it and its versions.
GET /file/{id}/versions	Its earlier versions.
GET /file/{id}/version/{v}	Download an earlier version.
POST /file/{id}/version/{v}/restore	Make an earlier version current.

Search

curl -G "$INF/search" -H "Authorization: Bearer $TOKEN" --data-urlencode "q=how do we deploy" -d space=ENG -d trust=verified

GET /search	q, and optionally space, by (a person's id), trust (verified), label, limit. Typos still find it, and verified pages come first.
GET /labels	Every label in use.

Spaces

GET /boot	You, your workspace, its people and the spaces you can see.
POST /spaces	Make a space: name, and optionally key, description, private.
GET /space/{key}	A space with its page tree.
PATCH /space/{key}	Change name or description.
DELETE /space/{key}	Delete it and everything in it. Admins only.
GET /space/{key}/health	What's overdue for review, unowned or linking to nothing.
GET /space/{key}/trash	Pages in its trash.
GET /templates	The templates you can start from.

People and everything else

POST /invites	An invite link: role (admin, member, viewer).
PATCH /member/{id}	Change role, or active to remove or bring someone back.
PUT /account/prefs	Your own settings. language is es, fr, de, or empty for English.
PUT /account/photo	Your picture, as the raw body: a JPEG or PNG under 512 KB, no side over 1,024 pixels.
PATCH /account/about	The few words beside your name: title, department and place, 80 characters each.
GET /push/key	The server's public key for Web Push, for pushManager.subscribe.
POST /push/subscribe	Turn notifications on for one device: its subscription, as PushSubscription.toJSON() gives it. Only the browsers' own push services are accepted.
POST /push/unsubscribe	Turn them off for one device: endpoint.
POST /push/test	Send a test notification to each of your devices.
GET /push/prefs	What buzzes your devices: off (kinds turned off), quiet (from and to in minutes of your day, and your clock's offset from UTC), and the kinds there are.
PUT /push/prefs	Change them: off and quiet (or null for none).
DELETE /account/photo	Take your picture away, so your initials show again.
GET /photo/{member}	Someone's picture, if you can see them. Add ?v= with their photo number from the people list, and it can be kept for good.
GET /notifications	What's aimed at you.
GET /audit	Who did what. Admins only.
GET /export	Every page, comment and file as one zip. Admins only.

Scripts written for Confluence

Anything written for Confluence keeps working. Point it at https://harrowsoft.com/influence/wiki and sign in with your email and a token. Our tests run the real atlassian-python-api client, for both Server and Cloud.

GET /rest/api/content	The classic API: content, search, spaces, labels, history, children and comments.
GET /api/v2/pages	List pages. Filter with space-id, title, status.
POST /api/v2/pages	Make a page: spaceId, title, body, and optionally parentId.
GET /api/v2/pages/{id}	One page. Add body-format=storage for its words.
PUT /api/v2/pages/{id}	Change a page. Send the next version.number.
GET /api/v2/pages/{id}/direct-children	The pages under it.
GET /api/v2/pages/{id}/versions	Its versions.
GET /api/v2/pages/{id}/labels	Its labels.
GET /api/v2/pages/{id}/footer-comments	Its comments.
GET /api/v2/blogposts	List blog posts.
GET /api/v2/spaces	List spaces. Filter with keys.
GET /api/v2/spaces/{id}/pages	The pages in a space.

Automation

A rule starts from something that happens, on a schedule, from a button on a page, or from another system. In its words, {{page.title}}, {{page.url}}, {{page.space}}, {{page.owner}}, {{actor}} and {{now}} fill themselves in.

GET /rules	Rules. Add ?space=ENG for one space's. Admins only.
POST /rules	Make one: name, trigger, config with if and then, and optionally space. A scheduled rule also has every and cql.
PATCH /rule/{id}	Change it, or turn it off with enabled.
DELETE /rule/{id}	Delete it.
GET /rule/{id}/log	What it did lately.
GET /page/{id}/rules	Rules someone can run from this page.
POST /page/{id}/rules/{rule}	Run one.

Looking after pages

GET /page/{id}/approval	Every round of approval on a page.
POST /page/{id}/approval	Ask for approval: people, and optionally message and due_at.
POST /page/{id}/approval/answer	answer is approve or changes, with an optional comment.
DELETE /page/{id}/approval	Call it off.
GET /page/{id}/watchers	Who's watching.
POST /page/{id}/watchers	Add a member.
POST /page/{id}/react	Add or take off an emoji.
GET /page/{id}/related	Pages like this one.
POST /page/{id}/ask-access	Ask to see a page. It answers the same whether the page exists or not.
POST /page/{id}/redact	Replace text with a solid bar. history does earlier versions too. Admins only.
GET /space/{key}/content	Every page in a space. Filter with q, owner, idle, kind, status.
POST /space/{key}/content	Do one thing to many pages: ids and action (archive, restore, trash, owner, move, label).
POST /import/document	Bring in a file: ?space=ENG, and x-filename saying what it is. Word, HTML, Markdown or a Notion zip.
GET /synced	Synced blocks.
POST /synced	Make one: title and doc.
PUT /synced/{id}	Change it everywhere.

Questions

GET /questions	Questions, newest first. ?q= searches, ?topic= narrows, ?show= takes top, unanswered or mine.
POST /questions	title, body, topics.
POST /question/{id}/answers	body.
POST /question/{id}/accept	answer, or null to clear it.
GET /space/{key}/book	Every page of a space in reading order, as HTML, with its PDF settings.
GET /file/{id}/comments	Comments on a file.
POST /file/{id}/comments	body.

Single sign-on

Set this up under Workspace settings, over OpenID Connect or SAML. These addresses are what your provider needs. {slug} is the short name you choose there.

GET /influence/sso/{slug}	Starts a sign-in.
POST /influence/sso/{slug}/acs	Where a SAML provider sends people back. Assertions must be signed, and not encrypted.
GET /influence/sso/{slug}/metadata	This workspace's SAML details, for providers that read metadata.

Monitoring

Off until you set INF_METRICS_TOKEN in the service's environment. Send that token as a bearer token. The numbers are counts and sizes, in Prometheus's text format, and they name nobody.

GET /influence/metrics

Counts for a monitoring tool.