go-mastodon is a comprehensive Go client library for the Mastodon social network API. It provides complete coverage of Mastodon API v1 and v2 endpoints, enabling developers to build applications, bots, and tools that interact with Mastodon instances.
github.com/mattn/go-mastodongo get github.com/mattn/go-mastodonimport (
"context"
"github.com/mattn/go-mastodon"
)package main
import (
"context"
"fmt"
"log"
"github.com/mattn/go-mastodon"
)
func main() {
// Create client configuration
config := &mastodon.Config{
Server: "https://mastodon.social",
ClientID: "your-client-id",
ClientSecret: "your-client-secret",
AccessToken: "your-access-token",
}
// Create client
client := mastodon.NewClient(config)
ctx := context.Background()
// Get current user's account
account, err := client.GetAccountCurrentUser(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Logged in as: %s\n", account.Username)
// Post a status
status, err := client.PostStatus(ctx, &mastodon.Toot{
Status: "Hello from go-mastodon!",
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Posted status: %s\n", status.URL)
}go-mastodon is built around a central Client type that provides methods for all API operations. All methods:
context.Context as the first parameter for cancellation and timeoutsPagination structID, Unixtime, etc.)The library provides two streaming implementations:
StreamingUser, StreamingPublic, etc.WSClient and StreamingWSUser, StreamingWSPublic, etc.Register applications, obtain access tokens, and authenticate users using multiple methods: app credentials, user credentials, or OAuth flow.
func RegisterApp(ctx context.Context, appConfig *AppConfig) (*Application, error)
func (c *Client) GetAppAccessToken(ctx context.Context, redirectURI string) error
func (c *Client) GetUserAccessToken(ctx context.Context, authCode string, redirectURI string) error
func (c *Client) VerifyAppCredentials(ctx context.Context) (*ApplicationVerification, error)Manage user accounts, relationships, and social connections including following, blocking, muting, and searching for accounts.
func (c *Client) GetAccount(ctx context.Context, id ID) (*Account, error)
func (c *Client) GetAccountCurrentUser(ctx context.Context) (*Account, error)
func (c *Client) AccountFollow(ctx context.Context, id ID) (*Relationship, error)
func (c *Client) AccountUnfollow(ctx context.Context, id ID) (*Relationship, error)
func (c *Client) AccountBlock(ctx context.Context, id ID) (*Relationship, error)
func (c *Client) AccountMute(ctx context.Context, id ID) (*Relationship, error)
func (c *Client) AccountsSearch(ctx context.Context, q string, limit int64) ([]*Account, error)Create, edit, delete, and interact with statuses (toots) including reblogging, favouriting, and bookmarking.
func (c *Client) PostStatus(ctx context.Context, toot *Toot) (*Status, error)
func (c *Client) UpdateStatus(ctx context.Context, toot *Toot, id ID) (*Status, error)
func (c *Client) DeleteStatus(ctx context.Context, id ID) error
func (c *Client) Reblog(ctx context.Context, id ID) (*Status, error)
func (c *Client) Favourite(ctx context.Context, id ID) (*Status, error)
func (c *Client) Bookmark(ctx context.Context, id ID) (*Status, error)Retrieve various timelines including home, public, hashtag, list, and direct message timelines.
func (c *Client) GetTimelineHome(ctx context.Context, pg *Pagination) ([]*Status, error)
func (c *Client) GetTimelinePublic(ctx context.Context, isLocal bool, pg *Pagination) ([]*Status, error)
func (c *Client) GetTimelineHashtag(ctx context.Context, tag string, isLocal bool, pg *Pagination) ([]*Status, error)
func (c *Client) GetTimelineList(ctx context.Context, id ID, pg *Pagination) ([]*Status, error)Upload media files for use in statuses from various sources including files, byte slices, and io.Readers.
func (c *Client) UploadMedia(ctx context.Context, file string) (*Attachment, error)
func (c *Client) UploadMediaFromBytes(ctx context.Context, b []byte) (*Attachment, error)
func (c *Client) UploadMediaFromReader(ctx context.Context, reader io.Reader) (*Attachment, error)
func (c *Client) UploadMediaFromMedia(ctx context.Context, media *Media) (*Attachment, error)Access and manage notifications, including push subscription configuration for real-time alerts.
func (c *Client) GetNotifications(ctx context.Context, pg *Pagination) ([]*Notification, error)
func (c *Client) DismissNotification(ctx context.Context, id ID) error
func (c *Client) ClearNotifications(ctx context.Context) error
func (c *Client) AddPushSubscription(ctx context.Context, endpoint string, public ecdsa.PublicKey, shared []byte, alerts PushAlerts) (*PushSubscription, error)Stream real-time updates using HTTP or WebSocket connections for timelines and notifications.
// HTTP Streaming
func (c *Client) StreamingUser(ctx context.Context) (chan Event, error)
func (c *Client) StreamingPublic(ctx context.Context, isLocal bool) (chan Event, error)
func (c *Client) StreamingHashtag(ctx context.Context, tag string, isLocal bool) (chan Event, error)
// WebSocket Streaming
func (c *Client) NewWSClient() *WSClient
func (c *WSClient) StreamingWSUser(ctx context.Context) (chan Event, error)
func (c *WSClient) StreamingWSPublic(ctx context.Context, isLocal bool) (chan Event, error)Create, manage, and organize custom lists of accounts for curated timelines.
func (c *Client) GetLists(ctx context.Context) ([]*List, error)
func (c *Client) CreateList(ctx context.Context, title string) (*List, error)
func (c *Client) AddToList(ctx context.Context, list ID, accounts ...ID) error
func (c *Client) RemoveFromList(ctx context.Context, list ID, accounts ...ID) errorCreate and manage content filters to hide unwanted content from timelines.
func (c *Client) GetFilters(ctx context.Context) ([]*Filter, error)
func (c *Client) CreateFilter(ctx context.Context, filter *Filter) (*Filter, error)
func (c *Client) UpdateFilter(ctx context.Context, id ID, filter *Filter) (*Filter, error)
func (c *Client) DeleteFilter(ctx context.Context, id ID) errorCreate polls in statuses and allow users to vote on existing polls.
func (c *Client) GetPoll(ctx context.Context, id ID) (*Poll, error)
func (c *Client) PollVote(ctx context.Context, id ID, choices ...int) (*Poll, error)Follow hashtags, retrieve hashtag information, and manage followed tags.
func (c *Client) TagInfo(ctx context.Context, tag string) (*FollowedTag, error)
func (c *Client) TagFollow(ctx context.Context, tag string) (*FollowedTag, error)
func (c *Client) TagUnfollow(ctx context.Context, ID string) (*FollowedTag, error)
func (c *Client) TagsFollowed(ctx context.Context, pg *Pagination) ([]*FollowedTag, error)Retrieve information about Mastodon instances including configuration, statistics, and federated peers.
func (c *Client) GetInstance(ctx context.Context) (*Instance, error)
func (c *Client) GetInstanceActivity(ctx context.Context) ([]*WeeklyActivity, error)
func (c *Client) GetInstancePeers(ctx context.Context) ([]string, error)Manage direct message conversations including marking as read and deletion.
func (c *Client) GetConversations(ctx context.Context, pg *Pagination) ([]*Conversation, error)
func (c *Client) MarkConversationAsRead(ctx context.Context, id ID) error
func (c *Client) DeleteConversation(ctx context.Context, id ID) errorFile reports for problematic content or accounts.
func (c *Client) Report(ctx context.Context, accountID ID, ids []ID, comment string) (*Report, error)
func (c *Client) GetReports(ctx context.Context) ([]*Report, error)Search for accounts, statuses, and hashtags across the Mastodon network.
func (c *Client) Search(ctx context.Context, q string, resolve bool) (*Results, error)Core types used throughout the API for identification, pagination, and data representation.