Replace version numbers with release numbers

CHANGELOG.rst

@@ -38,4 +38,4 @@ Specification changes in v0.1.0 (2015-06-01)
 ============================================
 - First numbered release.
 - Restructure the format of Event information. Add more information.
-- Restructure the format of the Client-Server HTTP APIs.
+- Restructure the format of the Client-Server HTTP APIs.

api/client-server/account-data.yaml

@@ -6,7 +6,7 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/administrative_contact.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Account Administrative Contact API"
+  title: "Matrix Client-Server Account Administrative Contact API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/banning.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Banning API"
+  title: "Matrix Client-Server Room Banning API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/content-repo.yaml

@@ -1,11 +1,11 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Content Repository API"
+  title: "Matrix Client-Server Content Repository API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
-basePath: /_matrix/media/v1
+basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
 produces:
   - application/json
   - "*/*"

api/client-server/create_room.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Creation API"
+  title: "Matrix Client-Server Room Creation API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/directory.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Directory API"
+  title: "Matrix Client-Server Directory API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1/directory
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory
 consumes:
   - application/json
 produces:

api/client-server/filter.yaml

@@ -1,11 +1,11 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v2 filter API"
+  title: "Matrix Client-Server filter API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/guest_events.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Sync Guest API"
+  title: "Matrix Client-Server Sync Guest API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/inviting.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Joining API"
+  title: "Matrix Client-Server Room Joining API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/joining.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Inviting API"
+  title: "Matrix Client-Server Room Inviting API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -63,6 +63,6 @@ paths:
           schema:
             "$ref": "definitions/error.yaml"
       x-alias:
-        canonical-link: "post-matrix-client-api-v1-rooms-roomid-join"
+        canonical-link: "post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join"
         aliases:
-          - /_matrix/client/api/v1/join/{roomId}
+          - /_matrix/client/%CLIENT_MAJOR_VERSION%/join/{roomId}

api/client-server/leaving.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Leaving API"
+  title: "Matrix Client-Server Room Leaving API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/list_public_rooms.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Creation API"
+  title: "Matrix Client-Server Room Creation API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/login.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Registration and Login API"
+  title: "Matrix Client-Server Registration and Login API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/message_pagination.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Rooms API"
+  title: "Matrix Client-Server Rooms API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/old_sync.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Sync API"
+  title: "Matrix Client-Server Sync API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/presence.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Presence API"
+  title: "Matrix Client-Server Presence API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/profile.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Profile API"
+  title: "Matrix Client-Server Profile API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/push_notifier.yaml

@@ -6,7 +6,7 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/push/v1
+basePath: /_matrix/push/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/pusher.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Push API"
+  title: "Matrix Client-Server Push API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/pushrules.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Push Rules API"
+  title: "Matrix Client-Server Push Rules API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/receipts.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v2 Receipts API"
+  title: "Matrix Client-Server Receipts API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/registration.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v2 Registration API"
+  title: "Matrix Client-Server Registration API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/room_send.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 message event send API"
+  title: "Matrix Client-Server message event send API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/room_state.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 state event send API"
+  title: "Matrix Client-Server state event send API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/rooms.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Rooms API"
+  title: "Matrix Client-Server Rooms API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/search.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Search API"
+  title: "Matrix Client-Server Search API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
@@ -67,7 +67,7 @@ paths:
                         title: Filter
                         description: |-
                             The filter to apply to search results.
-                            This has the same format as v2 filter API.
+                            This has the same format as filter API.
                     required: ["search_term"]
             required: ["search_categories"]
       responses:

api/client-server/sync.yaml

@@ -1,11 +1,11 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v2 sync API"
+  title: "Matrix Client-Server sync API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/tags.yaml

@@ -6,7 +6,7 @@ host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/third_party_membership.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Room Membership API for third party identifiers"
+  title: "Matrix Client-Server Room Membership API for third party identifiers"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/typing.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Typing API"
+  title: "Matrix Client-Server Typing API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

api/client-server/voip.yaml

@@ -1,12 +1,12 @@
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server v1 Voice over IP API"
+  title: "Matrix Client-Server Voice over IP API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:

