documentation/content/en/dev/routes.md

---

title: Routes description: How HTTP methods map to controllers and actions. menu: docs:

weight: 40
parent: dev

---

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/config/routes.rb" caption="config/routes.rb" >}}

Explanation of routes {#routes}

Mastodon uses Ruby on Rails, which defines its router configuration at config/routes.rb. You may view the Ruby on Rails routing guide for more detailed information, but this page will explain the basics of how Mastodon handles routing.

How routes are constructed {#router}

namespace is a prefix for routes mapped to a certain controller directory. resources are mapped to controllers within that namespace directory. scope passes to the module's controller. For example, consider the following abbreviated code:

{{< code title="config/routes.rb excerpt" >}}

namespace :api do
    namespace :v1 do
        resources :statuses, only [:create, :show, :destroy] do
            scope module: :statuses do
                resource :favourite, only: :create
                resource :unfavourite, to: 'favourites#destroy'
                member do
                    get :context
                end
            end
        end
    end
end

{{< /code >}}

The first available resource is :statuses, which is nested under the :api and :v1 namespaces. Thus, the resulting HTTP route will be /api/v1/statuses. The only defines certain allowed methods, which are to be defined in the controller at app/controllers/api/v1/statuses_controller.rb.

Within /api/v1/statuses, there is a scope for a module :statuses, where additional resources are defined. The controllers for these resources live in app/controllers/api/v1/statuses/. For example, :favourite will be handled by the #create action within app/controllers/api/v1/statuses/favourites_controller.rb and :unfavourite will be handled within the same controller, but by the #destroy action.

There is also a custom method defined for any member within this scope, or in other words, for any status to be controlled by app/controllers/api/v1/statuses_controller.rb, which is mapped to GET /api/v1/statuses/:id/context and handled by the :context action defined within that controller.

Available methods {#methods}

:index

Maps to HTTP GET, for a list. Handled by the #index action in a controller.

:show

Maps to HTTP GET, for a single view. Handled by the #show action in a controller.

:create

Maps to HTTP POST. Handled by the #create action in a controller.

:update

Maps to HTTP PUT. Handled by the #update action in a controller.

:destroy

Maps to HTTP DELETE. Handled by the #destroy action in a controller.

.well-known {#well-known}

/.well-known/host-meta {#host-meta}

Extensible Resource Descriptor (XRD). Advertises existence of Webfinger.

/.well-known/nodeinfo {#nodeinfo}

Maps to NodeInfo 2.0 endpoint at /nodeinfo/2.0, used for advertising software name and version, protocols, usage statistics, and whether registrations are open.

/.well-known/webfinger {#webfinger}

Used for discovering ActivityPub actor id. See Spec compliance > WebFinger for more information.

/.well-known/change-password {#change-password}

Maps to account settings page.

/.well-known/keybase-proof-config {#keybase}

Used for integration with Keybase, defining which usernames are acceptable and where proofs may be checked.

{{< hint style="warning" >}} The sections below this point are under construction. {{< /hint >}}

Public URIs {#public}

• /users/username = user URI
• /users/username/remote_follow = remote follow dialog
• /users/username/statuses/id = status URI
• /@username = "posts" tab
• /@username/with_replies = "posts and replies" tab
• /@username/media = "media" tab
• /@username/tagged/:hashtag = tagged statuses by user
• /@username/:status_id = status permalink
• /@username/:status_id/embed = embeddable version
• /interact/:status_id = remote interaction dialog
• /explore = profile directory
• /explore/:hashtag = profiles with this hashtag in bio
• /public = public timeline preview
• /about = landing page
• /about/more = extended description
• /terms = terms of service

API {#api}

• /api/oembed
• /api/proofs
• /api/v1
  • statuses [create, show, destroy]
  • reblogged_by [index]
  • favourited_by [index]
  • reblog [create]
  • unreblog [POST reblog#destroy]
  • favourite [create]
  • unfavourite [POST favourites#destroy]
  • bookmark [create]
  • unbookmark [POST bookmarks#destroy]
  • mute [create]
  • unmute [POST mutes#destroy]
  • pin [create]
  • unpin [POST pins#destroy]
  • context [GET]
  • timelines
  • home [show]
  • public [show]
  • tag [show]
  • list [show]
  • streaming [index]
  • custom_emojis [index]
  • suggestions [index, destroy]
  • scheduled_statuses [index, show, update, destroy]
  • preferences [index]
  • conversations [index, destroy]
  • read [POST]
  • media [create, update]
  • blocks [index]
  • mutes [index]
  • favourites [index]
  • bookmarks [index]
  • reports [create]
  • trends [index]
  • filters [index, create, show, update, destroy]
  • endorsements [index]
  • markers [index, create]
  • apps [create]
  • verify_credentials [credentials#show]
  • instance [show]
  • peers [index]
  • activity [show]
  • domain_blocks [show, create, destroy]
  • directory [show]
  • follow_requests [index]
  • authorize [POST]
  • reject [POST]
  • notifications [index, show]
  • clear [POST]
  • dismiss [POST]
  • accounts
  • verify_credentials [GET credentials#show]
  • update_credentials [PATCH credentials#update]
  • search [show (search#index)]
  • relationships [index]
  • accounts [create, show]
  • statuses [index accounts/statuses]
  • followers [index accounts/follower_accounts]
  • following [index accounts/following_accounts]
  • lists [index accounts/lists]
  • identity_proofs [index accounts/identity_proofs]
  • follow [POST]
  • unfollow [POST]
  • block [POST]
  • unblock [POST]
  • mute [POST]
  • unmute [POST]
  • pin [POST]
  • unpin [POST]
  • lists [index, create, show, update, destroy]
  • accounts [POST accounts/pins#destroy]
  • featured_tags [index, create, destroy]
  • suggestions [GET suggestions#index]
  • polls [create, show]
  • votes [create polls/votes]
  • push
  • subscription [create, show, update, destroy]
  • admin
  • accounts [index, show]
    • enable [POST]
    • unsilence [POST]
    • unsuspend [POST]
    • approve [POST]
    • reject [POST]
    • action [create account_actions]
  • reports [index, show]
    • assign_to_self [POST]
    • unassign [POST]
    • reopen [POST]
    • resolve [POST]
• /api/v2
  • search [GET search#index]