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 .
 70Content type should be multipart/form-data if an attachment is included.
 71The following values are recognized:
 72.Bl -tag -width placename
 73.It Fa noise
 74The contents of the honk.
 75.It Fa format
 76The format of noise.
 77Defaults to markdown.
 78May also be html.
 79.It Fa donk
 80A file to attach.
 81.It Fa donkdesc
 82A description for the attached file.
 83.It Fa donkxid
 84The XID of a previously uploaded attachment.
 85.It Fa placename
 86The name of an associated location.
 87.It Fa placeurl
 88The url of an associated location.
 89.It Fa placelat
 90The latitude of an associated location.
 91.It Fa placelong
 92The longitude of an associated location.
 93.It Fa timestart
 94The start time of an event.
 95.It Fa rid
 96The ActivityPub ID that this honk is in reply to.
 97.El
 98.Pp
 99Upon success, the honk action will return the URL for the created honk.
100.Ss donk
101Upload just an attachment using
102.Fa donk
103and
104.Fa donkdesc .
105Content type must be multipart/form-data.
106Will return the XID.
107.Ss gethonks
108The
109.Dq gethonks
110.Fa action
111can be used to query for honks.
112The following parameters are used.
113.Bl -tag -width placename
114.It Fa page
115Should be one of
116.Dq home
117or
118.Dq atme .
119.It Fa after
120Only return honks after the specified ID.
121.It Fa wait
122If there are no results, wait this many seconds for something to appear.
123.El
124.Pp
125The result will be returned as json.
126.Ss zonkit
127The
128.Dq zonkit
129action began life as a delete function, but has since evolved some other
130powers as specified by the
131.Fa wherefore
132parameter.
133The target of the action is specified by the
134.Fa what
135parameter and is generally the XID of a honk.
136.Pp
137Wherefore must be one of the following.
138.Bl -tag -width zonvoy
139.It bonk
140Share honk with others.
141.It unbonk
142Undo share.
143.It save
144Mark honk as saved.
145.It unsave
146Unmark honk as saved.
147.It react
148Post an emoji reaction.
149A custom reaction may be specified with
150.Fa reaction .
151.It ack
152Mark honk as read.
153.It deack
154Unmark honk as read.
155.It zonk
156Delete this honk.
157.It zonvoy
158Mute this thread.
159What should identify a convoy.
160.El
161.Ss gethonkers
162Returns a list of current honkers in json format.
163.Ss savehonker
164Save a new honker, or update an existing one.
165The following fields are used.
166.Bl -tag -width honkerid
167.It Fa honkerid
168The numeric ID of an existing honker to update.
169.It Fa name
170The preferred short name.
171.It Fa url
172The ActivityPub actor url.
173.It Fa combos
174Space separated list of combos.
175.It Fa notes
176Some notes.
177.El
178.Pp
179The honker numeric ID will be returned for success.
180To delete, unsub, or sub, include a form value with name and value equal.
181As in, a form value named delete with the value delete, or unsub=unsub, etc.
182.Ss sendactivity
183Send anything.
184No limits, no error checking.
185.Bl -tag -width public
186.It Fa rcpt
187An actor to deliver the message to to.
188May be specified more than once.
189An inbox may be specified directly by prefixing with %.
190.It Fa msg
191The message.
192It should be a valid json activity, but yolo.
193.It Fa public
194Set to 1 to use shared inboxes for delivery.
195.El
196.Sh EXAMPLES
197Refer to the sample code in the
198.Pa toys
199directory.
200.Sh SEE ALSO
201.Xr vim 3