Skip to main content

Getting Started

Beta

This library is currently in beta. API implementation is complete, but test coverage is minimal. Response models and method signatures may change based on test findings.

If you encounter any issues such as incorrect response models or unexpected behavior, please report them via GitHub Issues or submit a Pull Request.

mastodon_client is a pure Dart Mastodon API client library. It works in any environment where Dart runs: Flutter, server-side Dart, CLI tools, and more.

Installation​

Add the dependency to your pubspec.yaml:

dependencies:
  mastodon_client: ^1.0.0-beta.1

Then fetch it:

dart pub get

Basic Usage​

Initializing the client​

import 'package:mastodon_client/mastodon_client.dart';

final client = MastodonClient(
  baseUrl: 'https://mastodon.social',
  accessToken: 'your_access_token',
);

baseUrl must include the scheme (e.g. https://). accessToken can be omitted when only using endpoints that do not require authentication.

Your first API call​

Fetching server information (no authentication required):

final instance = await client.instance.fetch();
print(instance.title);       // Server name
print(instance.description); // Server description

Fetching the authenticated user's account:

final me = await client.accounts.verifyCredentials();
print(me.displayName); // Display name
print(me.acct);        // Username

API structure​

Every API is exposed as a property on MastodonClient, acting as a namespace:

client.accounts      // Account operations
client.statuses      // Status operations
client.timelines     // Timeline retrieval
client.notifications // Notification operations
client.media         // Media upload
client.search        // Search
client.oauth         // OAuth token operations
// ... and many more

Controlling log output​

HTTP request/response logs are printed to stdout by default.

// Disable logging
final client = MastodonClient(
  baseUrl: 'https://mastodon.social',
  accessToken: 'token',
  enableLog: false,
);

// Use a custom logger
final client = MastodonClient(
  baseUrl: 'https://mastodon.social',
  accessToken: 'token',
  logger: FunctionLogger((level, message) {
    // Your custom log handling
  }),
);

See Logging for details.

Next steps​