Home

Welcome to the osomemastodon documentation.

API Documentation

API Endpoints

1. Instance - Get Mastodon Instances API
2. Status - Search by keyword API
3. Status - Most recent by hashtag API
4. Status - Most recent for instance API
5. Status - Single status by Id API
6. Accounts - Search by keyword
7. Accounts - Single Account by Id
8. Get Hashtag metadata

1. Instance - Get Mastodon Instances API

Overview

The Mastodon Instances API provides a list of Mastodon instances based on specified criteria, including minimum active users, count, sorting, and authorization. You can access the official documentation from here.

Official API Endpoint

GET https://instances.social/api/1.0/instances/list

Request

• Method : GET
• URL : https://instances.social/api/1.0/instances/list
• Headers:
• Authorization: Bearer YOUR_API_KEY

OSoMe API Endpoint

GET https://osome.iu.edu/tools/mastodon/api/get-instance-data

Request

• Method : GET
• URL : https://osome.iu.edu/tools/mastodon/api/get-instance-data

Note Data is returned in JSON format.

2. Status - Search by keyword API

Overview

The Search API provides a method to retrieve accounts, statuses, and hashtags based on a specified search keyword. In this API, we get the statuses results as a json format. You can access the official documentation from here.

Official API Endpoint

GET https://{mastodon_instance}/api/v2/search?q={search_keyword}&type=statuses&resolve=true

Name	Type	Description
access_token	string	(Required) Bearer token for retrieving statuses.
search_keyword	string	(Required) The search keyword.

Headers

The following header must be included in the request:

• Authorization :Bearer token for authentication

Authorization: Bearer {access_token}

Request Example (POST request)

curl --location 'https://{mastodon_instance}/api/v2/search?q={search_keyword}&type=statuses' --header 'Authorization: Bearer 'TOKEN'

Note

• Ensure the provided access_token is a valid Bearer token.
• The response includes lists of accounts, statuses, and hashtags. But only populated statuses as we specifically select it.

3. Status - Most recent by hashtag API

Overview

This API endpoint allows users to retrieve public hashtag information from a Mastodon instance. You can access the official documentation from here.

Official API Endpoint

GET https://{mastodon_instance}/api/v1/timelines/tag/{hashtag}?limit={limit}&local={data_type}

Request

• Headers

1. Content-Type: application/json

• Parameters

1. mastodon_instance (string): The Mastodon instance name.
2. hashtag (string): The hashtag to fetch data for.
3. data_type (boolean): Indicates whether to include local data (true/false).
4. limit (integer): The maximum number of statuses to retrieve.

OSoMe API Endpoint

This API endpoint allows you to search public hashtag information through multiple Mastodon instances.

curl -X POST -H "Content-Type: application/json" -d '{"hashtag":"HASHTAG_NAME","mastodon_instances":[{"name":"MASTODON_INSTANCE"}],"data_type":"true/false","limit_no":"LIMIT_NO"}' "https://osome.iu.edu/tools/mastodon/api/hashtag-search"

Request

• Headers

1. Content-Type: application/json

• Parameters

1. mastodon_instances (array): List of Mastodon instances with their names.
2. hashtag (string): The hashtag to fetch data for.
3. data_type (boolean): Indicates whether to include local data (true/false).
4. limit_no (integer): The maximum number of statuses to retrieve.

4. Most recent for instance API