We just merged some updates to the /user/change_user_settings endpoint to add a bunch of user settings that were previously only found in the web ui. I have tried to compile them in a list below. However, first I wanted to provide a bit of extra information about the visibility settings that have been added.

Part of this update adds visibility controls for NSFW posts, NSFL posts, and posts made by bot accounts. Previously in the api, NSFW and NSFL controls were just a simple on/off control. I have retained those fields as a Boolean so that nothing breaks with existing api clients. However, I have added new fields that override the old ones if they are provided. They offer a more fine-grained control over the visibility of the content that mirrors what is available in the web ui. Namely, the new options are:

• Show - posts show up in the feed
• Hide - completely hides the posts from the feed
• Blur - In the web ui, this setting blurs any thumbnail or text previews associated with these posts until the thumbnail is expanded or the post is clicked into. This feature would need to be implemented client side to match your client's styling if you want to support it.
• Transparent - In the web ui, this setting makes these posts semi-transparent (css: opacity: 0.2;) until the thumbnail is expanded or the post is clicked into. This feature would need to be implemented client side to match your client's styling if you want to support it.

As mentioned above, these settings are available for three different kinds of content; bot posts through the bot_visibility setting, nsfw posts through the nsfw_visibility setting, and nsfl posts through the nsfl_visibility setting. The old show_nsfw and show_nsfl fields are still there, but are overridden if the corresponding *_visibility field is provided. Also, as part of this, the LocalUser schema now returns additional fields for the new settings. There are now the three *_visibility fields there as well as the show_nsfw and show_nsfl fields. The show_* fields will be marked as true for any visibility option other than Hide. If you have questions, feel free to ask here or hit us up on matrix or zulip.

Without further ado, here are the new fields in the /user/change_user_settings endpoint:

• accept_private_messages - controls who the user will accept private messages from
• bot - marks or unmarks the user as a bot account
• bot_visibility - as discussed above, offers more options for how to display bot posts (will need to be implemented client side if you plan to support them)
• community_keyword_filter - a list of words which will prevent communities with those words in their name from appearing in the user's feed
• email_unread - receive an email about unread notifications occasionally (if the local admin has set it up)
• federate_votes - setting to control whether the user's votes are federated out (more public) or only stay on the local instance (more private)
• feed_auto_follow - setting that auto-subscribes to any community in a feed that the user subscribes to
• feed_auto_leave - setting that auto-unsubscribes to any community in a feed that the user unsubscribed to (if the user subscribed outside of being auto-subscribed, then they will not be auto-unsubscribed)
• hide_low_quality - setting that hides communities that are marked as low quality by the local admin from the user's feed
• indexable - setting to allow the user's posts to show up using the search function
• newsletter - subscribe to the local instance's newsletter (if the local admin has set it up or ever uses it)
• nsfl_visibility - as discussed above, offers more options for how to display nsfl posts (will need to be implemented client side if you plan to support them)
• nsfw_visibility - as discussed above, offers more options for how to display nsfw posts (will need to be implemented client side if you plan to support them)
• reply_collapse_threshold - in the web ui, post replies below this score are automatically collapsed, but can still be expanded to be viewed (will need to be implemented client side if you plan to support this)
• searchable - setting to allow the user to show up in the user list on the instance
• reply_hide_threshold - in the web ui, post replies below this threshold are automatically hidden completely (will need to be implemented client side if you plan to support this)

I have pushed these changes to the crust server (swagger here). Let us know if you run into any issues or have feedback/questions/suggestions!

Hi devs and API enthusiasts!

Just wanted to call your attention to a change in the way posts are returned in the /post/list endpoint in the api. This hasn't been backported, so only instances running 1.3.0-dev (the main branch) would currently have this change. The stable, 1.2.x branch is unaffected.

Now, when you are filtering to a single community (either by providing a community_name or a community_id), any sticky posts for that community will be returned as the first results of page 1, regardless of the sort order specified. This matches the web ui behavior where sticky posts are...well...stuck to the top of the community's list of posts.

One aspect that is different than the web ui is that as you page through the posts, the api will not keep the sticky posts at the top of the results for pages 2+. This should make it easier to create a seamless flow from one page into the next for something like an infinite scroll since the sticky posts won't keep showing up with each request for subsequent pages.

I added an ignore_sticky parameter that, when true, allows you to turn off the stickiness of posts when returning results. This should help for applications where you don't care what posts are sticky or not, but you just want them sorted in a specific way.

Let me know if you have any questions or feedback!

I have taken a pass over another set of endpoints, this time the /user endpoints. Overall, there were less changes to these endpoints compared to previous groups I have done. Most of the work for this group focused on the /user/notifications endpoint. This is because marshmallow (the python library doing the schema validation for us) doesn't allow any kind of polymorphism in its schemata, thereby preventing the use of the anyOf part of the OpenAPI spec. So, I had to define a base notification schema and then tried to document the optional fields to indicate what fields would be present for which type of notification.

Here is crust running the updated swagger and here is the codeberg PR. I have included a changelog compared to 1.1 below:

• GET /user

  • limit input parameter now defaults to 20. Previously default was 50 for posts and 10 for comments.

• PUT /user/subscribe

  • added subscribed field to response to mirror similar pattern elsewhere, like /user/block

• PUT /user/save_user_settings

  • Documented some input fields that were previously undocumented in the swagger
  • Documented the response

• POST /user/set_flair

  • modified so that either omitting the flair_text field or setting it to null will remove existing flair

• GET /user/notifications

  • status input field options renamed to one of Unread, Read, or All
  • unread field replaces new_notifications in the counts field
  • read field replaces read_notifications in the counts field
  • total field replaces total_notifications in the counts field
  • I had to redefine the schema for the items field because the auto-documenting library we are using doesn't support the OpenAPI anyOf feature. So, this field is now a list of a generic notification schema. I have documented which types of notifications the optional fields are returned for.
  • username field replaces user since it is just a string rather than a whole schema

