tessl/golang-go-mastodon
Go client library for Mastodon API with complete coverage of v1 and v2 endpoints
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
To install, run
npx @tessl/cli install tessl/golang-go-mastodon@0.0.0index.mddocs/
go-mastodon
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.
Package Information
- Package Name: go-mastodon
- Package Type: Go module
- Language: Go
- Module Path:
github.com/mattn/go-mastodon - Installation:
go get github.com/mattn/go-mastodon - Go Version: Requires Go 1.23+
Core Imports
import (
"context"
"github.com/mattn/go-mastodon"
)Basic Usage
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)
}Architecture
go-mastodon is built around a central Client type that provides methods for all API operations. All methods:
- Accept
context.Contextas the first parameter for cancellation and timeouts - Return pointers to structs for API responses
- Support pagination through the
Paginationstruct - Use strongly-typed custom types (
ID,Unixtime, etc.)
The library provides two streaming implementations:
- HTTP streaming via
StreamingUser,StreamingPublic, etc. - WebSocket streaming via
WSClientandStreamingWSUser,StreamingWSPublic, etc.
Capabilities
Authentication
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)Account Management
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)Status Operations
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)Timelines
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)Media Attachments
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)Notifications
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)Real-time Streaming
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)List Management
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) errorContent Filters
Create 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) errorPolls
Create 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)Hashtag Operations
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)Instance Information
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)Conversations
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) errorReporting
File 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
Search for accounts, statuses, and hashtags across the Mastodon network.
func (c *Client) Search(ctx context.Context, q string, resolve bool) (*Results, error)Common Types
Core types used throughout the API for identification, pagination, and data representation.