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 donkxid
 83The XID of a previously uploaded attachment.
 84.It Fa placename
 85The name of an associated location.
 86.It Fa placeurl
 87The url of an associated location.
 88.It Fa placelat
 89The latitude of an associated location.
 90.It Fa placelong
 91The longitude of an associated location.
 92.It Fa timestart
 93The start time of an event.
 94.It Fa rid
 95The ActivityPub ID that this honk is in reply to.
 96.El
 97.Pp
 98Upon success, the honk action will return the URL for the created honk.
 99.Ss donk
100Upload just an attachment using
101.Fa donk
102and
103.Fa donkdesc .
104Will return the XID.
105.Ss gethonks
106The
107.Dq gethonks
108.Fa action
109can be used to query for honks.
110The following parameters are used.
111.Bl -tag -width placename
112.It Fa page
113Should be one of
114.Dq home
115or
116.Dq atme .
117.It Fa after
118Only return honks after the specified ID.
119.It Fa wait
120If there are no results, wait this many seconds for something to appear.
121.El
122.Pp
123The result will be returned as json.
124.Ss sendactivity
125Send anything.
126No limits, no error checking.
127.Bl -tag -width public
128.It Fa rcpt
129An actor to deliver the message to to.
130May be specified more than once.
131An inbox may be specified directly by prefixing with %.
132.It Fa msg
133The message.
134It should be a valid json activity, but yolo.
135.It Fa public
136Set to 1 to use shared inboxes for delivery.
137.El
138.Sh EXAMPLES
139Refer to the sample code in the
140.Pa toys
141directory.
142.Sh SEE ALSO
143.Xr vim 3