mastodon

README

mastodon

A pure-Go, dependency-free read client for the Mastodon REST API.

• CGO_ENABLED=0 — no C, static binaries everywhere.
• Zero third-party dependencies — standard library only.
• Reads public, hashtag and per-account timelines, with Link-header pagination.
• 100% test coverage, network-free tests via net/http/httptest.

Install

go get github.com/go-mastodon/mastodon

Requires Go 1.26.4 or newer.

Usage

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/go-mastodon/mastodon"
)

func main() {
	c := mastodon.New("https://mastodon.social",
		mastodon.WithUserAgent("myapp/1.0"),
		// mastodon.WithToken("…"), // optional bearer token
	)

	tl, err := c.PublicTimeline(context.Background(), mastodon.TimelineOptions{
		Limit:     20,
		OnlyMedia: true,
		Local:     true,
	})
	if err != nil {
		log.Fatal(err)
	}

	for _, s := range tl.Statuses {
		fmt.Printf("@%s: %s\n", s.Account.Acct, s.URL)
	}

	// Fetch the next page using the pagination cursor.
	if tl.MaxID != "" {
		next, err := c.PublicTimeline(context.Background(), mastodon.TimelineOptions{MaxID: tl.MaxID})
		if err != nil {
			log.Fatal(err)
		}
		_ = next
	}
}

Other timelines

// A hashtag timeline.
tl, err := c.HashtagTimeline(ctx, "golang", mastodon.TimelineOptions{Limit: 10})

// An account's statuses (resolves the acct to an account ID first).
tl, err := c.AccountStatuses(ctx, "Gargron@mastodon.social", mastodon.TimelineOptions{})

API

Method	Endpoint
PublicTimeline	GET /api/v1/timelines/public
HashtagTimeline	GET /api/v1/timelines/tag/:hashtag
AccountStatuses	GET /api/v1/accounts/lookup then GET /api/v1/accounts/:id/statuses

All methods take a context.Context and TimelineOptions (Limit, MaxID, OnlyMedia, Local) and return a *Timeline whose MaxID field carries the rel="next" pagination cursor parsed from the Link response header.

License

BSD-3-Clause. See LICENSE.

Documentation

Overview

Package mastodon is a dependency-free read client for the Mastodon REST API.

It uses only the Go standard library (CGO_ENABLED=0) and exposes a small surface for reading public, hashtag and per-account timelines.

Index

• type Account
• type Client
  • func New(instance string, opts ...Option) *Client
  • func (c *Client) AccountStatuses(ctx context.Context, acct string, opts TimelineOptions) (*Timeline, error)
  • func (c *Client) HashtagTimeline(ctx context.Context, tag string, opts TimelineOptions) (*Timeline, error)
  • func (c *Client) PublicTimeline(ctx context.Context, opts TimelineOptions) (*Timeline, error)
• type Media
• type Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithToken(t string) Option
  • func WithUserAgent(ua string) Option
• type Status
• type Tag
• type Timeline
• type TimelineOptions

Types

type Account

type Account struct {
	ID          string `json:"id"`
	Username    string `json:"username"`
	Acct        string `json:"acct"`
	DisplayName string `json:"display_name"`
	URL         string `json:"url"`
	Avatar      string `json:"avatar"`
}

Account is a Mastodon account.

type Client

type Client struct {
	// Instance is the base URL of the Mastodon instance,
	// e.g. https://mastodon.social.
	Instance string
	// Token is an optional bearer token. When set, requests are
	// authenticated with an Authorization header.
	Token string
	// HTTPClient is the underlying HTTP client. When nil, http.DefaultClient
	// is used.
	HTTPClient *http.Client
	// UserAgent is the value sent in the User-Agent header.
	UserAgent string
}

Client is a read-only Mastodon REST API client.

func New

func New(instance string, opts ...Option) *Client

New creates a Client for the given instance base URL.

func (*Client) AccountStatuses

func (c *Client) AccountStatuses(ctx context.Context, acct string, opts TimelineOptions) (*Timeline, error)

AccountStatuses resolves acct via GET /api/v1/accounts/lookup and then fetches that account's statuses (GET /api/v1/accounts/:id/statuses).

func (*Client) HashtagTimeline

func (c *Client) HashtagTimeline(ctx context.Context, tag string, opts TimelineOptions) (*Timeline, error)

HashtagTimeline fetches the timeline for a hashtag (GET /api/v1/timelines/tag/:hashtag).

func (*Client) PublicTimeline

func (c *Client) PublicTimeline(ctx context.Context, opts TimelineOptions) (*Timeline, error)

PublicTimeline fetches the public timeline (GET /api/v1/timelines/public).

type Media

type Media struct {
	Type        string `json:"type"` // image, video, gifv, audio
	URL         string `json:"url"`
	PreviewURL  string `json:"preview_url"`
	Description string `json:"description"`
}

Media is a media attachment on a status.

type Option

type Option func(*Client)

Option configures a Client.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient sets the HTTP client used to perform requests.

func WithToken

func WithToken(t string) Option

WithToken sets the bearer token used to authenticate requests.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent sets the User-Agent header value.

type Status

type Status struct {
	ID          string    `json:"id"`
	URL         string    `json:"url"`
	Content     string    `json:"content"` // HTML
	CreatedAt   time.Time `json:"created_at"`
	Account     Account   `json:"account"`
	Favourites  int       `json:"favourites_count"`
	Reblogs     int       `json:"reblogs_count"`
	Replies     int       `json:"replies_count"`
	Sensitive   bool      `json:"sensitive"`
	SpoilerText string    `json:"spoiler_text"`
	Media       []Media   `json:"media_attachments"`
	Tags        []Tag     `json:"tags"`
}

Status is a Mastodon status (toot).

type Tag

type Tag struct {
	Name string `json:"name"`
	URL  string `json:"url"`
}

Tag is a hashtag referenced by a status.

type Timeline

type Timeline struct {
	Statuses []Status
	// MaxID is extracted from the Link header rel="next" and can be passed
	// as TimelineOptions.MaxID to fetch the following page. It is empty when
	// there is no next page.
	MaxID string
}

Timeline is a page of statuses plus the pagination cursor.

type TimelineOptions

type TimelineOptions struct {
	Limit     int
	MaxID     string
	OnlyMedia bool
	Local     bool
}

TimelineOptions holds the query parameters shared by the timeline methods.