openapi: 3.1.0
info:
  title: Mastodon Instances API
  version: 1.0.0
  description: |
    The instances.social API allows searching for and retrieving information
    about Mastodon server instances, including user counts, language,
    software version, uptime statistics, content moderation policies, and
    supported features.
  contact:
    name: instances.social
    url: https://instances.social
servers:
  - url: https://instances.social/api/1.0
    description: Production
security:
  - BearerAuth: []
paths:
  /instances/sample:
    get:
      summary: Get a random sample of instances
      operationId: getInstancesSample
      parameters:
        - in: query
          name: count
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - in: query
          name: include_dead
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: A list of sampled instances.
  /instances/list:
    get:
      summary: List instances with rich filtering
      operationId: listInstances
      parameters:
        - in: query
          name: count
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 20
          description: 0 returns all instances.
        - in: query
          name: include_dead
          schema:
            type: boolean
            default: false
        - in: query
          name: include_down
          schema:
            type: boolean
            default: true
        - in: query
          name: include_closed
          schema:
            type: boolean
            default: true
        - in: query
          name: supported_features
          schema:
            type: string
          description: Comma-separated list of required features.
        - in: query
          name: min_version
          schema:
            type: string
        - in: query
          name: min_users
          schema:
            type: integer
        - in: query
          name: max_users
          schema:
            type: integer
        - in: query
          name: min_active_users
          schema:
            type: integer
        - in: query
          name: category
          schema:
            type: string
        - in: query
          name: language
          schema:
            type: string
        - in: query
          name: prohibited_content
          schema:
            type: array
            items:
              type: string
        - in: query
          name: allowed_content
          schema:
            type: array
            items:
              type: string
        - in: query
          name: min_id
          schema:
            type: string
        - in: query
          name: sort_by
          schema:
            type: string
            enum: [name, uptime, https_score, obs_score, users, statuses, connections, active_users]
        - in: query
          name: sort_order
          schema:
            type: string
            enum: [asc, desc]
            default: asc
      responses:
        '200':
          description: A list of instances.
  /instances/search:
    get:
      summary: Search instances by name, topic, or description
      operationId: searchInstances
      parameters:
        - in: query
          name: q
          required: true
          schema:
            type: string
        - in: query
          name: count
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 20
        - in: query
          name: name
          schema:
            type: boolean
            default: false
          description: Only search through instance names.
      responses:
        '200':
          description: Search results.
  /instances/show:
    get:
      summary: Show information about a specific instance
      operationId: showInstance
      parameters:
        - in: query
          name: name
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Instance details.
  /versions/list:
    get:
      summary: List Mastodon versions seen across the network
      operationId: listVersions
      parameters:
        - in: query
          name: count
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 20
        - in: query
          name: include_specials
          schema:
            type: boolean
            default: true
        - in: query
          name: include_unused
          schema:
            type: boolean
            default: true
        - in: query
          name: min_id
          schema:
            type: integer
      responses:
        '200':
          description: Versions list.
  /versions/show:
    get:
      summary: Show information about a specific Mastodon version
      operationId: showVersion
      parameters:
        - in: query
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Version details.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API token obtained from https://instances.social/api/token,
        passed as `Authorization: Bearer {token}`.