diff --git a/docs/specs/schema.yml b/docs/specs/schema.yml
new file mode 100644
index 000000000..d50ebbaf4
--- /dev/null
+++ b/docs/specs/schema.yml
@@ -0,0 +1,103 @@
+openapi: 3.1.0
+info:
+  description: "Interactive documentation for [Funkwhale](https://funkwhale.audio) API."
+  version: "2.0.0"
+  title: "Funkwhale API"
+servers:
+  - url: "https://demo.funkwhale.audio"
+    description: "Demo server"
+  - url: "https://open.audio"
+    description: "Real server with real content"
+  - url: "https://{domain}"
+    description: "Custom server"
+    variables:
+      domain:
+        default: yourdomain
+        description: "Your Funkwhale Domain"
+      protocol:
+        enum:
+          - "http"
+          - "https"
+        default: "https"
+tags:
+  - name: Users
+paths:
+  /api/v2/users:
+    $ref: "users/schema.yml#/paths/~1users"
+components:
+  parameters:
+    PageParam:
+      name: page
+      in: query
+      required: false
+      description: The number of the result page you want to return
+      schema:
+        type: number
+        format: integer
+    PageSizeParam:
+      name: page_size
+      in: query
+      required: false
+      description: The number of results to return on each page. Defaults to 50.
+      schema:
+        type: number
+        default: 50
+    Query:
+      name: q
+      in: query
+      required: false
+      description: A free text field to filter results
+      schema:
+        type: string
+  schemas:
+    ImageUrls:
+      type: object
+      description: "Metadata and file links for the object's associated art"
+      required:
+        - guid
+        - mimetype
+        - size
+        - creationDate
+        - urls
+      properties:
+        guid:
+          type: string
+          format: uuid
+          description: "The unique ID of the cover"
+        mimetype:
+          type: string
+          description: "The data type (filetype) of the cover file"
+        size:
+          type: integer
+          description: "The size of the file"
+        creationDate:
+          type: string
+          format: date-time
+          description: "The date and time on which the cover object was created"
+        urls:
+          type: object
+          description: "All URLs associated with the cover"
+          required:
+            - original
+          properties:
+            source:
+              type: string
+              format: url
+              description: "The source of the cover"
+            original:
+              type: string
+              format: url
+              description: "The upload in its original size and format"
+    Pagination:
+      type: object
+      required:
+        - total
+      properties:
+        total:
+          type: integer
+        next:
+          type: string
+          format: url
+        previous:
+          type: string
+          format: url
diff --git a/docs/specs/users/schema.yml b/docs/specs/users/schema.yml
new file mode 100644
index 000000000..0a7a79d71
--- /dev/null
+++ b/docs/specs/users/schema.yml
@@ -0,0 +1,131 @@
+paths:
+  /users:
+    get:
+      tags:
+        - Users
+      summary: "Fetch a list of users"
+      description: "Fetch a list of users from the server"
+      operationId: getUsers
+      parameters:
+        - $ref: "../schema.yml#/components/parameters/Query"
+        - $ref: "../schema.yml#/components/parameters/PageParam"
+        - $ref: "../schema.yml#/components/parameters/PageSizeParam"
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: "../schema.yml#/components/schemas/Pagination"
+                  - type: object
+                    required:
+                      - results
+                    properties:
+                      results:
+                        type: array
+                        items:
+                          $ref: "#/components/schemas/SimpleUser"
+              example:
+                total: 1
+                results:
+                  - guid: "eaf72973-b62b-45ed-8549-f427919e6555"
+                    username: "betterraves"
+                    preferredUsername: "betterraves"
+                    domain: "https://open.audio"
+                    name: "Agate"
+components:
+  schemas:
+    SimpleUser:
+      type: object
+      required:
+        - guid
+        - username
+        - preferredUsername
+        - domain
+      properties:
+        guid:
+          type: string
+          format: uuid
+          description: "The unique ID of the user"
+        username:
+          type: string
+          description: "The user's account username"
+        preferredUsername:
+          type: string
+          description: "The username displayed on the user's profile"
+        domain:
+          type: string
+          format: url
+          description: "The domain the user belongs to"
+        name:
+          type: string
+          description: "The user's real name"
+    User:
+      allOf:
+        - $ref: "#/components/schemas/SimpleUser"
+        - type: object
+          properties:
+            createdDate:
+              type: string
+              format: date-time
+              description: "The date and time the user profile was created"
+            summary:
+              type: string
+              format: html
+              description: "A brief summary of the user"
+            avatar:
+              $ref: "../schema.yml#/components/schemas/ImageUrls"
+    SimpleActor:
+      type: object
+      required:
+        - fid
+        - preferredUsername
+        - fullUsername
+        - local
+        - domain
+      properties:
+        fid:
+          type: string
+          format: url
+          description: "The federation ID of the actor"
+        fullUsername:
+          type: string
+          description: "The username and domain of the actor"
+        preferredUsername:
+          type: string
+          description: "The user-selected preferred username"
+        name:
+          type: string
+          description: "The name of the actor"
+        domain:
+          type: string
+          description: "The domain the actor is associated with"
+        local:
+          type: boolean
+          description: "Whether the actor belongs to the server serving the request"
+    Actor:
+      allOf:
+        - $ref: "#/components/schemas/SimpleActor"
+        - type: object
+          properties:
+            lastFetchDate:
+              type: string
+              format: date-time
+              description: "The date and time on which the server last fetched information about the actor"
+            manuallyApprovesFollowers:
+              type: boolean
+              description: "Whether the user manually approves followers"
+            type:
+              type: string
+              description: "The type of ActivityPub actor the object represents"
+              enum:
+                - person
+                - tombstone
+                - application
+                - group
+                - organization
+                - service
+            url:
+              type: string
+              format: url