diff --git a/README.md b/README.md
index 823ca6f..50d3237 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,8 @@
 # hosted  
 there are a bunch of webservers i host for my personal use, mostly for different parts of my website. im writing a pretty barebones documentation for em here, so you can use them if you find them useful :3  
 
-### naming scheme
+## naming scheme
 i use different hrt terms as a naming scheme for my machines. my main pc is called estrogen, my weak main vps is called bica, and the vps i use to host most of my webservers is called mono (as in monotherapy). so every webserver will most likely be under \<something>.mono.exhq.dev
 
-## dc-lookup.mono.exhq.dev 
-selfhosted [discord lookup api](https://github.com/mesalytic/discord-lookup-api) instance. the documentation can be found in the github  
-**example usage:** `GET https://dc-lookup.mono.exhq.dev/v1/user/712639419785412668`
-
-
-## backendreview.mono.exhq.dev 
-review system i use on my website. this instance will most likely not be useful to you, but [you can selfhost the software if you think its useful to you](https://github.com/exhq/review.exhq.dev)  
-**example usage:** `GET https://backendreview.mono.exhq.dev/getreviews`
-
-## slcache.mono.exhq.dev
-reverse proxied cached api for song.link, since their responses dont have cors set and have a really low ratelimit  
-i have not written any documentation for this api, but if you think it might be useful to you, you can check out [song.link's api docs](https://linktree.notion.site/API-d0ebe08a5e304a55928405eb682f6741) and [the sourcecode for slcache](https://git.lgbt/exhq/slcache)
-**example usage:** `GET http://slcache.mono.exhq.dev/?url=spotify%3Atrack%3A6BJHsLiE47Sk0wQkuppqhr`
\ No newline at end of file
+## endpoints
+see: [wiki](/wiki)
diff --git a/openapi.yaml b/openapi.yaml
new file mode 100644
index 0000000..fffae26
--- /dev/null
+++ b/openapi.yaml
@@ -0,0 +1,283 @@
+openapi: 3.0.0
+info:
+  title: Personal Web Services API
+  description: Documentation for various web services hosted under mono.exhq.dev
+  version: 1.0.0
+
+paths:
+  /v1/user/{userId}:
+    get:
+      tags:
+        - Discord Lookup
+      summary: Look up Discord user information
+      description: Retrieves information about a Discord user using their ID
+      parameters:
+        - name: userId
+          in: path
+          required: true
+          schema:
+            type: string
+          example: "712639419785412668"
+      responses:
+        '200':
+          description: Successful response with user information
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DiscordUser'
+      servers:
+        - url: https://dc-lookup.mono.exhq.dev
+
+  /getreviews:
+    get:
+      tags:
+        - Review System
+      summary: Get reviews
+      description: Retrieves reviews from the backend review system
+      responses:
+        '200':
+          description: Successful response with reviews
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Review'
+      servers:
+        - url: https://backendreview.mono.exhq.dev
+
+  /:
+    get:
+      tags:
+        - Song Link Cache
+      summary: Get cached song.link data
+      description: Cached proxy for song.link API responses with CORS support
+      parameters:
+        - name: url
+          in: query
+          required: true
+          schema:
+            type: string
+          example: "spotify:track:6BJHsLiE47Sk0wQkuppqhr"
+          description: Encoded song URL or identifier
+      responses:
+        '200':
+          description: Cached song.link response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SongLinkResponse'
+      servers:
+        - url: http://slcache.mono.exhq.dev
+
+components:
+  schemas:
+    DiscordUser:
+      type: object
+      properties:
+        id:
+          type: string
+          example: "712639419785412668"
+        created_at:
+          type: string
+          format: date-time
+          example: "2020-05-20T12:14:37.877Z"
+        username:
+          type: string
+          example: "exhq"
+        avatar:
+          $ref: '#/components/schemas/DiscordAvatar'
+        avatar_decoration:
+          type: string
+          nullable: true
+          example: null
+        badges:
+          type: array
+          items:
+            type: string
+          example: ["HOUSE_BALANCE"]
+        accent_color:
+          type: string
+          nullable: true
+          example: null
+        global_name:
+          type: string
+          example: "ECHO 🐈"
+        banner:
+          $ref: '#/components/schemas/DiscordBanner'
+        raw:
+          $ref: '#/components/schemas/DiscordRawData'
+
+    DiscordAvatar:
+      type: object
+      properties:
+        id:
+          type: string
+          example: "93dd1fc1629fb1ec652c68203af4f3f1"
+        link:
+          type: string
+          example: "https://cdn.discordapp.com/avatars/712639419785412668/93dd1fc1629fb1ec652c68203af4f3f1"
+        is_animated:
+          type: boolean
+          example: false
+
+    DiscordBanner:
+      type: object
+      properties:
+        id:
+          type: string
+          nullable: true
+          example: null
+        link:
+          type: string
+          nullable: true
+          example: null
+        is_animated:
+          type: boolean
+          example: false
+        color:
+          type: string
+          nullable: true
+          example: null
+
+    DiscordRawData:
+      type: object
+      properties:
+        id:
+          type: string
+          example: "712639419785412668"
+        username:
+          type: string
+          example: "exhq"
+        avatar:
+          type: string
+          example: "93dd1fc1629fb1ec652c68203af4f3f1"
+        discriminator:
+          type: string
+          example: "0"
+        public_flags:
+          type: integer
+          example: 256
+        flags:
+          type: integer
+          example: 256
+        banner:
+          type: string
+          nullable: true
+          example: null
+        accent_color:
+          type: string
+          nullable: true
+          example: null
+        global_name:
+          type: string
+          example: "ECHO 🐈"
+        avatar_decoration_data:
+          type: string
+          nullable: true
+          example: null
+        banner_color:
+          type: string
+          nullable: true
+          example: null
+        clan:
+          type: string
+          nullable: true
+          example: null
+
+    Review:
+      type: object
+      properties:
+        reviewID:
+          type: integer
+          example: 1
+        discordID:
+          type: string
+          example: "712653921692155965"
+        reviewText:
+          type: string
+          example: "meow"
+        timestamp:
+          type: string
+          example: "1708902649485"
+
+    SongLinkResponse:
+      type: object
+      properties:
+        entityUniqueId:
+          type: string
+          example: "SPOTIFY_SONG::6BJHsLiE47Sk0wQkuppqhr"
+        userCountry:
+          type: string
+          example: "US"
+        pageUrl:
+          type: string
+          example: "https://song.link/s/6BJHsLiE47Sk0wQkuppqhr"
+        entitiesByUniqueId:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/SongEntity'
+        linksByPlatform:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/PlatformLink'
+
+    SongEntity:
+      type: object
+      properties:
+        id:
+          type: string
+          example: "6BJHsLiE47Sk0wQkuppqhr"
+        type:
+          type: string
+          example: "song"
+        title:
+          type: string
+          example: "From the Start"
+        artistName:
+          type: string
+          example: "Good Kid"
+        thumbnailUrl:
+          type: string
+          example: "https://i.scdn.co/image/ab67616d0000b273e67835d0a5d81fa4f268b513"
+        thumbnailWidth:
+          type: integer
+          example: 640
+        thumbnailHeight:
+          type: integer
+          example: 640
+        apiProvider:
+          type: string
+          example: "spotify"
+        platforms:
+          type: array
+          items:
+            type: string
+          example: ["spotify"]
+
+    PlatformLink:
+      type: object
+      properties:
+        country:
+          type: string
+          example: "US"
+        url:
+          type: string
+          example: "https://open.spotify.com/track/6BJHsLiE47Sk0wQkuppqhr"
+        entityUniqueId:
+          type: string
+          example: "SPOTIFY_SONG::6BJHsLiE47Sk0wQkuppqhr"
+        nativeAppUriMobile:
+          type: string
+          example: "spotify:track:6BJHsLiE47Sk0wQkuppqhr"
+        nativeAppUriDesktop:
+          type: string
+          example: "spotify:track:6BJHsLiE47Sk0wQkuppqhr"
+
+tags:
+  - name: Discord Lookup
+    description: Discord user information lookup service
+  - name: Review System
+    description: Backend review system for website
+  - name: Song Link Cache
+    description: Cached proxy for song.link API