Skip to content

Home

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

Welcome to the osomemastodon API 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.

OSoMe API Endpoint

The API endpoint facilitates the search for statuses across multiple Mastodon instances using a specified keyword.

curl -X POST -H "Content-Type: application/json" -d '{"mastodon_instances":[{"name":"INSTANCE_NAME_1"},{"name":"INSTANCE_NAME_2"}],"keyword":"SEARCH_KEYWORD","access_tokens":["ACCESS_TOKEN_1","ACCESS_TOKEN_2"]}' "https://osome.iu.edu/tools/mastodon/api/search-status-by-keyword"

Request

  • Headers
  1. Content-Type: application/json
  • Parameters
  1. mastodon_instances (array): List of Mastodon instances with their names.
  2. keyword (string): (Required) The search keyword.
  3. access_tokens (array): List of access tokens for each mastodon instance.

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.

OSoMe API Endpoint

The API endpoint facilitates the search for accounts across multiple Mastodon instances using a specified keyword.

curl -X POST -H "Content-Type: application/json" -d '{"keyword":"SEARCH_KEYWORD","instances":[{"name":"INSTANCE_1"},{"name":"INSTANCE_2"}]}' "https://osome.iu.edu/tools/mastodon/api/search-accounts-by-keyword"

Request

  • Headers
  1. Content-Type: application/json
  • Parameters
  1. instances (array): List of Mastodon instances with their names.
  2. keyword (string): (Required) The search keyword.

7. Accounts - Single Account by Id

Overview

This API endpoint retrieves account information from the Mastodon API based on the account ID and Mastodon instance name. You can access the official documentation from here.

Official API Endpoint

GET https://{mastodon_instance}/api/v1/accounts/{account_id}

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.

OSoMe API Endpoint

GET https://osome.iu.edu/api/account-search-by-id?mastodon_instance={mastodon_instance}&account_id={account_id}

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.

Note

  1. When retrieving some of the account information, there may be instances where certain data is not available or not returned by the Mastodon API.

8. Get Hashtag metadata

Overview

This API endpoint retrieves account information from the Mastodon API based on the account ID and Mastodon instance name. You can access the official documentation from here.

Official API Endpoint

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

Request

  • Headers
  1. Content-Type: application/json
  • Parameters
  1. mastodon_instance (string): The Mastodon instance name.
  2. search_keyword (string): (Required) The search keyword.

OSoMe API Endpoint

This API endpoint for searching hashtag data through a hashtag keyword 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 '{"keyword":"SEARCH_KEYWORD","instances":[{"name":"MASTODON_INSTANCE}}' "https://osome.iu.edu/tools/mastodon/api/search-hashtag-by-keyword"

Request

  • Headers
  1. Content-Type: application/json
  • Parameters
  1. mastodon_instances (array): List of Mastodon instances with their names.
  2. search_keyword (string): The search keyword.
Clone this wiki locally