Users

General User Identifiers

Unless otherwise specified, user identifiers can be any of the following:

  • User ID (1)
  • @username (@33mhz)
  • "me", when authenticated

User IDs are preferred where convenient, because they take less effort and will never change (unlike usernames).

Referring to usernames is not case-sensitive, but usernames will be returned from the API with the casing specified by the user -- so comparisons should normalize them before comparing.

Canonical User Profiles

Any user profile can be found at https://pnut.io/@username, which will redirect to the user profile.

User Fields

Field Type Description
badge object Badges are earned for various achievements.

Only set if user has a badge selected.

Field Type Description
id string Reference ID of the badge.
name string Common name for the badge.
content object
Field Type Description
avatar_image object
Field Type Description
is_default boolean Whether or not the user's avatar is the original identicon generated for their username, or an image they uploaded.
height integer Original height of the image.
url string URL linking to the current avatar image.
width integer Original width of the image.
cover_image object
Field Type Description
is_default boolean Whether or not the user has uploaded an image for their cover image, or if it is the default plain white background.
height integer Original height of the image.
url string URL linking to the current cover image.
width integer Original width of the image.
entities object Rich text information for this user. See the Entities documentation.
html string Server-generated annotated HTML rendering of user text.
markdown_text string text, with the original markdown links preserved.

Only set when looking up the authenticated user's profile or GET /token.
text string User supplied text of the user. All Unicode characters allowed. Maximum length 256 characters. The maximum length can be retrieved from the Configuration endpoint.
counts object
Field Type Description
bookmarks integer Number of bookmarks this user has saved.
clients integer Number of public clients this user has created.
followers integer Number of users following this user.
following integer Number of users this user is following.
posts integer Number of posts created by this user.
created_at string The time at which the User was created in ISO 8601 format; YYYY-MM-DDTHH:MM:SSZ.
follows_you boolean Whether or not this user follows you.

Only set on authenticated calls.
id string Primary identifier for a user. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed. This id space is unique to User objects. There can be a Post and User with the same ID; no relation is implied.
locale string User locale in ISO format.
name string User-supplied name. All Unicode characters allowed. Maximum length 50 characters. Be sure to escape if necessary.

Optional.
timezone string User timezone in tzinfo format. E.g., America/Chicago is the default when a user is created.
type string human, feed, or bot. See Account Types to be sure of the implications.
username string Case sensitive. 20 characters, may only contain a-z, 0-9 and underscore.
you_blocked boolean Whether or not you blocked this user.

Only set on authenticated calls.
you_can_follow boolean Whether or not you can follow this user -- not taking into account you_follow.

Only set on authenticated calls.
you_follow boolean Whether or not you follow this user.

Only set on authenticated calls.
you_muted boolean Whether or not you muted this user.

Only set on authenticated calls.
verified object

Optional.

Field Type Description
domain string Domain verified to be owned by the user.
url string URL verified to be owned by the user.
presence string User presence. Up to 100 characters.

Only set if include_presence is true.
raw object The raw items attached to this object.

Only set if query parameter specified.

Field Type Description
{type name} list of objects A list of objects of this type.

General User Parameters

Any endpoint that returns user objects (including any that return post objects, message objects, etc.) can be subject to these parameters.

General Parameters

Name Type Description Default
include_html integer (0 or 1) Should the post and user html field be included alongside the text field in the response objects? true
include_user_html integer (0 or 1) Should the user html field be included alongside the text field in the response objects? true.
include_counts integer (0 or 1) Include the user's counts. true
include_user integer (0 or 1) Return the user as their complete object, or only as (string) ID if false. true
include_presence integer (0 or 1) Include the user's current presence. false
include_raw integer (0 or 1) Include raw on all objects. false
include_user_raw integer (0 or 1) Include raw on all user objects. false

Locales

User locales the API recognizes are available as a comma-separated text file. To ask for more to be supported, make a feature request to the API GitHub repository. We would like to have translations of all of these for pnut.io account management. You may make pull requests to https://github.com/pnut-api/pnutio-localizations.

Timezones

User timezones the API recognizes are available as a comma-separated text file.