drafts/e2e.rst

@@ -115,7 +115,7 @@ The JSON object is signed using the process given by `Signing JSON`_.
 
 .. code:: http
 
-    POST /_matrix/client/v2_alpha/keys/upload/<device_id> HTTP/1.1
+    POST /_matrix/client/%CLIENT_MAJOR_VERSION%/keys/upload/<device_id> HTTP/1.1
     Content-Type: application/json
 
     {
@@ -206,7 +206,7 @@ lies about the keys a user owns.
     } } } } } }
 
 
-Clients use ``/_matrix/client/v2_alpha/keys/query`` on their own homeservers to
+Clients use ``/_matrix/client/%CLIENT_MAJOR_VERSION%/keys/query`` on their own homeservers to
 query keys for any user they wish to contact. Homeservers will respond with the
 keys for their local users and forward requests for remote users to
 ``/_matrix/federation/v1/user/keys/query`` over federation to the remote
@@ -263,7 +263,7 @@ time key once it has given that key to another user.
     } } } }
 
 
-Clients use ``/_matrix/client/v2_alpha/keys/claim`` on their own homeservers to
+Clients use ``/_matrix/client/%CLIENT_MAJOR_VERSION%/keys/claim`` on their own homeservers to
 claim keys for any user they wish to contact. Homeservers will respond with the
 keys for their local users and forward requests for remote users to
 ``/_matrix/federation/v1/user/keys/claim`` over federation to the remote

specification/application_service_api.rst

@@ -153,10 +153,10 @@ application services MUST implement these APIs. These APIs are defined below.
 
 .. _create the user: `sect:asapi-permissions`_
 
-Client-Server v2 API Extensions
+Client-Server API Extensions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Application services can utilise a more powerful version of the 
+Application services can use a more powerful version of the
 client-server API by identifying itself as an application service to the
 homeserver.
 
@@ -281,7 +281,7 @@ an API is exposed.
 
 ::
 
