# Known RPC host

Wikis are served here to apps their organization registered, as the person signed in — never to anyone without a token. Each wiki's own document is at https://rpc.known.info/rpc/<wiki>, for a token that may read it. This page as JSON: https://rpc.known.info/rpc.json

## Signing in

An app signs people in with Known through OAuth 2.0's authorization code flow with PKCE (S256). No app holds a secret.

1. An organization registers the app, its exact redirect URIs, and attaches the wikis it may read: in Known under Settings → Apps, or `known <org> apps create`.
2. Send the person to `https://known.info/authorize` with `response_type=code`, `client_id`, `redirect_uri` (exactly as registered), `state`, `code_challenge`, `code_challenge_method=S256`, and `scope`: wiki:<wiki>:read, space-separated; none signs the person in with no wiki. Known signs them in and sends them back with `code` and `state`.
3. `POST https://rpc.known.info/oauth/token` with `grant_type=authorization_code`, `code`, `code_verifier`, `client_id`, `redirect_uri`. The answer: `access_token` (an hour), `refresh_token`, `scope` (the wikis granted).
4. Call this host with `Authorization: Bearer <access_token>`. Refresh with `grant_type=refresh_token`, `refresh_token`, `client_id`; each refresh token works once. Sign out with `POST https://rpc.known.info/oauth/revoke` (`token`, `client_id`).

## How to call

JSON-RPC 2.0 over `POST https://rpc.known.info/rpc`, one named-params object per call. Paths are full: the wiki slug, then the page path, dot-separated.

- Every call carries a token from Known sign-in: `Authorization: Bearer <access_token>`. An app reads the wikis the person granted it at sign-in, as that person, while they may still read them.
- Reads only, for now. Page authoring, notes and records are written in Known.
- Every call names a path or a wiki; there is no listing of wikis. `app.whoami` says who is signed in and which wikis the app may read for them.

With curl:

```sh
curl -s https://rpc.known.info/rpc -H 'content-type: application/json' -H 'authorization: Bearer <access_token>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"wiki.tree","params":{"path":"<wiki>","depth":1}}'
```

With methodry, in a browser, signed in through `wiki/session`:

```js
import { createClient } from 'methodry'
import { methodryAuth } from 'wiki/session'
const rpc = createClient('https://rpc.known.info', null, methodryAuth(session))
const { response: page, refused } = await rpc.wiki.get({ path: '<wiki>' })
```

A refusal is a JSON-RPC error whose `data.refused` is true. Its codes:

- `-32602` invalid params
- `-32003` forbidden
- `-32004` not found
- `-32009` conflict

## Methods

### wiki.get

Read one page: its title, content, metadata, and revision, as it is now or as it was at a commit or time. Capability: read. Returns: page.

- `path` (string): the full path of the page, wiki slug first
- `commitId` (number, optional): read the page as of this commit
- `at` (string, optional): read the page as of this ISO-8601 time

### wiki.tree

The page hierarchy under a path, with each page's record count. Capability: read. Returns: tree.

- `path` (string): the full path to start from; the wiki slug alone is the whole wiki
- `depth` (number, optional): how many levels down to include
- `commitId` (number, optional): the tree as of this commit
- `at` (string, optional): the tree as of this ISO-8601 time

### wiki.search

Full-text search under a path: pages, and the records of tables. A record hit names its page and key. Capability: read. Returns: hit[].

- `path` (string): the full path to search under
- `query` (string): the words to find
- `limit` (number, optional): at most this many hits

### wiki.history

A page's revisions, newest first. Capability: read. Returns: revision[].

- `path` (string): the full path of the page
- `limit` (number, optional): at most this many revisions

### wiki.log

The wiki's commit log under a path, newest first, each commit with the pages it changed. Capability: read. Returns: commit[].

- `path` (string): the full path to read the log under
- `limit` (number, optional): at most this many commits
- `before` (number, optional): only commits before this commit id

### wiki.getCommit

One commit of a wiki, with what it changed; the latest when no id is given. Capability: read. Returns: commit.

- `wiki` (string): the wiki slug
- `commitId` (number, optional): the commit to read

### wiki.revision

One revision of a page by id, and the revision before it, for a diff. Capability: read. Returns: revision.

- `wiki` (string): the wiki slug
- `revisionId` (string): the revision to read

### wiki.snapshot

Every page of a wiki as it was at a commit or time. Capability: read. Returns: snapshot.

- `wiki` (string): the wiki slug
- `commitId` (number, optional): the wiki as of this commit
- `at` (string, optional): the wiki as of this ISO-8601 time

### wiki.data

Read a page's records: one by key, or a range by time, paged by cursor, or the records the page held at a moment. Tables read in key order, logs in time order. Capability: read. Returns: records.

- `path` (string): the full path of the page
- `key` (string, optional): one record, by key; combines with no other option
- `latest` (boolean, optional): only the newest record
- `since` (string, optional): records at or after this ISO-8601 time
- `until` (string, optional): records before this ISO-8601 time
- `limit` (number, optional): at most this many records
- `cursor` (string, optional): continue a previous read from where it stopped
- `reverse` (boolean, optional): newest first, or highest key first
- `at` (string, optional): the records as they stood at this ISO-8601 time: a table whole, with `unknown` naming keys whose state then was not kept; a log in pages, the records written by then

### wiki.versions

A table record's versions, newest first: each as the record that version left (no fields on a deletion), with its stamps and _change (created, updated, deleted). The history outlives the record. Capability: read. Returns: versions.

- `path` (string): the full path of the table
- `key` (string): the record's key
- `limit` (number, optional): at most this many versions
- `cursor` (string, optional): continue a previous read from where it stopped

### wiki.version

One version of a table record and the version before it, for a diff. Capability: read. Returns: version.

- `path` (string): the full path of the table
- `key` (string): the record's key
- `version` (number): the version to read

### wiki.links

What links to a page, or to one of its records: the pages whose content and the records that carry a wikilink to it. A linking record comes with its value. Capability: read. Returns: links.

- `path` (string): the full path of the page
- `key` (string, optional): a record of the page, by key; without it, the page itself
- `limit` (number, optional): at most this many links