1.\"
  2.\" Copyright (c) 2019 Ted Unangst
  3.\"
  4.\" Permission to use, copy, modify, and distribute this software for any
  5.\" purpose with or without fee is hereby granted, provided that the above
  6.\" copyright notice and this permission notice appear in all copies.
  7.\"
  8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 15.\"
 16.Dd $Mdocdate$
 17.Dt HONK 3
 18.Os
 19.Sh NAME
 20.Nm honk
 21.Nd API access
 22.Sh DESCRIPTION
 23In addition to the standard web interface, some functionality is
 24available via the
 25.Nm
 26HTTP API.
 27.Pp
 28With the exception of login, all requests should contain
 29the following form values.
 30.Bl -tag -width action
 31.It Fa action
 32The desired action.
 33See below.
 34.It Fa token
 35An authorization token.
 36.El
 37.Pp
 38The API URL for all actions other than login and logout is
 39.Pa /api .
 40.Ss login
 41Send a POST request to
 42.Pa /dologin
 43with the following form values.
 44.Bl -tag -width username
 45.It Fa username
 46User name.
 47.It Fa password
 48Pass phrase.
 49.It Fa gettoken
 50Must be
 51.Dq 1 .
 52.El
 53.Pp
 54This will return a token to be used for future requests.
 55The token is valid for one year.
 56.Ss logout
 57Send a request to
 58.Pa /logout
 59with the
 60.Fa token
 61to be expired.
 62.Ss honk
 63The
 64.Fa action
 65value should be
 66.Dq honk .
 67The following values are recognized:
 68.Bl -tag -width placename
 69.It Fa noise
 70The contents of the honk in markdown format.
 71.It Fa donk
 72A file to attach.
 73.It Fa donkdesc
 74A description for the attached file.
 75.It Fa placename
 76The name of an associated location.
 77.It Fa placeurl
 78The url of an associated location.
 79.It Fa placelat
 80The latitude of an associated location.
 81.It Fa placelong
 82The longitude of an associated location.
 83.It Fa timestart
 84The start time of an event.
 85.It Fa rid
 86The ActivityPub ID that this honk is in reply to.
 87.El
 88.Pp
 89Upon success, the honk action will return the URL for the created honk.
 90.Ss gethonks
 91The
 92.Dq gethonks
 93.Fa action
 94can be used to query for honks.
 95The following parameters are used.
 96.Bl -tag -width placename
 97.It Fa page
 98Should be one of
 99.Dq home
100or
101.Dq atme .
102.It Fa after
103Only return honks after the specified ID.
104.It Fa wait
105If there are no results, wait this many seconds for something to appear.
106.El
107.Pp
108The result will be returned as json.
109.Sh EXAMPLES
110Refer to the sample code in the
111.Pa toys
112directory.
113.Sh SEE ALSO
114.Xr vim 3