-  GET /_matrix/app/v1/user?uri=$url_encoded_uri
+  GET /_matrix/app/%CLIENT_MAJOR_VERSION%/user?uri=$url_encoded_uri
   
   Returns 200 OK:
   {
@@ -305,7 +305,7 @@ SHOULD be mapped in the same way as "user" URIs.
 
 ::
 
-  GET /_matrix/app/v1/alias?uri=$url_encoded_uri
+  GET /_matrix/app/%CLIENT_MAJOR_VERSION%/alias?uri=$url_encoded_uri
   
   Returns 200 OK:
   {

specification/client_server_api.rst

@@ -7,16 +7,6 @@ support both lightweight clients which store no state and lazy-load data from
 the server as required - as well as heavyweight clients which maintain a full
 local persistent copy of server state.
 
-This mostly describes v1 of the Client-Server API as featured in the original September
-2014 launch of Matrix, apart from user-interactive authentication where it is
-encouraged to move to v2, therefore this is the version documented here.
-Version 2 is currently in development (as of Jan-March 2015) as an incremental
-but backwards-incompatible refinement of Version 1 and will be released
-shortly.
-
-Documentation for the old `V1 authentication
-<../attic/v1_registration_login.rst>`_ is still available separately.
-
 .. contents:: Table of Contents
 .. sectnum::
 
@@ -93,41 +83,17 @@ Some requests have unique error codes:
 
 .. _sect:txn_ids:
 
-The Client-Server API typically uses ``HTTP POST`` to submit requests. This
+The Client-Server API typically uses ``HTTP PUT`` to submit requests with a
-means these requests are not idempotent. The C-S API also allows ``HTTP PUT`` to
+client-generated transaction identifier. This means that these requests are
-make requests idempotent. In order to use a ``PUT``, paths should be suffixed
+idempotent. The scope of a transaction identifier is a particular access token.
-with ``/{txnId}``. ``{txnId}`` is a unique client-generated transaction ID which
+It **only** serves to identify new
-identifies the request, and is scoped to a given Client (identified by that
-client's ``access_token``). Crucially, it **only** serves to identify new
 requests from retransmits. After the request has finished, the ``{txnId}``
 value should be changed (how is not specified; a monotonically increasing
-integer is recommended). It is preferable to use ``HTTP PUT`` to make sure
+integer is recommended).
-requests to send messages do not get sent more than once should clients need to
-retransmit requests.
 
-Valid requests look like::
+Some API endpoints may allow or require the use of ``POST`` requests without a
-
+transaction ID. Where this is optional, the use of a ``PUT`` request is strongly
-    POST /some/path/here?access_token=secret
+recommended.
-    {
-      "key": "This is a post."
-    }
-
-    PUT /some/path/here/11?access_token=secret
-    {
-      "key": "This is a put with a txnId of 11."
-    }
-
-In contrast, these are invalid requests::
-
-    POST /some/path/here/11?access_token=secret
-    {
-      "key": "This is a post, but it has a txnId."
-    }
-
-    PUT /some/path/here?access_token=secret
-    {
-      "key": "This is a put but it is missing a txnId."
-    }
 
 Client Authentication
 ---------------------
@@ -135,7 +101,7 @@ Most API endpoints require the user to identify themselves by presenting
 previously obtained credentials in the form of an ``access_token`` query
 parameter.
 
-In API version 2, when credentials are missing or invalid, the HTTP call will
+When credentials are required but missing or invalid, the HTTP call will
 return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or
 ``M_UNKNOWN_TOKEN`` respectively.
 
@@ -144,8 +110,6 @@ User-Interactive Authentication API
 
 .. _sect:auth-api:
 
-This section refers to API Version 2.
-
 Some API endpoints such as ``login`` or ``register`` require authentication that
 interacts with the user. The homeserver may provide many different ways of
 authenticating, such as user/password auth, login via a social network (OAuth2),
@@ -450,9 +414,9 @@ Clients cannot be expected to be able to know how to process every single login
 type. If a client does not know how to handle a given login type, it can direct
 the user to a web browser with the URL of a fallback page which will allow the
 user to complete that login step out-of-band in their web browser. The URL it
-should open is the homeserver base URL plus prefix, plus::
+should open is::
 
-  /auth/<stage type>/fallback/web?session=<session ID>
+  /_matrix/client/%CLIENT_MAJOR_VERSION%/auth/<stage type>/fallback/web?session=<session ID>
 
 Where ``stage type`` is the type name of the stage it is attempting and
 ``session id`` is the ID of the session given by the homeserver.
@@ -463,15 +427,10 @@ the authentication has been completed.
 
 API calls using the User-Interactive Authentication mechanism
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This section refers to API Version 2. These API calls currently use the prefix
-``/_matrix/client/v2_alpha``.
-
 .. _User-Interactive Authentication: `sect:auth-api`_
 
 {{registration_http_api}}
 
-Old V1 API docs: |register|_
-
 {{login_http_api}}
 
 Login Fallback
@@ -490,7 +449,7 @@ Changing Password
 +++++++++++++++++
 Request::
 
-  POST $V2PREFIX/account/password
+  POST /_matrix/client/%CLIENT_MAJOR_VERSION%/account/password
 
 This API endpoint uses the User-Interactive Authentication API. An access token
 should be submitted to this endpoint if the client has an active session. The
@@ -622,15 +581,21 @@ point in time::
 
   [E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]->[E7]->[E8]->[E9]
   
-Clients can add to the stream by POSTing message or state events, and can read
+Clients can add to the stream by PUTing message or state events, and can read
-from the stream via the |initialSync|_, |/rooms/<room_id>/initialSync|_, `Event
+from the stream via the
-Stream`_ and |/rooms/<room_id>/messages|_ APIs.
+|initialSync|_,
+|events|_,
+|/rooms/<room_id>/initialSync|_, and
+|/rooms/<room_id>/messages|_
+APIs.
 
 For reading events, the intended flow of operation is to call
-$PREFIX/initialSync, which returns all of the state and the last N events in the
+/_matrix/client/%CLIENT_MAJOR_VERSION%/initialSync, which returns all of the
+state and the last N events in the
 event stream for each room, including ``start`` and ``end`` values describing the
 pagination of each room's event stream. For instance,
-$PREFIX/initialSync?limit=5 might return the events for a room in the
+/_matrix/client/%CLIENT_MAJOR_VERSION%/initialSync?limit=5 might return the
+events for a room in the
 rooms[0].messages.chunk[] array, with tokens describing the start and end of the
 range in rooms[0].messages.start as '1-2-3' and rooms[0].messages.end as
 'a-b-c'.
@@ -643,7 +608,8 @@ You can visualise the range of events being returned as::
                         start: '1-2-3'                end: 'a-b-c'
                              
 Now, to receive future events in real-time on the event stream, you simply GET
-$PREFIX/events with a ``from`` parameter of 'a-b-c': in other words passing in the
+/_matrix/client/%CLIENT_MAJOR_VERSION%/events with a ``from`` parameter of
+'a-b-c': in other words passing in the
 ``end`` token returned by initial sync. The request blocks until new events are
 available or until your specified timeout elapses, and then returns a
 new paginatable chunk of events alongside new start and end parameters::
@@ -655,10 +621,11 @@ new paginatable chunk of events alongside new start and end parameters::
                                                       start: 'a-b-c'
 
 To resume polling the events stream, you pass in the new ``end`` token as the
-``from`` parameter of $PREFIX/events and poll again.
+``from`` parameter of /_matrix/client/%CLIENT_MAJOR_VERSION%/events and poll again.
 
 Similarly, to paginate events backwards in order to lazy-load in previous
-history from the room, you simply GET $PREFIX/rooms/<room_id>/messages
+history from the room, you simply
+GET /_matrix/client/%CLIENT_MAJOR_VERSION%/rooms/<room_id>/messages
 specifying the ``from`` token to paginate backwards from and a limit of the number
 of messages to retrieve. For instance, calling this API with a ``from`` parameter
 of '1-2-3' and a limit of 5 would return::
@@ -1023,44 +990,33 @@ have to wait in milliseconds before they can try again.
 .. Links through the external API docs are below
 .. =============================================
 
-.. |createRoom| replace:: ``/createRoom``
-.. _createRoom: /docs/api/client-server/#!/-rooms/create_room
-
 .. |initialSync| replace:: ``/initialSync``
-.. _initialSync: /docs/api/client-server/#!/-events/initial_sync
+.. _initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-initialsync
+
+.. |events| replace:: ``/events``
+.. _events: #get-matrix-client-%CLIENT_MAJOR_VERSION%-events
 
 .. |/rooms/<room_id>/initialSync| replace:: ``/rooms/<room_id>/initialSync``
-.. _/rooms/<room_id>/initialSync: /docs/api/client-server/#!/-rooms/get_room_sync_data
+.. _/rooms/<room_id>/initialSync: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync
-
-.. |login| replace:: ``/login``
-.. _login: /docs/api/client-server/#!/-login
-
-.. |register| replace:: ``/register``
-.. _register: /docs/api/client-server/#!/-registration
 
 .. |/rooms/<room_id>/messages| replace:: ``/rooms/<room_id>/messages``
-.. _/rooms/<room_id>/messages: /docs/api/client-server/#!/-rooms/get_messages
+.. _/rooms/<room_id>/messages: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages
 
 .. |/rooms/<room_id>/members| replace:: ``/rooms/<room_id>/members``
-.. _/rooms/<room_id>/members: /docs/api/client-server/#!/-rooms/get_members
+.. _/rooms/<room_id>/members: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-members
 
 .. |/rooms/<room_id>/state| replace:: ``/rooms/<room_id>/state``
-.. _/rooms/<room_id>/state: /docs/api/client-server/#!/-rooms/get_state_events
+.. _/rooms/<room_id>/state: #get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state
 
 .. |/rooms/<room_id>/invite| replace:: ``/rooms/<room_id>/invite``
-.. _/rooms/<room_id>/invite: /docs/api/client-server/#!/-rooms/invite
+.. _/rooms/<room_id>/invite: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-invite
 
 .. |/rooms/<room_id>/join| replace:: ``/rooms/<room_id>/join``
-.. _/rooms/<room_id>/join: /docs/api/client-server/#!/-rooms/join_room
+.. _/rooms/<room_id>/join: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join
 
 .. |/rooms/<room_id>/leave| replace:: ``/rooms/<room_id>/leave``
-.. _/rooms/<room_id>/leave: /docs/api/client-server/#!/-rooms/leave
+.. _/rooms/<room_id>/leave: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-leave
 
 .. |/rooms/<room_id>/ban| replace:: ``/rooms/<room_id>/ban``
-.. _/rooms/<room_id>/ban: /docs/api/client-server/#!/-rooms/ban
+.. _/rooms/<room_id>/ban: #post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-ban
-
-.. |/join/<room_alias_or_id>| replace:: ``/join/<room_alias_or_id>``
-.. _/join/<room_alias_or_id>: /docs/api/client-server/#!/-rooms/join
-
-.. _`Event Stream`: /docs/api/client-server/#!/-events/get_event_stream
 

specification/intro.rst

@@ -15,6 +15,9 @@ The following APIs are documented in this specification:
 
 There are also some `appendices <appendices.html>`_.
 
+Before we formally started releasing the specification, the last working copy
+we had can be found `here <https://matrix.org/docs/spec/legacy/>`_.
+
 .. contents:: Table of Contents
 .. sectnum::
 

specification/modules/account_data.rst

@@ -14,11 +14,11 @@ Events
 ------
 
 The client recieves the account data as events in the ``account_data`` sections
-of a v2 /sync.
+of a ``/sync``.
 
-These events can also be received in a v1 /events response or in the
+These events can also be received in a ``/events`` response or in the
-``account_data`` section of a room in v1 /initialSync. ``m.tag``
+``account_data`` section of a room in ``/initialSync``. ``m.tag``
-events appearing in v1 /events will have a ``room_id`` with the room
+events appearing in ``/events`` will have a ``room_id`` with the room
 the tags are for.
 
 Client Behaviour

specification/modules/guest_access.rst

@@ -9,7 +9,7 @@ the room. This module specifies how these clients should interact with servers
 in order to participate in rooms as guests.
 
 Guest users retrieve access tokens from a homeserver using the ordinary
-`register endpoint <#post-matrix-client-api-v2-alpha-register>`_, specifying
+`register endpoint <#post-matrix-client-%CLIENT_MAJOR_VERSION%-register>`_, specifying
 the ``kind`` parameter as ``guest``. They may then interact with the
 client-server API as any other user would, but will only have access to a subset
 of the API as described the Client behaviour subsection below.
@@ -29,13 +29,13 @@ Client behaviour
 The following API endpoints are allowed to be accessed by guest accounts for
 retrieving events:
 
-* `GET /rooms/:room_id/state <#get-matrix-client-api-v1-rooms-roomid-state>`_
+* `GET /rooms/:room_id/state <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state>`_
-* `GET /rooms/:room_id/state/:event_type/:state_key <#get-matrix-client-api-v1-rooms-roomid-state-eventtype-statekey>`_
+* `GET /rooms/:room_id/state/:event_type/:state_key <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype-statekey>`_
-* `GET /rooms/:room_id/messages <#get-matrix-client-api-v1-rooms-roomid-messages>`_
+* `GET /rooms/:room_id/messages <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages>`_
-* `GET /rooms/:room_id/initialSync <#get-matrix-client-api-v1-rooms-roomid-initialsync>`_
+* `GET /rooms/:room_id/initialSync <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync>`_
 
 There is also a special version of the
-`GET /events <#get-matrix-client-api-v1-events>`_ endpoint:
+`GET /events <#get-matrix-client-%CLIENT_MAJOR_VERSION%-events>`_ endpoint:
 
 {{guest_events_http_api}}
 
@@ -47,15 +47,15 @@ receive events for them.
 The following API endpoints are allowed to be accessed by guest accounts for
 sending events:
 
-* `POST /rooms/:room_id/join <#post-matrix-client-api-v1-rooms-roomid-join>`_
+* `POST /rooms/:room_id/join <#post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join>`_
-* `PUT /rooms/:room_id/send/m.room.message/:txn_id <#put-matrix-client-api-v1-rooms-roomid-send-eventtype-txnid>`_
+* `PUT /rooms/:room_id/send/m.room.message/:txn_id <#put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-send-eventtype-txnid>`_
 
 Guest clients *do* need to join rooms in order to send events to them.
 
 The following API endpoints are allowed to be accessed by guest accounts for
 their own account maintenance:
 
-* `PUT /profile/:user_id/displayname <#put-matrix-client-api-v1-profile-userid-displayname>`_
+* `PUT /profile/:user_id/displayname <#put-matrix-client-%CLIENT_MAJOR_VERSION%-profile-userid-displayname>`_
 
 Server behaviour
 ----------------

specification/modules/push.rst

@@ -355,14 +355,14 @@ Examples
 To create a rule that suppresses notifications for the room with ID
 ``!dj234r78wl45Gh4D:matrix.org``::
 
-  curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/v1/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \
+  curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/%CLIENT_MAJOR_VERSION%/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \
   '{
      "actions" : ["dont_notify"]
    }'
 
 To suppress notifications for the user ``@spambot:matrix.org``::
 
-  curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/v1/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \
+  curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/%CLIENT_MAJOR_VERSION%/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \
   '{
      "actions" : ["dont_notify"]
    }'
