From 4e4adcd601dd71f8d936589b95db8858ae655205 Mon Sep 17 00:00:00 2001
From: Raymond Jacobson <ray@audius.co>
Date: Fri, 6 Mar 2026 15:54:46 -0800
Subject: [PATCH] Add details to the api overview

---
 api/swagger/swagger-v1.yaml | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/api/swagger/swagger-v1.yaml b/api/swagger/swagger-v1.yaml
index 19dd343d..9df806e5 100644
--- a/api/swagger/swagger-v1.yaml
+++ b/api/swagger/swagger-v1.yaml
@@ -1,9 +1,40 @@
 openapi: 3.0.1
 info:
-  title: API
-  description: Audius V1 API
+  title: Audius API
+  description: |
+    ## Overview
+
+    The Audius API provides REST access to the world's largest open music catalog, built on the [Open Audio Protocol](https://openaudio.org). Use it to query and stream tracks, users, playlists, and more—perfect for building music players, discovery apps, and audio-native products.
+
+    ## Key Capabilities
+
+    - **Users** — Profiles, followers, following, search
+    - **Tracks** — Search, trending, stream, favorites, reposts
+    - **Playlists** — Create, update, browse, curate
+    - **Resolve** — Look up content by Audius canonical URLs (e.g. `audius.co/artist/...`)
+    - **Explore** — Trending content, charts, discovery
+    - **Comments, Tips, Rewards** — Social features and engagement
+
+    ## Authentication
+
+    - **Read-only** — Most endpoints work without credentials. Use an API key for higher rate limits.
+    - **Writes** — Upload, favorite, repost, and other mutations require an API key and secret. Get keys at [api.audius.co/plans](https://api.audius.co/plans) or [audius.co/settings](https://audius.co/settings).
+
+    ## Resources
+
+    - [API Docs](https://docs.audius.co/api) — Full reference and guides
+    - [API Plans](https://api.audius.co/plans) — Get API keys (free tier available)
+    - [Log in with Audius](https://docs.audius.co/developers/guides/log-in-with-audius) — OAuth for user actions
+    - [JavaScript SDK](https://www.npmjs.com/package/@audius/sdk) — `@audius/sdk` for Node and browser
   version: "1.0"
+  contact:
+    name: Audius
+    url: https://audius.co
+  x-logo:
+    url: https://audius.co/favicon.ico
 servers:
+  - url: https://api.audius.co/v1
+    description: Production
   - url: /v1
 tags:
   - name: users