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.
 36Alternatively, may be passed in the
 37.Dq Authorization
 38HTTP header.
 39.El
 40.Pp
 41The API URL for all actions other than login and logout is
 42.Pa /api .
 43.Ss login
 44Send a POST request to
 45.Pa /dologin
 46with the following form values.
 47.Bl -tag -width username
 48.It Fa username
 49User name.
 50.It Fa password
 51Pass phrase.
 52.It Fa gettoken
 53Must be
 54.Dq 1 .
 55.El
 56.Pp
 57This will return a token to be used for future requests.
 58The token is valid for one year.
 59.Ss logout
 60Send a request to
 61.Pa /logout
 62with the
 63.Fa token
 64to be expired.
 65.Ss honk
 66The
 67.Fa action
 68value should be
 69.Dq honk .
 70The following values are recognized:
 71.Bl -tag -width placename
 72.It Fa noise
 73The contents of the honk.
 74.It Fa format
 75The format of noise.
 76Defaults to markdown.
 77May also be html.
 78.It Fa donk
 79A file to attach.
 80.It Fa donkdesc
 81A description for the attached file.
 82.It Fa placename
 83The name of an associated location.
 84.It Fa placeurl
 85The url of an associated location.
 86.It Fa placelat
 87The latitude of an associated location.
 88.It Fa placelong
 89The longitude of an associated location.
 90.It Fa timestart
 91The start time of an event.
 92.It Fa rid
 93The ActivityPub ID that this honk is in reply to.
 94.El
 95.Pp
 96Upon success, the honk action will return the URL for the created honk.
 97.Ss gethonks
 98The
 99.Dq gethonks
100.Fa action
101can be used to query for honks.
102The following parameters are used.
103.Bl -tag -width placename
104.It Fa page
105Should be one of
106.Dq home
107or
108.Dq atme .
109.It Fa after
110Only return honks after the specified ID.
111.It Fa wait
112If there are no results, wait this many seconds for something to appear.
113.El
114.Pp
115The result will be returned as json.
116.Ss sendactivity
117Send anything.
118No limits, no error checking.
119.Bl -tag -width public
120.It Fa rcpt
121An actor to deliver the message to to.
122May be specified more than once.
123An inbox may be specified directly by prefixing with %.
124.It Fa msg
125The message.
126It should be a valid json activity, but yolo.
127.It Fa public
128Set to 1 to use shared inboxes for delivery.
129.El
130.Sh EXAMPLES
131Refer to the sample code in the
132.Pa toys
133directory.
134.Sh SEE ALSO
135.Xr vim 3