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.