honk/docs/honk.3

.\"
.\" 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.
Alternatively, may be passed in the
.Dq Authorization
HTTP header.
.El
.Pp
The API URL for all actions other than login and logout is
.Pa /api .
.Ss login
Send a POST request to
.Pa /dologin
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.
.Ss logout
Send a request to
.Pa /logout
with the
.Fa token
to be expired.
.Ss honk
The
.Fa action
value should be
.Dq honk .
Content type should be multipart/form-data if an attachment is included.
The following values are recognized:
.Bl -tag -width placename
.It Fa noise
The contents of the honk.
.It Fa format
The format of noise.
Defaults to markdown.
May also be html.
.It Fa donk
A file to attach.
.It Fa donkdesc
A description for the attached file.
.It Fa donkxid
The XID of a previously uploaded attachment.
.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.
.Ss donk
Upload just an attachment using
.Fa donk
and
.Fa donkdesc .
Content type must be multipart/form-data.
Will return the XID.
.Ss gethonks
The
.Dq gethonks
.Fa action
can be used to query for honks.
The following parameters are used.
.Bl -tag -width placename
.It Fa page
Should be one of
.Dq home
or
.Dq atme .
.It Fa after
Only return honks after the specified ID.
.It Fa wait
If there are no results, wait this many seconds for something to appear.
.El
.Pp
The result will be returned as json.
.Ss zonkit
The
.Dq zonkit
action began life as a delete function, but has since evolved some other
powers as specified by the
.Fa wherefore
parameter.
The target of the action is specified by the
.Fa what
parameter and is generally the XID of a honk.
.Pp
Wherefore must be one of the following.
.Bl -tag -width zonvoy
.It bonk
Share honk with others.
.It unbonk
Undo share.
.It save
Mark honk as saved.
.It unsave
Unmark honk as saved.
.It react
Post an emoji reaction.
A custom reaction may be specified with
.Fa reaction .
.It ack
Mark honk as read.
.It deack
Unmark honk as read.
.It zonk
Delete this honk.
.It zonvoy
Mute this thread.
What should identify a convoy.
.El
.Ss gethonkers
Returns a list of current honkers in json format.
.Ss savehonker
Save a new honker, or update an existing one.
The following fields are used.
.Bl -tag -width honkerid
.It Fa honkerid
The numeric ID of an existing honker to update.
.It Fa name
The preferred short name.
.It Fa url
The ActivityPub actor url.
.It Fa combos
Space separated list of combos.
.It Fa notes
Some notes.
.El
.Pp
The honker numeric ID will be returned for success.
To delete, unsub, or sub, include a form value with name and value equal.
As in, a form value named delete with the value delete, or unsub=unsub, etc.
.Ss sendactivity
Send anything.
No limits, no error checking.
.Bl -tag -width public
.It Fa rcpt
An actor to deliver the message to to.
May be specified more than once.
An inbox may be specified directly by prefixing with %.
.It Fa msg
The message.
It should be a valid json activity, but yolo.
.It Fa public
Set to 1 to use shared inboxes for delivery.
.El
.Sh EXAMPLES
Refer to the sample code in the
.Pa toys
directory.
.Sh SEE ALSO
.Xr vim 3