Skip to content

Home

Jump to bottom
Pasan Kamburugamuwa edited this page Jan 2, 2024 · 23 revisions

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

OSoMe API Endpoint

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

Request

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

Overview

This API endpoint retrieves public timeline statuses from a Mastodon instance. You can access the official documentation from here.

Official API Endpoint

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

Request

  • Headers
  1. Content-Type: application/json
  • Parameters
  1. mastodon_instance (string): The Mastodon instance name.
  2. limit (integer): The maximum number of statuses to retrieve.
  3. data_type (boolean): Indicates whether to include local data (true/false). [true - Local data, false - Federated data]

OSoMe API Endpoint

This API endpoint retrieves public timeline statuses across multiple Mastodon instances. It accepts a JSON payload containing Mastodon instances and a search keyword.

(POST Request)

curl -X POST -H "Content-Type: application/json" -d '{"mastodon_instances":[{"name":"MASTODON_INSTANCE"}],"data_type":"TRUE/FALSE","limit_no":"LIMIT"}' "https://osome.iu.edu/tools/mastodon/api/timeline-statuses"

Request

  • Headers
  1. Content-Type: application/json
  • Parameters
  1. mastodon_instances (array): List of Mastodon instances with their names.
  2. limit_no (integer): The maximum number of statuses to retrieve.
  3. data_type (boolean): Indicates whether to include local data (true/false). [true - Local data, false - Federated data]

5. Status - Single status by Id API

Overview

This API method is used to search for statuses from a Mastodon instance based on a specific status Id. You can access the official documentation from here.

Official API Endpoint

GET https://{mastodon_instance}/api/v1/statuses/{status_id}

Request

  • Headers
  1. Content-Type: application/json
  • Parameters
  1. mastodon_instance : This should be replaced with the domain of the Mastodon instance you are working with (e.g., mastodon.social)
  2. status_Id (string): This should be replaced with the ID of the specific status you want to retrieve

OSoMe API Endpoint

GET https://osome.iu.edu/tools/mastodon/api/search-status-by-id?status_id={STATUS_ID}&mastodon_instance={MASTODON_INSTANCE}

Request

  • Headers
  1. Content-Type: application/json
  • Parameters
  1. mastodon_instance (string): The Mastodon instance name.
  2. status_id : The mastodon specific status id you want to search.

6. Accounts - Search by keyword

Overview

This API retrieves account data from a Mastodon instance based on a search keyword. You can access the official documentation from here.

Official API Endpoint

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

Request

  • Headers
  1. Content-Type: application/json
  • Parameters
  1. mastodon_instance (string): The Mastodon instance name.
  2. account_id (string): The unique identifier for the Mastodon account.

Request Example (POST request) curl --location 'https://{mastodon_instance}/api/v2/search?q={search_keyword}&type=accounts' --header 'Authorization: Bearer 'TOKEN'

Note

  1. Ensure the provided access_token is a valid Bearer token.
  2. The response includes lists of accounts, statuses, and hashtags. But only get populated accounts as we specifically select it.
Clone this wiki locally