@@ -370,7 +370,7 @@ To suppress notifications for the user ``@spambot:matrix.org``::
 To always notify for messages that contain the work 'cake' and set a specific
 sound (with a rule_id of ``SSByZWFsbHkgbGlrZSBjYWtl``)::
 
-  curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/v1/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" -d \
+  curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/%CLIENT_MAJOR_VERSION%/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" -d \
   '{
      "pattern": "cake",
      "actions" : ["notify", {"set_sound":"cakealarm.wav"}]
@@ -379,7 +379,7 @@ sound (with a rule_id of ``SSByZWFsbHkgbGlrZSBjYWtl``)::
 To add a rule suppressing notifications for messages starting with 'cake' but
 ending with 'lie', superseding the previous rule::
 
-  curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/v1/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" -d \
+  curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/%CLIENT_MAJOR_VERSION%/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" -d \
   '{
      "pattern": "cake*lie",
      "actions" : ["notify"]
@@ -389,7 +389,7 @@ To add a custom sound for notifications messages containing the word 'beer' in
 any rooms with 10 members or fewer (with greater importance than the room,
 sender and content rules)::
 
-  curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/v1/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456" -d \
+  curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/api/%CLIENT_MAJOR_VERSION%/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456" -d \
   '{
      "conditions": [
        {"kind": "event_match", "key": "content.body", "pattern": "beer" },

specification/modules/receipts.rst

@@ -24,8 +24,8 @@ single ``event_id``.
 Client behaviour
 ----------------
 
-In v1 ``/initialSync``, receipts are listed in a separate top level ``receipts``
+In ``/initialSync``, receipts are listed in a separate top level ``receipts``
-key. In v2 ``/sync``, receipts are contained in the ``ephemeral`` block for a
+key. In ``/sync``, receipts are contained in the ``ephemeral`` block for a
 room. New receipts that come down the event streams are deltas which update
 existing mappings. Clients should replace older receipt acknowledgements based
 on ``user_id`` and ``receipt_type`` pairs. For example::

specification/modules/tags.rst

@@ -11,11 +11,11 @@ Events
 ------
 
 The tags on a room are received as single ``m.tag`` event in the
-``account_data`` section of a room in a v2 /sync.
+``account_data`` section of a room in a ``/sync``.
 
-The ``m.tag`` can also be received in a v1 /events response or in the
+The ``m.tag`` can also be received in a ``/events`` response or in the
-``account_data`` section of a room in v1 /initialSync. ``m.tag``
+``account_data`` section of a room in ``/initialSync``. ``m.tag``
-events appearing in v1 /events will have a ``room_id`` with the room
+events appearing in ``/events`` will have a ``room_id`` with the room
 the tags are for.
 
 Each tag has an associated JSON object with information about the tag, e.g how