@spec accept_follow_request(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Relationship.t()

Accepts a follow request

Parameters

• conn - connection credentials
• id - follow request id

@spec accept_notification_request(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  boolean()

Accept a notification request, so future notifications from the account are delivered normally

Parameters

• conn - connection credentials
• id - notification request identifier

@spec accept_notification_requests(Hunter.Client.t(), [String.t() | non_neg_integer()]) ::
  boolean()

Accept multiple notification requests

Parameters

• conn - connection credentials
• ids - notification request identifiers

@spec account(Hunter.Client.t(), String.t() | non_neg_integer()) :: Hunter.Account.t()

Retrieve account

Parameters

• conn - connection credentials
• id - account identifier

@spec account_endorsements(
  Hunter.Client.t(),
  String.t() | non_neg_integer(),
  Keyword.t()
) :: [
  Hunter.Account.t()
]

Retrieve the accounts a given account is featuring on their profile

Parameters

• conn - connection credentials
• id - account identifier
• options - option list

Options

• max_id - get a list of endorsements with id less than or equal this value
• since_id - get a list of endorsements with id greater than this value
• limit - maximum number of endorsements to get

@spec account_featured_tags(Hunter.Client.t(), String.t() | non_neg_integer()) :: [
  Hunter.FeaturedTag.t()
]

Retrieve the hashtags an account is featuring on their profile

Parameters

• conn - connection credentials
• id - account identifier

@spec account_lists(Hunter.Client.t(), String.t() | non_neg_integer()) :: [
  Hunter.List.t()
]

Retrieve the user's lists that contain a given account

Parameters

• conn - connection credentials
• account_id - account identifier

@spec accounts_by_ids(Hunter.Client.t(), [String.t() | non_neg_integer()]) :: [
  Hunter.Account.t()
]

Retrieve multiple accounts by id

Parameters

• conn - connection credentials
• ids - list of account identifiers

@spec add_accounts_to_list(Hunter.Client.t(), String.t() | non_neg_integer(), [
  String.t() | non_neg_integer()
]) :: boolean()

Add accounts to a list; the user must be following each of them

Parameters

• conn - connection credentials
• id - list identifier
• account_ids - account identifiers to add

@spec add_keyword_to_filter(
  Hunter.Client.t(),
  String.t() | non_neg_integer(),
  String.t(),
  Keyword.t()
) :: Hunter.FilterKeyword.t()

Add a keyword to a filter

Parameters

• conn - connection credentials
• filter_id - filter identifier
• keyword - the phrase to be matched against
• options - option list

Options

• whole_word - whether the keyword should consider word boundaries

@spec add_status_to_filter(
  Hunter.Client.t(),
  String.t() | non_neg_integer(),
  String.t() | non_neg_integer()
) :: Hunter.FilterStatus.t()

Add a status to a filter group

Parameters

• conn - connection credentials
• filter_id - filter identifier
• status_id - status identifier

@spec authorization_url(Hunter.Application.t(), String.t(), Keyword.t()) :: String.t()

Build the URL to send the user to for authorization (GET /oauth/authorize)

Parameters

• app - application details, see: Hunter.create_app/5
• base_url - API base url, default: https://mastodon.social
• opts - optional params

Options

• redirect_uri - overrides the app's registered redirect URI
• scope - space-separated scopes, defaults to the app's scopes
• code_challenge / code_challenge_method - PKCE params, see generate_pkce/0
• state - opaque value returned to your redirect URI unchanged
• force_login - forces re-login when true
• lang - ISO 639-1 language code for the authorization form

Builds a URL only; performs no request.

@spec block(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Relationship.t()

Block a user

Parameters

• conn - connection credentials
• id - user identifier

@spec block_domain(Hunter.Client.t(), String.t()) :: boolean()

Block a domain

Parameters

• conn - connection credentials
• domain - domain to block

@spec blocked_domains(Hunter.Client.t(), Keyword.t()) :: [String.t()]

Fetch user's blocked domains

Parameters

• conn - connection credentials
• options - option list

Options

• max_id - get a list of blocks with id less than or equal this value
• since_id - get a list of blocks with id greater than this value
• limit - maximum number of blocks to get, default: 40, max: 80

@spec blocks(Hunter.Client.t(), Keyword.t()) :: [Hunter.Account.t()]

Retrieve user's blocks

Parameters

• conn - connection credentials

Options

• max_id - get a list of blocks with id less than or equal this value
• since_id - get a list of blocks with id greater than this value
• limit - maximum number of blocks to get, default: 40, max: 80

@spec bookmark(Hunter.Client.t(), String.t() | non_neg_integer()) :: Hunter.Status.t()

Bookmark a status

Parameters

• conn - connection credentials
• id - status identifier

@spec bookmarks(Hunter.Client.t(), Keyword.t()) :: [Hunter.Status.t()]

Fetch the user's bookmarked statuses

Parameters

• conn - connection credentials
• options - option list

Options

• max_id - get a list of bookmarks with id less than or equal this value
• since_id - get a list of bookmarks with id greater than this value
• min_id - get a list of bookmarks with id greater than this value, immediately newer
• limit - maximum number of bookmarks to get, default: 20, max: 40

@spec clear_notification(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  boolean()

Dismiss a single notification

Parameters

• conn - connection credentials
• id - notification id

@spec clear_notifications(Hunter.Client.t()) :: boolean()

Deletes all notifications from the Mastodon server for the authenticated user

Parameters

• conn - connection credentials

@spec create_app(
  String.t(),
  String.t() | [String.t()],
  [String.t()],
  nil | String.t(),
  Keyword.t()
) :: Hunter.Application.t() | no_return()

Register a new OAuth client app on the target instance

Parameters

• name - name of your application
• redirect_uris - where the user should be redirected after authorization; a single URI or a list of URIs (Mastodon 4.3+), default: urn:ietf:wg:oauth:2.0:oob (no redirect)
• scopes - scope list, see the scope section for more details, default: read
• website - URL to the homepage of your app, default: nil
• options - option list

Scopes

• read - read data
• write - post statuses and upload media for statuses
• follow - follow, unfollow, block, unblock

Multiple scopes can be requested during the authorization phase with the scope query param

Options

• save? - persists your application information to a file, so, you can use them later. default: false
• api_base_url - specifies if you want to register an application on a different instance. default: https://mastodon.social

Examples

iex> Hunter.create_app("hunter", "urn:ietf:wg:oauth:2.0:oob", ["read", "write", "follow"], nil, [save?: true, api_base_url: "https://example.com"])
%Hunter.Application{client_id: "1234567890",
 client_secret: "1234567890",
 id: "1234"}

@spec create_filter(Hunter.Client.t(), String.t(), [String.t()], Keyword.t()) ::
  Hunter.Filter.t()

Create a new filter

Parameters

• conn - connection credentials
• title - the name of the filter group
• context - contexts in which the filter is applied, list of: home, notifications, public, thread, account
• options - option list

Options

• filter_action - action to take when a status matches the filter, one of: warn, hide, blur; default: warn
• expires_in - seconds from now the filter should expire, nil to never expire
• keywords_attributes - list of maps with keyword and whole_word keys, the keywords to add to the newly-created filter

@spec create_list(Hunter.Client.t(), String.t(), Keyword.t()) :: Hunter.List.t()

Create a new list

Parameters

• conn - connection credentials
• title - the title of the list
• options - option list

Options

• replies_policy - which replies should be shown in the list, one of: followed, list, none; default: list
• exclusive - whether members of the list are removed from the home timeline

@spec create_push_subscription(Hunter.Client.t(), map(), map()) ::
  Hunter.WebPushSubscription.t()

Subscribe to Web Push notifications; each access token can have exactly one subscription, and creating a new one replaces it

Parameters

• conn - connection credentials
• subscription - map with endpoint, keys (p256dh and auth) and optionally standard
• data - optional map with alerts and policy

@spec create_status(Hunter.Client.t(), String.t(), Keyword.t()) ::
  Hunter.Status.t() | Hunter.ScheduledStatus.t() | no_return()

Create new status

Parameters

• conn - connection credentials
• status - text of the status
• options - option list

Options

• in_reply_to_id - local ID of the status you want to reply to
• media_ids - list of media IDs to attach to the status (maximum: 4)
• sensitive - whether the media of the status is NSFW
• spoiler_text - text to be shown as a warning before the actual content
• visibility - either direct, private, unlisted or public
• language - ISO 639-1 language code for the status
• poll - map with options (list of choices) and expires_in (seconds); optional: multiple, hide_totals
• quoted_status_id - ID of a status to quote
• scheduled_at - ISO 8601 datetime (at least 5 minutes ahead) at which the status should be published; the call returns a Hunter.ScheduledStatus instead of a Hunter.Status
• idempotency_key - unique string sent as the Idempotency-Key header to prevent duplicate submissions

@spec delete_media(Hunter.Client.t(), String.t() | non_neg_integer()) :: boolean()

Delete a media attachment that is not currently attached to a status

Parameters

• conn - connection credentials
• id - attachment identifier

@spec delete_push_subscription(Hunter.Client.t()) :: boolean()

Remove the Web Push subscription tied to the access token

Parameters

• conn - connection credentials

@spec destroy_filter(Hunter.Client.t(), String.t() | non_neg_integer()) :: boolean()

Delete a filter

Parameters

• conn - connection credentials
• id - filter identifier

@spec destroy_filter_keyword(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  boolean()

Remove a keyword from a filter

Parameters

• conn - connection credentials
• id - filter keyword identifier

@spec destroy_filter_status(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  boolean()

Remove a status from a filter group

Parameters

• conn - connection credentials
• id - status filter identifier

@spec destroy_list(Hunter.Client.t(), String.t() | non_neg_integer()) :: boolean()

Delete a list

Parameters

• conn - connection credentials
• id - list identifier

@spec destroy_status(Hunter.Client.t(), String.t() | non_neg_integer()) :: boolean()

Destroy status

Parameters

• conn - connection credentials
• id - status identifier

@spec dismiss_notification_group(Hunter.Client.t(), String.t()) :: boolean()

Dismiss a notification group

Parameters

• conn - connection credentials
• group_key - notification group key

@spec dismiss_notification_request(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  boolean()

Dismiss a notification request, removing it and its filtered notifications

Parameters

• conn - connection credentials
• id - notification request identifier

@spec dismiss_notification_requests(Hunter.Client.t(), [
  String.t() | non_neg_integer()
]) :: boolean()

Dismiss multiple notification requests, removing them and their filtered notifications

Parameters

• conn - connection credentials
• ids - notification request identifiers

@spec edit_status(
  Hunter.Client.t(),
  String.t() | non_neg_integer(),
  String.t(),
  Keyword.t()
) ::
  Hunter.Status.t() | no_return()

Edit a status

Parameters

• conn - connection credentials
• id - status identifier
• status - the new text of the status
• options - option list

Options

• spoiler_text - text to be shown as a warning before the actual content
• sensitive - whether the media of the status is NSFW
• language - ISO 639-1 language code for the status
• media_ids - list of media IDs to attach to the status
• poll - map with options (list of choices) and expires_in (seconds); replaces the current poll

@spec endorse(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Relationship.t()

Feature an account on your profile

Parameters

• conn - connection credentials
• id - account identifier

@spec endorsements(Hunter.Client.t(), Keyword.t()) :: [Hunter.Account.t()]

Retrieve the accounts you are featuring on your profile

Parameters

• conn - connection credentials
• options - option list

Options

• max_id - get a list of endorsements with id less than or equal this value
• since_id - get a list of endorsements with id greater than this value
• limit - maximum number of endorsements to get

@spec familiar_followers(Hunter.Client.t(), [String.t() | non_neg_integer()]) :: [
  Hunter.FamiliarFollowers.t()
]

Find out which of the accounts you follow also follow the given accounts

Parameters

• conn - connection credentials
• ids - list of account identifiers

@spec favourite(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Status.t()

Favorite a status

Parameters

• conn - connection credentials
• id - status identifier

@spec favourited_by(Hunter.Client.t(), String.t() | non_neg_integer(), Keyword.t()) ::
  [
    Hunter.Account.t()
  ]

Fetch the list of users who favourited the status

Parameters

• conn - connection credentials
• id - status identifier
• options - option list

Options

• max_id - get a list of favourited by ids less than or equal this value
• since_id - get a list of favourited by ids greater than this value
• limit - maximum number of favourited by to get, default: 40, max: 80

@spec favourites(Hunter.Client.t(), Keyword.t()) :: [Hunter.Status.t()]

Fetch a user's favourites

Parameters

• conn - connection credentials
• options - option list

Options

• max_id - get a list of favourites with id less than or equal this value
• since_id - get a list of favourites with id greater than this value
• limit - maximum of favourites to get, default: 20, max: 40

@spec filter(Hunter.Client.t(), String.t() | non_neg_integer()) :: Hunter.Filter.t()

Retrieve a filter

Parameters

• conn - connection credentials
• id - filter identifier

@spec filter_keyword(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.FilterKeyword.t()

Retrieve a filter keyword

Parameters

• conn - connection credentials
• id - filter keyword identifier

@spec filter_keywords(Hunter.Client.t(), String.t() | non_neg_integer()) :: [
  Hunter.FilterKeyword.t()
]

Retrieve the keywords grouped under a filter

Parameters

• conn - connection credentials
• filter_id - filter identifier

@spec filter_status(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.FilterStatus.t()

Retrieve a status filter

Parameters

• conn - connection credentials
• id - status filter identifier

@spec filter_statuses(Hunter.Client.t(), String.t() | non_neg_integer()) :: [
  Hunter.FilterStatus.t()
]

Retrieve the status filters grouped under a filter

Parameters

• conn - connection credentials
• filter_id - filter identifier

@spec filters(Hunter.Client.t()) :: [Hunter.Filter.t()]

Retrieve all filters the user owns

Parameters

• conn - connection credentials

@spec follow(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Relationship.t()

Follow a user

Parameters

• conn - connection credentials
• id - user identifier

@spec follow_requests(Hunter.Client.t(), Keyword.t()) :: [Hunter.Account.t()]

Retrieve a list of follow requests

Parameters

• conn - connection credentials
• options - option list

Options

• max_id - get a list of follow requests with id less than or equal this value
• since_id - get a list of follow requests with id greater than this value
• limit - maximum number of requests to get, default: 40, max: 80

@spec followers(Hunter.Client.t(), String.t() | non_neg_integer(), Keyword.t()) :: [
  Hunter.Account.t()
]

Get a list of followers

Parameters

• conn - connection credentials
• id - account identifier
• options - options list

Options

• max_id - get a list of followers with id less than or equal this value
• since_id - get a list of followers with id greater than this value
• limit - maximum number of followers to get, default: 40, maximum: 80

Note: max_id and since_id for next and previous pages are provided in the Link header. It is not possible to use the id of the returned objects to construct your own URLs, because the results are sorted by an internal key.

@spec following(Hunter.Client.t(), String.t() | non_neg_integer(), Keyword.t()) :: [
  Hunter.Account.t()
]

Get a list of followed accounts

Parameters

• conn - connection credentials
• id - account identifier
• options - options list

Options

• max_id - get a list of followings with id less than or equal this value
• since_id - get a list of followings with id greater than this value
• limit - maximum number of followings to get, default: 40, maximum: 80

Note: max_id and since_id for next and previous pages are provided in the Link header. It is not possible to use the id of the returned objects to construct your own URLs, because the results are sorted by an internal key.

@spec generate_pkce() :: %{
  code_verifier: String.t(),
  code_challenge: String.t(),
  code_challenge_method: String.t()
}

Generate a PKCE verifier/challenge pair (RFC 7636, S256)

Returns a map with code_verifier, code_challenge and code_challenge_method. Pass the challenge params to authorization_url/3 and the verifier to log_in_oauth/4.

@spec grouped_notifications(Hunter.Client.t(), Keyword.t()) ::
  Hunter.GroupedNotificationsResults.t()

Retrieve grouped notifications, together with the accounts and statuses they reference

Parameters

• conn - connection credentials
• options - option list

Options

• max_id - get groups with id less than or equal this value
• since_id - get groups with id greater than this value
• limit - maximum number of groups to get, default: 40, max: 80
• types - notification types to include
• exclude_types - notification types to exclude
• grouped_types - which types can be grouped together

@spec grouped_unread_count(Hunter.Client.t()) :: non_neg_integer()

Retrieve the number of unread notification groups, capped by the server

Parameters

• conn - connection credentials

@spec hashtag_timeline(Hunter.Client.t(), [String.t()], Keyword.t()) :: [
  Hunter.Status.t()
]

Retrieve statuses from a hashtag

Parameters

• conn - connection credentials
• hashtag - string list
• options - option list

Options

• local - only return statuses originating from this instance
• max_id - get a list of timelines with id less than or equal this value
• since_id - get a list of timelines with id greater than this value
• limit - maximum number of statuses on the requested timeline to get, default: 20, max: 40

@spec home_timeline(Hunter.Client.t(), Keyword.t()) :: [Hunter.Status.t()]

Retrieve statuses from the home timeline

Parameters

• conn - connection credentials
• options - option list

Options

• max_id - get a list of timelines with id less than or equal this value
• since_id - get a list of timelines with id greater than this value
• limit - maximum number of statuses on the requested timeline to get, default: 20, max: 40

@spec instance_info(Hunter.Client.t()) :: Hunter.Instance.t()

Retrieve instance information

Parameters

• conn - connection credentials

Examples

iex> conn = Hunter.new([base_url: "https://social.lou.lt", access_token: "123456"])
%Hunter.Client{base_url: "https://social.lou.lt", access_token: "123456"}
iex> Hunter.instance_info(conn)
%Hunter.Instance{description: "Mostly French  instance - <a href=\"/about/more#rules\">Read full description</a> for rules.",
          domain: "social.lou.lt", title: "Loultstodon", version: "4.3.8"}

@spec list(Hunter.Client.t(), String.t() | non_neg_integer()) :: Hunter.List.t()

Retrieve a list

Parameters

• conn - connection credentials
• id - list identifier

@spec list_accounts(Hunter.Client.t(), String.t() | non_neg_integer(), Keyword.t()) ::
  [
    Hunter.Account.t()
  ]

Retrieve the accounts in a list

Parameters

• conn - connection credentials
• id - list identifier
• options - option list

Options

• max_id - get a list of accounts with id less than or equal this value
• since_id - get a list of accounts with id greater than this value
• limit - maximum number of accounts to get, default: 40; set to 0 to get all accounts in the list

@spec list_timeline(Hunter.Client.t(), String.t() | non_neg_integer(), Keyword.t()) ::
  [
    Hunter.Status.t()
  ]

Retrieve statuses from the given list's timeline

Parameters

• conn - connection credentials
• list_id - list identifier
• options - option list

Options

• max_id - get a list of timelines with id less than or equal this value
• since_id - get a list of timelines with id greater than this value
• limit - maximum number of statuses on the requested timeline to get, default: 20, max: 40

@spec lists(Hunter.Client.t()) :: [Hunter.List.t()]

Retrieve all lists the user owns

Parameters

• conn - connection credentials

@spec load_credentials(String.t()) :: Hunter.Application.t()

Load persisted application's credentials

Parameters

• name - application's name

@spec log_in_app(Hunter.Application.t(), String.t()) :: Hunter.Client.t()

Retrieve an app-level access token via the client-credentials grant

The returned client can call app-scoped endpoints such as verify_app_credentials/1 and register_account/2.

Parameters

• app - application details, see: Hunter.create_app/5 for more details.
• base_url - API base url, default: https://mastodon.social

@spec log_in_oauth(Hunter.Application.t(), String.t(), String.t(), Keyword.t()) ::
  Hunter.Client.t()

Retrieve access token via the OAuth authorization-code flow

Parameters

• app - application details, see: Hunter.create_app/5 for more details.
• oauth_code - authorization code from the redirect (or the out-of-band form)
• base_url - API base url, default: https://mastodon.social
• opts - optional params

Options

• code_verifier - PKCE verifier matching the code_challenge sent to authorization_url/3, see generate_pkce/0
• redirect_uri - must match the URI used on the authorization request; defaults to the app's first registered URI

@spec lookup_account(Hunter.Client.t(), String.t()) :: Hunter.Account.t()

Look up an account by its webfinger address, without requiring a search

Parameters

• conn - connection credentials
• acct - the username or webfinger address (e.g. user@domain) to look up

@spec media_attachment(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Attachment.t()

Retrieve a media attachment, to check the processing status of an asynchronous upload

Parameters

• conn - connection credentials
• id - attachment identifier

@spec mute(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Relationship.t()

Mute a user

Parameters

• conn - connection credentials
• id - user identifier

@spec mute_conversation(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Status.t()

Mute a conversation, so its thread stops generating notifications

Parameters

• conn - connection credentials
• id - status identifier

@spec mutes(Hunter.Client.t(), Keyword.t()) :: [Hunter.Account.t()]

Retrieve user's mutes

Parameters

• conn - connection credentials
• options - option list

Options

• max_id - get a list of mutes with id less than or equal this value
• since_id - get a list of mutes with id greater than this value
• limit - maximum number of mutes to get, default: 40, max: 80

@spec new(Keyword.t()) :: Hunter.Client.t()

Initializes a client

Options

• base_url - URL of the instance you want to connect to
• access_token - [String] OAuth access token for your authenticated user

@spec notification(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Notification.t()

Retrieve single notification

Parameters

• conn - connection credentials
• id - notification identifier

Examples

Hunter.notification(conn, 17_476)
#=> %Hunter.Notification{account: %{"acct" => "paperswelove@mstdn.io", ...}

@spec notification_group(Hunter.Client.t(), String.t()) ::
  Hunter.GroupedNotificationsResults.t()

Retrieve a single notification group by its group key

Parameters

• conn - connection credentials
• group_key - notification group key

@spec notification_group_accounts(Hunter.Client.t(), String.t()) :: [
  Hunter.Account.t()
]

Retrieve the accounts of all notifications in a notification group

Parameters

• conn - connection credentials
• group_key - notification group key

@spec notification_policy(Hunter.Client.t()) :: Hunter.NotificationPolicy.t()

Retrieve the notification filtering policy for the user

Parameters

• conn - connection credentials

@spec notification_request(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.NotificationRequest.t()

Retrieve a single notification request

Parameters

• conn - connection credentials
• id - notification request identifier

@spec notification_requests(Hunter.Client.t(), Keyword.t()) :: [
  Hunter.NotificationRequest.t()
]

Retrieve notification requests (groups of filtered notifications)

Parameters

• conn - connection credentials
• options - option list

Options

• max_id - get requests with id less than or equal this value
• since_id - get requests with id greater than this value
• limit - maximum number of requests to get, default: 40, max: 80

@spec notification_requests_merged?(Hunter.Client.t()) :: boolean()

Check whether accepted notification requests have been merged

Parameters

• conn - connection credentials

@spec notifications(Hunter.Client.t(), Keyword.t()) :: [Hunter.Notification.t()]

Retrieve user's notifications

Parameters

• conn - connection credentials
• options - option list

Options

• max_id - get a list of notifications with id less than or equal this value
• since_id - get a list of notifications with id greater than this value
• limit - maximum number of notifications to get, default: 15, max: 30

Examples

Hunter.notifications(conn)
#=> [%Hunter.Notification{account: %{"acct" => "paperswelove@mstdn.io", ...}]

@spec oauth_server_metadata(String.t()) :: map()

Fetch the instance's OAuth server metadata (RFC 8414)

Use this to discover supported scopes, grant types and endpoints instead of hardcoding them. Available since Mastodon 4.3. Does not require authentication.

Parameters

• base_url - API base url, default: https://mastodon.social

Returns the decoded metadata map ("issuer", "authorization_endpoint", "token_endpoint", "scopes_supported", "code_challenge_methods_supported", ...).

@spec pin(Hunter.Client.t(), String.t() | non_neg_integer()) :: Hunter.Status.t()

Pin a status to the top of the user's profile

Parameters

• conn - connection credentials
• id - status identifier

@spec poll(Hunter.Client.t(), String.t() | non_neg_integer()) :: Hunter.Poll.t()

Retrieve a poll

Parameters

• conn - connection credentials
• id - poll identifier

@spec public_timeline(Hunter.Client.t(), Keyword.t()) :: [Hunter.Status.t()]

Retrieve statuses from the public timeline

Parameters

• conn - connection credentials
• options - option list

Options

• local - only return statuses originating from this instance
• max_id - get a list of timelines with id less than or equal this value
• since_id - get a list of timelines with id greater than this value
• limit - maximum number of statuses on the requested timeline to get, default: 20, max: 40

@spec push_subscription(Hunter.Client.t()) :: Hunter.WebPushSubscription.t()

Retrieve the Web Push subscription tied to the access token

Parameters

• conn - connection credentials

@spec reblog(Hunter.Client.t(), String.t() | non_neg_integer()) :: Hunter.Status.t()

Reblog a status

Parameters

• conn - connection credentials
• id - status identifier

@spec reblogged_by(Hunter.Client.t(), String.t() | non_neg_integer(), Keyword.t()) ::
  [
    Hunter.Account.t()
  ]

Fetch the list of users who reblogged the status.

Parameters

• conn - connection credentials
• id - status identifier
• options - option list

Options

• max_id - get a list of reblogged by ids less than or equal this value
• since_id - get a list of reblogged by ids greater than this value
• limit - maximum number of reblogged by to get, default: 40, max: 80

@spec register_account(Hunter.Client.t(), map()) :: Hunter.Client.t()

Register a new account and obtain its access token

The given client must carry an app-level access token (from the OAuth client-credentials flow); returns a new Hunter.Client holding the created user's access token.

Parameters

• conn - connection credentials with the app-level access token
• params - registration params

Possible keys for params

• username - desired username
• email - the account owner's email address
• password - the account password
• agreement - whether the user agrees to the server rules and terms (must be true)
• locale - the language of the confirmation email (e.g. "en")
• reason - (optional) why you want to join, when registrations require approval

@spec reject_follow_request(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Relationship.t()

Rejects a follow request

Parameters

• conn - connection credentials
• id - follow request id

@spec relationships(Hunter.Client.t(), [String.t() | non_neg_integer()]) :: [
  Hunter.Relationship.t()
]

Get the relationships of authenticated user towards given other users

Parameters

• conn - connection credentials
• id - list of relationship IDs

@spec remove_accounts_from_list(Hunter.Client.t(), String.t() | non_neg_integer(), [
  String.t() | non_neg_integer()
]) :: boolean()

Remove accounts from a list

Parameters

• conn - connection credentials
• id - list identifier
• account_ids - account identifiers to remove

@spec remove_from_followers(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Relationship.t()

Remove an account from your followers

Parameters

• conn - connection credentials
• id - account identifier

@spec report(
  Hunter.Client.t(),
  String.t() | non_neg_integer(),
  [String.t() | non_neg_integer()],
  String.t()
) :: Hunter.Report.t()

Report a user

Parameters

• conn - connection credentials
• account_id - the ID of the account to report
• status_ids - the IDs of statuses to report
• comment - a comment to associate with the report

@spec revoke_token(Hunter.Application.t(), String.t(), String.t()) :: true

Revoke an access token

Parameters

• app - application details (must be the client the token was issued to), see: Hunter.create_app/5
• token - the access token to revoke
• base_url - API base url, default: https://mastodon.social

Returns true on success. Raises Hunter.Error if the token does not belong to the given client.

@spec search(Hunter.Client.t(), String.t(), Keyword.t()) :: Hunter.Result.t()

Search for content

Parameters

• conn - connection credentials
• q - the search query, if q is a URL Mastodon will attempt to fetch the provided account or status, otherwise it will do a local account and hashtag search
• options - option list

Options

• resolve - whether to resolve non-local accounts

@spec search_account(Hunter.Client.t(), Keyword.t()) :: [Hunter.Account.t()]

Search for accounts

Parameters

• conn - connection credentials
• options - option list

Options

• q: what to search for
• limit: maximum number of matching accounts to return, default: 40

@spec set_account_note(Hunter.Client.t(), String.t() | non_neg_integer(), String.t()) ::
  Hunter.Relationship.t()

Set a private note on an account

Parameters

• conn - connection credentials
• id - account identifier
• comment - the note text; pass an empty string to clear the note

@spec status(Hunter.Client.t(), String.t() | non_neg_integer()) :: Hunter.Status.t()

Retrieve status

Parameters

• conn - connection credentials
• id - status identifier

@spec status_context(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Context.t()

Retrieve status context

Parameters

• conn - connection credentials
• id - status identifier

@spec status_history(Hunter.Client.t(), String.t() | non_neg_integer()) :: [
  Hunter.StatusEdit.t()
]

Retrieve the edit history of a status

Parameters

• conn - connection credentials
• id - status identifier

@spec status_source(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.StatusSource.t()

Retrieve the plain-text source of a status, for editing

Parameters

• conn - connection credentials
• id - status identifier

@spec statuses(Hunter.Client.t(), String.t() | non_neg_integer(), Keyword.t()) :: [
  Hunter.Status.t()
]

Get a list of statuses by a user

Parameters

• conn - connection credentials -
• account_id - account identifier
• options - option list

Options

• only_media - only return Hunter.Status.t that have media attachments
• exclude_replies - skip statuses that reply to other statuses
• max_id - get a list of statuses with id less than or equal this value
• since_id - get a list of statuses with id greater than this value
• limit - maximum number of statuses to get, default: 20, max: 40

@spec statuses_by_ids(Hunter.Client.t(), [String.t() | non_neg_integer()]) :: [
  Hunter.Status.t()
]

Retrieve multiple statuses by id

Parameters

• conn - connection credentials
• ids - list of status identifiers

@spec streaming_health?(Hunter.Client.t(), Keyword.t()) :: boolean()

Checks the streaming server's health endpoint (Mastodon 2.5+)

Parameters

• conn - connection credentials
• opts - url: overrides the streaming base URL (ws:///wss:// accepted and mapped to http:///https://)

See Hunter.Streaming.health?/2; streaming connections themselves are opened with Hunter.Streaming.connect/2.

@spec translate_status(Hunter.Client.t(), String.t() | non_neg_integer(), Keyword.t()) ::
  Hunter.Translation.t()

Translate a status into some language

Parameters

• conn - connection credentials
• id - status identifier
• options - option list

Options

• lang - ISO 639-1 language code the status should be translated into; defaults to the user's current locale

@spec unblock(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Relationship.t()

Unblock a user

• conn - connection credentials
• id - user identifier

@spec unblock_domain(Hunter.Client.t(), String.t()) :: boolean()

Unblock a domain

Parameters

• conn - connection credentials
• domain - domain to unblock

@spec unbookmark(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Status.t()

Remove a status from bookmarks

Parameters

• conn - connection credentials
• id - status identifier

@spec unendorse(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Relationship.t()

Stop featuring an account on your profile

Parameters

• conn - connection credentials
• id - account identifier

@spec unfavourite(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Status.t()

Undo a favorite of a status

Parameters

• conn - connection credentials
• id - status identifier

@spec unfollow(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Relationship.t()

Unfollow a user

Parameters

• conn - connection credentials
• id - user identifier

@spec unmute(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Relationship.t()

Unmute a user

Parameters

• conn - connection credentials
• id - user identifier

@spec unmute_conversation(Hunter.Client.t(), String.t() | non_neg_integer()) ::
  Hunter.Status.t()

Unmute a conversation

Parameters

• conn - connection credentials
• id - status identifier

@spec unpin(Hunter.Client.t(), String.t() | non_neg_integer()) :: Hunter.Status.t()

Unpin a status from the user's profile

Parameters

• conn - connection credentials
• id - status identifier

@spec unread_count(Hunter.Client.t()) :: non_neg_integer()

Retrieve the number of unread notifications, capped by the server

Parameters

• conn - connection credentials

@spec unreblog(Hunter.Client.t(), String.t() | non_neg_integer()) :: Hunter.Status.t()

Undo a reblog of a status

Parameters

• conn - connection credentials
• id - status identifier

@spec update_credentials(Hunter.Client.t(), map()) :: Hunter.Account.t()

Make changes to the authenticated user

Parameters

• conn - connection credentials
• data - data payload

Possible keys for payload

• display_name - name to display in the user's profile
• note - new biography for the user
• avatar - base64 encoded image to display as the user's avatar (e.g. data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...)
• header - base64 encoded image to display as the user's header image (e.g. data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAUoAAADrCAYAAAA...)

@spec update_filter(Hunter.Client.t(), String.t() | non_neg_integer(), Keyword.t()) ::
  Hunter.Filter.t()

Update a filter

Parameters

• conn - connection credentials
• id - filter identifier
• options - option list

Options

• title - the new name of the filter group
• context - contexts in which the filter is applied, list of: home, notifications, public, thread, account
• filter_action - action to take when a status matches the filter, one of: warn, hide, blur
• expires_in - seconds from now the filter should expire, nil to never expire
• keywords_attributes - list of maps with keyword, whole_word, id and _destroy keys, keywords to add, update or remove in place

@spec update_filter_keyword(
  Hunter.Client.t(),
  String.t() | non_neg_integer(),
  Keyword.t()
) ::
  Hunter.FilterKeyword.t()

Update a filter keyword

Parameters

• conn - connection credentials
• id - filter keyword identifier
• options - option list

Options

• keyword - the phrase to be matched against
• whole_word - whether the keyword should consider word boundaries

@spec update_list(Hunter.Client.t(), String.t() | non_neg_integer(), Keyword.t()) ::
  Hunter.List.t()

Update a list

Parameters

• conn - connection credentials
• id - list identifier
• options - option list

Options

• title - the new title of the list
• replies_policy - which replies should be shown in the list, one of: followed, list, none
• exclusive - whether members of the list are removed from the home timeline

@spec update_media(Hunter.Client.t(), String.t() | non_neg_integer(), Keyword.t()) ::
  Hunter.Attachment.t()

Update a media attachment, before it is attached to a status

Parameters

• conn - connection credentials
• id - attachment identifier
• options - option list

Options

• description - plain-text description of the media for accessibility
• focus - two floating points between -1.0 and 1.0, comma-delimited
• thumbnail - path of a custom thumbnail image

@spec update_notification_policy(Hunter.Client.t(), Keyword.t()) ::
  Hunter.NotificationPolicy.t()

Update the notification filtering policy for the user

Parameters

• conn - connection credentials
• options - option list

Options

Each takes one of accept, filter or drop:

• for_not_following
• for_not_followers
• for_new_accounts
• for_private_mentions
• for_limited_accounts

@spec update_push_subscription(Hunter.Client.t(), map()) ::
  Hunter.WebPushSubscription.t()

Update the data portion of the Web Push subscription

Parameters

• conn - connection credentials
• data - map with alerts and/or policy

@spec upload_media(Hunter.Client.t(), Path.t(), Keyword.t()) :: Hunter.Attachment.t()

Upload a media file

Parameters

• conn - connection credentials
• file - media to be uploaded
• options - option list

Options

• description - plain-text description of the media for accessibility (max 420 chars)
• focus - two floating points, comma-delimited

Note: the v2 media endpoint processes large files asynchronously: the returned attachment's url may be nil until the server finishes processing (HTTP 202). The id can be attached to a status with create_status as soon as processing completes.

@spec user_agent() :: String.t()

User agent of the client

@spec userinfo(Hunter.Client.t()) :: map()

Fetch OIDC-style claims about the authenticated user

Available since Mastodon 4.4; the token must carry the profile (or read) scope.

Parameters

• conn - connection credentials

Returns the decoded claims map ("iss", "sub", "name", "preferred_username", ...).

@spec verify_app_credentials(Hunter.Client.t()) :: Hunter.Application.t()

Confirm that the app-level token works

Parameters

• conn - connection credentials holding an app-level access token, see log_in_app/2

Returns the Hunter.Application as the server sees it (never includes client_secret; includes scopes and redirect_uris since Mastodon 4.3).

@spec verify_credentials(Hunter.Client.t()) :: Hunter.Account.t()

Retrieve account of authenticated user

Parameters

• conn - connection credentials

Examples

  iex> conn = Hunter.new([base_url: "https://social.lou.lt", access_token: "123456"])
  %Hunter.Client{base_url: "https://social.lou.lt", access_token: "123456"}
  iex> Hunter.verify_credentials(conn)
  %Hunter.Account{acct: "milmazz",
          avatar: "https://social.lou.lt/avatars/original/missing.png",
          avatar_static: "https://social.lou.lt/avatars/original/missing.png",
          created_at: "2017-04-06T17:43:55.325Z",
          display_name: "Milton Mazzarri", followers_count: 4,
          following_count: 4,
          header: "https://social.lou.lt/headers/original/missing.png",
          header_static: "https://social.lou.lt/headers/original/missing.png",
          id: "8039", locked: false, note: "", statuses_count: 3,
          url: "https://social.lou.lt/@milmazz", username: "milmazz"}

@spec version() :: String.t()

Returns Hunter version

@spec vote(Hunter.Client.t(), String.t() | non_neg_integer(), [non_neg_integer()]) ::
  Hunter.Poll.t()

Vote on one or more options in a poll

Parameters

• conn - connection credentials
• id - poll identifier
• choices - list of option indices to vote for (zero-based); multiple choices are only allowed on multiple-choice polls