• I added the about_html field to a couple schema (/site and /user/save_user_settings responses both have it) as the html version of a user's about in case it would be easier for you to use the html version of a user's bio instead of markdown.

Me again, here to document some more upcoming api changes as the self-documentation adventure continues. This time, it is the /topic/list endpoint. Similar to feeds, this endpoint exists in 1.1, but it was undocumented. This has led to it not being widely used yet, so I have taken the liberty to make a series of changes to it to help it be more consistent with other endpoints. This has mostly taken the form of field name changes. In the end, this endpoint now looks and functions very similarly to /feed/list by design.

Here is the updated swagger running on crust, and here is the codeberg PR if you prefer to look things over there.

If you have made use of this endpoint in its 1.1 form, I have included a changelog compared to 1.1 below. Let me know if there are any questions/feedback/requested changes.

Changes from 1.1:

• Added include_communities request parameter. Functions exactly the same way as the /feed/list endpoint.
• Dropped version field
• Multiple field name changes for better consistency with other endpoints. I have summarized them in the table below:

Another post from me as I continue to work through endpoints. This endpoint is present in 1.1, but it is undocumented. AFAIK, only Boost has made use of it so far, so this might be of particular relevance for them. The updated swagger is available here for your perusal. If you have already experimented with this endpoint from 1.1, I have included the changelog below. So far, this is the only feed endpoint in the api, documented or otherwise. I am sure more will be added in the future.

This is still open for feedback/suggestions, so if there is something here that would help/hurt, please let me know!

Changes from 1.1:

• drop machine_name field as it was redundant with name field
• rename num_communities to communities_count to better align with other counts fields for other endpoints
• drop ap_id and ap_profile_id fields in favor of...
• new actor_id field is the url of the activitypub actor (examples: https://instance.tld/f/feed_name for a public feed or https://instance.tld/f/feed_name/user_name for a private feed)
• new ap_domain is the instance domain of the actor (example: piefed.social)
• rename show_posts_in_children to show_posts_from_children. This is purely a linguistic preference on my part and so I am taking the opportunity before this endpoint gets more widely used, to change it now.
• drop version field as it was not really informative
• new local field that is a boolean indicating whether the feed is local or remote

As part of our ongoing effort to make our api self-documenting and validating our api input/output, we have been working through the api endpoints one at a time to make things a bit more consistent and logical. I just finished doing this for our existing /community endpoints and thought I would share the changelog here for awareness and feedback.

As of right now, these changes are only live on my instance and on our new, dedicated testing instance, crust.piefed.social. The self-documenting swagger for 1.2 (a WIP) can be found here.

1.2 Community Endpoints Changelog

• PUT /community
  • input parameter community_id properly documented (was previously erroneously documented as id)
• GET /community/list
  • made next_page nullable if there is no next page
  • this change was backported to 1.1 already
• GET /community/moderate/bans
  • banned_by replaces bannedBy - transitioning everything to snake case
  • banned_user replaces bannedUser - transitioning everything to snake case
  • expired_at replaces expiredAt - transitioning everything to snake case
  • expired_at value of null indicates a permanent ban
  • expired_at only returned if ban has expired
  • expires_at field added, only returned if ban is still in effect
  • expires_at value of null indicates permanent ban
• PUT /community/moderate/unban
  • same field name changes as above (snake_case instead of camelCase)
  • expired_at is now set equal to current time if ban was found (indicating that it was just set to expired) and returned in standard timestamp format found elsewhere in the api (2025-06-07T02:29:07.980084Z)
• POST /community/moderate/ban
  • Input:
    • expires_at replaces expiredAt/expired_at for input
    • expires_at uses standard timestamp format (2025-06-07T02:29:07.980084Z)
    • expires_at is optional
    • expires_at is checked to make sure it is in the future, raises an exception if it is not
    • permanent is new optional boolean field, supercedes expires_at if true
    • If expires_at is not provided and permanent is either false or not provided, then the ban is set to expire in one year
  • Output:
    • same field name changes as above (snake_case instead of camelCase)
    • expires_at value of null indicates permanent ban
    • standardize timestamp format of expires_at
    • only returns expires_at because it is a time in the future (does not return expired_at)

As part of our ongoing effort to make the piefed api self-documenting and validate the input and output, there have been a couple tweaks to the api. I realized that I should probably document them here since not everybody is keeping tabs on every codeberg PR that comes through the repo.

• canAuthUserModerate has been renamed to can_auth_user_moderate in the CommentView schema. This transitioning from camelCase to snake_case will be a theme as I work my way through the endpoints, this is just the first that I ran across.
• The title field in the PersonView schema will now be equal to the user_name instead of null if the user never set a display name. The way this was handled was a bit inconsistent between local and remote users, but now all users should have this behave the same way.
• All of the timestamps in the InstanceWithoutFederationState schema have been standardized to the same format. Previously, these were in the standard iso format, but didn't have the Z at the end.
• The Site schema can now return the site sidebar in html and markdown (if both formats are present). The sidebar field will continue to be html, while the new sidebar_md field will provide the markdown rendition of the sidebar. In the past, the sidebar was only in html, so the markdown version will only become available after an admin updates their instance's sidebar to use markdown instead of html.

That's all the changes that are live up to this point. I will continue to make posts in this community as changes are made to try to keep you all in the loop.

While we are talking about the future, other plans for the future are to have a dedicated development instance for testing bleeding edge code while keeping piefed.social on a more stable branch. In the meantime, feel free to peruse my instance's swagger ui (json version), which is up to date with the api changes as I am working on them (community endpoints are next).