Mastodon

Connect your Mastodon account to schedule and publish posts through Cue.

Overview

Mastodon is a decentralized social network where users join instances (servers) of their choice. Cue integrates with the Mastodon API to publish content on your behalf across any Mastodon instance.

Sign up for a Mastodon account at joinmastodon.org.

Authentication

Mastodon uses OAuth 2.0 for secure authentication. When connecting, you specify your instance URL and Cue handles the rest.

Connecting Your Account

1. Go to Profiles in your Cue dashboard
2. Click Connect Account on a profile
3. Select Mastodon
4. Enter your instance URL (e.g., mastodon.social, hachyderm.io)
5. You'll be redirected to your Mastodon instance to authorize access
6. Sign in and grant Cue permission to post on your behalf
7. You'll be redirected back to Cue automatically

Your credentials are never shared with Cue.

Disconnecting

To disconnect your Mastodon account, go to your profile and click Disconnect next to the Mastodon connection. This revokes Cue's access to your account.

You can also revoke access from your Mastodon instance settings under Authorized Apps.

Content Limits

Mastodon enforces the following limits on posts (called "toots"):

Note: Character limits vary by Mastodon instance. Some instances allow up to 5,000 characters. Cue validates against your specific instance's limits.

Publishing a Post

curl -X POST https://api.oncue.so/v1/posts \
  -H "Authorization: Bearer cue_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "prf_abc123",
    "platforms": {
      "sac_mastodon1": {
        "items": [{ "content": "Hello from Cue!" }]
      }
    },
    "publishNow": true
  }'

const response = await fetch("https://api.oncue.so/v1/posts", {
  method: "POST",
  headers: {
    Authorization: "Bearer cue_sk_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    profileId: "prf_abc123",
    platforms: {
      sac_mastodon1: {
        items: [{ content: "Hello from Cue!" }]
      }
    },
    publishNow: true,
  }),
});

Schedule for Later

curl -X POST https://api.oncue.so/v1/posts \
  -H "Authorization: Bearer cue_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "prf_abc123",
    "platforms": {
      "sac_mastodon1": {
        "items": [{ "content": "Scheduled toot content" }]
      }
    },
    "scheduledAt": "2024-01-20T09:00:00-05:00"
  }'

const response = await fetch("https://api.oncue.so/v1/posts", {
  method: "POST",
  headers: {
    Authorization: "Bearer cue_sk_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    profileId: "prf_abc123",
    platforms: {
      sac_mastodon1: {
        items: [{ content: "Scheduled toot content" }]
      }
    },
    scheduledAt: "2024-01-20T09:00:00-05:00",
  }),
});

Creating Threads

Create multi-post threads by including multiple items in the items array. Each item becomes a connected toot in the thread.

curl -X POST https://api.oncue.so/v1/posts \
  -H "Authorization: Bearer cue_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "prf_abc123",
    "platforms": {
      "sac_mastodon1": {
        "items": [
          { "content": "1/ Let me share some thoughts on the fediverse..." },
          { "content": "2/ The beauty of Mastodon is server choice..." },
          { "content": "3/ Each community can set its own rules..." },
          { "content": "4/ This is what decentralization looks like!" }
        ]
      }
    },
    "publishNow": true
  }'

const response = await fetch("https://api.oncue.so/v1/posts", {
  method: "POST",
  headers: {
    Authorization: "Bearer cue_sk_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    profileId: "prf_abc123",
    platforms: {
      sac_mastodon1: {
        items: [
          { content: "1/ Let me share some thoughts on the fediverse..." },
          { content: "2/ The beauty of Mastodon is server choice..." },
          { content: "3/ Each community can set its own rules..." },
          { content: "4/ This is what decentralization looks like!" }
        ]
      }
    },
    publishNow: true,
  }),
});

Each post in a thread must respect the 500 character limit (may vary by server).

Response

{
  "data": {
    "id": "pst_xyz789",
    "profileId": "prf_abc123",
    "content": "Hello from Cue!",
    "status": "queued",
    "scheduledAt": null,
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  },
  "message": "Post queued for publishing to 1 platform(s)"
}

Error Handling

Mastodon API errors are translated into user-friendly messages:

Common Issues

"Reconnect required" error

• Your access token has expired or been revoked
• Go to your profile and reconnect your Mastodon account

"Content too long" error

• Your post exceeds your instance's character limit
• Most instances allow 500 characters, but some allow more
• Shorten your message or split it into multiple posts

"Instance unreachable" error

• Your Mastodon instance may be temporarily down
• Check your instance's status page
• Try again in a few minutes

"Media upload failed" error

• Your file may exceed the instance's size limits
• Compress images or videos and try again

Troubleshooting

Connection Issues

Cannot find instance during OAuth

• Verify your instance URL is correct (e.g., mastodon.social)
• Ensure the instance is online and accepting connections
• Try without https:// prefix

OAuth returns error

• Your Mastodon instance may have restrictions on third-party apps
• Some instances require admin approval for OAuth applications
• Contact your instance administrator

"Invalid redirect" error

• Try using a different browser
• Disable browser extensions that might block redirects
• Clear your browser cache and cookies

Publishing Issues

Posts not appearing

• Check if your post is still in "queued" status
• Wait a few minutes - federated posts may take time to propagate
• Check the post's platform status for error details

Hashtags not working

• Mastodon hashtags must use the # symbol
• Multi-word hashtags should be CamelCase (e.g., #OpenSource)
• Hashtags cannot contain spaces or special characters

Mentions not linking

• Use full handles including instance (e.g., @user@mastodon.social)
• The mentioned user must exist on a federated instance

Best Practices

Content Guidelines

• Mastodon values content warnings for sensitive topics
• Use hashtags to help content discovery
• Mention users with @user@instance format
• Keep posts concise but informative

Instance-Specific Features

• Check your instance's rules and guidelines
• Some instances have topic restrictions
• Local timelines show posts from your instance only
• Federated timelines show posts from all connected instances

Further Reading

• Mastodon Documentation
• Mastodon API Reference
• Find a Mastodon Instance