HONK(3) | Library Functions Manual | HONK(3)

# NAME

`honk` — API access

# DESCRIPTION

In addition to the standard web interface, some functionality is available via the `honk` HTTP API.

With the exception of login, all requests should contain the following form values.

action
  The desired action. See below.
token
  An authorization token. Alternatively, may be passed in the “Authorization” HTTP header.

The API URL for all actions other than login and logout is /api.

## login

Send a POST request to /dologin with the following form values.

username
  User name.
password
  Pass phrase.
gettoken
  Must be “1”.

This will return a token to be used for future requests. The token is valid for one year.

## logout

Send a request to /logout with the token to be expired.

## honk

The action value should be “honk”. Content type should be multipart/form-data if an attachment is included. The following values are recognized:

noise
  The contents of the honk.
format
  The format of noise. Defaults to markdown. May also be html.
donk
  A file to attach.
donkdesc
  A description for the attached file.
donkxid
  The XID of a previously uploaded attachment.
placename
  The name of an associated location.
placeurl
  The url of an associated location.
placelat
  The latitude of an associated location.
placelong
  The longitude of an associated location.
timestart
  The start time of an event.
rid
  The ActivityPub ID that this honk is in reply to.

Upon success, the honk action will return the URL for the created honk.

## donk

Upload just an attachment using donk and donkdesc. Content type must be multipart/form-data. Will return the XID.

## gethonks

The “gethonks” action can be used to query for honks. The following parameters are used.

page
  Should be one of “home” or “atme”.
after
  Only return honks after the specified ID.
wait
  If there are no results, wait this many seconds for something to appear.

The result will be returned as json.

## zonkit

The “zonkit” action began life as a delete function, but has since evolved some other powers as specified by the wherefore parameter. The target of the action is specified by the what parameter and is generally the XID of a honk.

Wherefore must be one of the following.

bonk
  Share honk with others.
unbonk
  Undo share.
save
  Mark honk as saved.
unsave
  Unmark honk as saved.
react
  Post an emoji reaction. A custom reaction may be specified with reaction.
ack
  Mark honk as read.
deack
  Unmark honk as read.
zonk
  Delete this honk.
zonvoy
  Mute this thread. What should identify a convoy.

## gethonkers

Returns a list of current honkers in json format.

## savehonker

Save a new honker, or update an existing one. The following fields are used.

honkerid
  The numeric ID of an existing honker to update.
name
  The preferred short name.
url
  The ActivityPub actor url.
combos
  Space separated list of combos.
notes
  Some notes.

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.

## sendactivity

Send anything. No limits, no error checking.

rcpt
  An actor to deliver the message to to. May be specified more than once. An inbox may be specified directly by prefixing with %.
msg
  The message. It should be a valid json activity, but yolo.
public
  Set to 1 to use shared inboxes for delivery.

# EXAMPLES

Refer to the sample code in the toys directory.

# SEE ALSO

vim(3)

June 6, 2025 | macOS 13.7