From a3ed3de9e3b38a1ff32c9e533fe6e1283d52b05a Mon Sep 17 00:00:00 2001
From: Ted Unangst <tedu@tedunangst.com>
Date: Sun, 10 Nov 2019 19:49:35 -0500
Subject: [PATCH] document the API, such as it is

---
 docs/honk.3  | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/intro.1 |  2 ++
 docs/vim.3   |  4 ++-
 3 files changed, 92 insertions(+), 1 deletion(-)
 create mode 100644 docs/honk.3

diff --git a/docs/honk.3 b/docs/honk.3
new file mode 100644
index 0000000..22374c1
--- /dev/null
+++ b/docs/honk.3
@@ -0,0 +1,87 @@
+.\"
+.\" Copyright (c) 2019 Ted Unangst
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate$
+.Dt HONK 3
+.Os
+.Sh NAME
+.Nm honk
+.Nd API access
+.Sh DESCRIPTION
+In addition to the standard web interface, some functionality is
+available via the
+.Nm
+HTTP API.
+.Pp
+With the exception of login, all requests should contain
+the following form values.
+.Bl -tag -width action
+.It Fa action
+The desired action.
+See below.
+.It Fa token
+An authorization token.
+.El
+.Ss login
+Send a POST request to
+.Pa /login
+with the following form values.
+.Bl -tag -width username
+.It Fa username
+User name.
+.It Fa password
+Pass phrase.
+.It Fa gettoken
+Must be
+.Dq 1 .
+.El
+.Pp
+This will return a token to be used for future requests.
+The token is valid for one year.
+You can stop using the API at any time, but you can never logout.
+.Ss honk
+The
+.Fa action
+value should be
+.Dq honk .
+The following values are recognized:
+.Bl -tag -width placename
+.It Fa noise
+The contents of the honk in markdown format.
+.It Fa donk
+A file to attach.
+.It Fa donkdesc
+A description for the attached file.
+.It Fa placename
+The name of an associated location.
+.It Fa placeurl
+The url of an associated location.
+.It Fa placelat
+The latitude of an associated location.
+.It Fa placelong
+The longitude of an associated location.
+.It Fa timestart
+The start time of an event.
+.It Fa rid
+The ActivityPub ID that this honk is in reply to.
+.El
+.Pp
+Upon success, the honk action will return the URL for the created honk.
+.Sh EXAMPLES
+Refer to the sample code in the
+.Pa toys
+directory.
+.Sh SEE ALSO
+.Xr vim 3
diff --git a/docs/intro.1 b/docs/intro.1
index ad47eef..3c38bcf 100644
--- a/docs/intro.1
+++ b/docs/intro.1
@@ -34,6 +34,8 @@ Honk composition.
 Honk Filtering and Censorship System.
 .It Xr activitypub 7
 ActivityPub implementation notes.
+.It Xr honk 3
+API access for robotrons.
 .It Xr vim 3
 Modifying honk.
 .El
diff --git a/docs/vim.3 b/docs/vim.3
index ef60cd3..587cf0f 100644
--- a/docs/vim.3
+++ b/docs/vim.3
@@ -14,7 +14,7 @@
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .Dd $Mdocdate$
-.Dt VIM 1
+.Dt VIM 3
 .Os
 .Sh NAME
 .Nm vim
@@ -24,3 +24,5 @@ The vital improvements module,
 .Nm ,
 is used to customize and extend honk in such rare cases as the
 existing functionality proves insufficient.
+.Sh SEE ALSO
+.Xr honk 3