# Anghami + OSN+ SDK

> Public API SDK for Anghami music and OSN+ video streaming. Proto-first, multi-language, agent-ready.

## Docs

- [Agent Discovery](https://docs.sdk.anghami.com/agent-discovery.md): Point any AI agent or codegen tool at the Anghami + OSN+ SDK and have it self-configure — OpenAPI bundle, llms.txt, OAuth metadata, all from well-known URLs.
- [AI Features](https://docs.sdk.anghami.com/ai-features.md): What AI surfaces the SDK exposes today, and what's coming.
- [API Keys](https://docs.sdk.anghami.com/api-keys.md): Lifecycle, rotation, and revocation of server-to-server API keys.
- [ExchangeToken](https://docs.sdk.anghami.com/api-reference/authservice/exchangetoken.md): ExchangeToken exchanges an authorization code for access and refresh tokens.  Uses the OAuth 2.0 Authorization Code + PKCE flow.
- [RefreshToken](https://docs.sdk.anghami.com/api-reference/authservice/refreshtoken.md): RefreshToken obtains a new access token using a refresh token.  The refresh token may be rotated — always use the latest refresh token.
- [RevokeToken](https://docs.sdk.anghami.com/api-reference/authservice/revoketoken.md): RevokeToken invalidates an access or refresh token.  Revoking a refresh token also invalidates all associated access tokens.
- [CreateApiKey](https://docs.sdk.anghami.com/api-reference/developerservice/createapikey.md): CreateApiKey creates a new API key with the specified name and scopes.  Returns the full key secret once — it cannot be retrieved again.
- [GetApiKey](https://docs.sdk.anghami.com/api-reference/developerservice/getapikey.md): GetApiKey retrieves a single API key by ID.  The full secret is never returned — only the key_prefix is visible.
- [ListApiKeys](https://docs.sdk.anghami.com/api-reference/developerservice/listapikeys.md): ListApiKeys retrieves all API keys belonging to the authenticated developer.  Key secrets are never returned — only the key_prefix is shown for identification.
- [RevokeApiKey](https://docs.sdk.anghami.com/api-reference/developerservice/revokeapikey.md): RevokeApiKey permanently deactivates an API key.  Once revoked, the key can no longer be used for authentication.  This action is irreversible.
- [RotateApiKey](https://docs.sdk.anghami.com/api-reference/developerservice/rotateapikey.md): RotateApiKey generates a new secret for an existing API key.  The old key remains valid for a server-defined grace period to allow migration.  Returns the new full secret once — it cannot be retrieved again.
- [UpdateApiKey](https://docs.sdk.anghami.com/api-reference/developerservice/updateapikey.md): UpdateApiKey updates an API key's metadata (e.g. name) using a FieldMask.
- [BrowseCharts](https://docs.sdk.anghami.com/api-reference/discoveryservice/browsecharts.md): BrowseCharts retrieves available popularity charts with preview entries.
- [BrowseFeatured](https://docs.sdk.anghami.com/api-reference/discoveryservice/browsefeatured.md): BrowseFeatured retrieves editorially curated featured sections.  Returns sections like "Made For You", "Trending Now", and other editorial picks.
- [BrowseGenres](https://docs.sdk.anghami.com/api-reference/discoveryservice/browsegenres.md): BrowseGenres retrieves the list of available content genres.
- [BrowseNewReleases](https://docs.sdk.anghami.com/api-reference/discoveryservice/browsenewreleases.md): BrowseNewReleases retrieves recently released content across the catalog.
- [GetChartEntries](https://docs.sdk.anghami.com/api-reference/discoveryservice/getchartentries.md): GetChartEntries retrieves the full paginated entries for a specific chart.
- [GetGenreContent](https://docs.sdk.anghami.com/api-reference/discoveryservice/getgenrecontent.md): GetGenreContent retrieves content items within a specific genre.
- [Search](https://docs.sdk.anghami.com/api-reference/discoveryservice/search.md): Search performs a full-text search across all content types in the catalog.  Results can be filtered by content type and scoped to a specific market.
- [CheckFollowedArtists](https://docs.sdk.anghami.com/api-reference/libraryservice/checkfollowedartists.md): CheckFollowedArtists checks whether the user follows specific artists.  Useful for rendering follow/unfollow toggle state in the UI. Requires the "read" scope.
- [CheckLikedItems](https://docs.sdk.anghami.com/api-reference/libraryservice/checklikeditems.md): CheckLikedItems checks whether specific items are in the user's liked collection.  Useful for rendering like/unlike toggle state in the UI. Requires the "read" scope.
- [CheckSavedItems](https://docs.sdk.anghami.com/api-reference/libraryservice/checksaveditems.md): CheckSavedItems checks whether specific items are in the user's saved collection.  Useful for rendering save/unsave toggle state in the UI. Requires the "read" scope.
- [GetFollowedArtists](https://docs.sdk.anghami.com/api-reference/libraryservice/getfollowedartists.md): GetFollowedArtists retrieves the artists the user follows.  Requires the "read" scope.
- [GetHistory](https://docs.sdk.anghami.com/api-reference/libraryservice/gethistory.md): GetHistory retrieves the user's playback history, optionally filtered by content type.  Requires the "read" scope.
- [GetLikedItems](https://docs.sdk.anghami.com/api-reference/libraryservice/getlikeditems.md): GetLikedItems retrieves the user's liked items (songs and albums only),  optionally filtered by content type. Requires the "read" scope.
- [GetSavedItems](https://docs.sdk.anghami.com/api-reference/libraryservice/getsaveditems.md): GetSavedItems retrieves the user's saved items (movies and shows only),  optionally filtered by content type. Requires the "read" scope.
- [BatchGetAlbums](https://docs.sdk.anghami.com/api-reference/musiccatalogservice/batchgetalbums.md): BatchGetAlbums retrieves multiple albums by their unique identifiers.  Returns a map of ID to result, where each result is either the album or an error.
- [BatchGetArtists](https://docs.sdk.anghami.com/api-reference/musiccatalogservice/batchgetartists.md): BatchGetArtists retrieves multiple artists by their unique identifiers.  Returns a map of ID to result, where each result is either the artist or an error.
- [BatchGetSongs](https://docs.sdk.anghami.com/api-reference/musiccatalogservice/batchgetsongs.md): BatchGetSongs retrieves multiple songs by their unique identifiers.  Returns a map of ID to result, where each result is either the song or an error.
- [GetAlbum](https://docs.sdk.anghami.com/api-reference/musiccatalogservice/getalbum.md): GetAlbum retrieves a single album by its unique identifier.
- [GetAlbumTracks](https://docs.sdk.anghami.com/api-reference/musiccatalogservice/getalbumtracks.md): GetAlbumTracks retrieves the tracks from a specific album.
- [GetArtist](https://docs.sdk.anghami.com/api-reference/musiccatalogservice/getartist.md): GetArtist retrieves a single artist by its unique identifier.
- [GetArtistDiscography](https://docs.sdk.anghami.com/api-reference/musiccatalogservice/getartistdiscography.md): GetArtistDiscography retrieves albums by a specific artist with optional filtering.
- [GetArtistTopTracks](https://docs.sdk.anghami.com/api-reference/musiccatalogservice/getartisttoptracks.md): GetArtistTopTracks retrieves the most popular songs by a specific artist.
- [GetLyrics](https://docs.sdk.anghami.com/api-reference/musiccatalogservice/getlyrics.md): GetLyrics retrieves the lyrics for a specific song.  Returns time-synchronized lyrics when available, otherwise plain text.
- [GetRelatedArtists](https://docs.sdk.anghami.com/api-reference/musiccatalogservice/getrelatedartists.md): GetRelatedArtists retrieves artists similar to a specific artist.
- [GetSong](https://docs.sdk.anghami.com/api-reference/musiccatalogservice/getsong.md): GetSong retrieves a single song by its unique identifier.
- [GetPlaylist](https://docs.sdk.anghami.com/api-reference/playlistservice/getplaylist.md): GetPlaylist retrieves a playlist by ID along with its paginated items.  Accessible with either an API key (public playlists) or OAuth token.
- [GetUserPlaylists](https://docs.sdk.anghami.com/api-reference/playlistservice/getuserplaylists.md): GetUserPlaylists retrieves the authenticated user's playlists.  Requires an OAuth access token with the "read" scope.
- [GetAssociatedContent](https://docs.sdk.anghami.com/api-reference/soundtrackservice/getassociatedcontent.md): GetAssociatedContent retrieves shows and movies that feature a specific song.  Returns paginated video content entries for "featured in" display.
- [GetSoundtrack](https://docs.sdk.anghami.com/api-reference/soundtrackservice/getsoundtrack.md): GetSoundtrack retrieves the list of songs featured in a show or movie.  Returns paginated song entries for soundtrack display.
- [AcquireMusicStream](https://docs.sdk.anghami.com/api-reference/streamingservice/acquiremusicstream.md): AcquireMusicStream acquires a stream URL for playing a song.  This is the billable event for music playback.
- [AcquireVideoStream](https://docs.sdk.anghami.com/api-reference/streamingservice/acquirevideostream.md): AcquireVideoStream acquires a stream URL for playing a video (episode or movie).  This is the billable event for video playback.
- [GetCurrentUser](https://docs.sdk.anghami.com/api-reference/userservice/getcurrentuser.md): GetCurrentUser retrieves the profile of the currently authenticated user.
- [BatchGetEpisodes](https://docs.sdk.anghami.com/api-reference/videocatalogservice/batchgetepisodes.md): BatchGetEpisodes retrieves multiple episodes by their unique identifiers.  Returns a map of ID to result, where each result is either the episode or an error.
- [BatchGetMovies](https://docs.sdk.anghami.com/api-reference/videocatalogservice/batchgetmovies.md): BatchGetMovies retrieves multiple movies by their unique identifiers.  Returns a map of ID to result, where each result is either the movie or an error.
- [BatchGetSeasons](https://docs.sdk.anghami.com/api-reference/videocatalogservice/batchgetseasons.md): BatchGetSeasons retrieves multiple seasons by their unique identifiers.  Returns a map of ID to result, where each result is either the season or an error.
- [BatchGetShows](https://docs.sdk.anghami.com/api-reference/videocatalogservice/batchgetshows.md): BatchGetShows retrieves multiple shows by their unique identifiers.  Returns a map of ID to result, where each result is either the show or an error.
- [GetEpisode](https://docs.sdk.anghami.com/api-reference/videocatalogservice/getepisode.md): GetEpisode retrieves a single episode by its unique identifier.
- [GetMovie](https://docs.sdk.anghami.com/api-reference/videocatalogservice/getmovie.md): GetMovie retrieves a single movie by its unique identifier.
- [GetSeason](https://docs.sdk.anghami.com/api-reference/videocatalogservice/getseason.md): GetSeason retrieves a single season by its unique identifier.  Returns the season with its paginated episode list.
- [GetShow](https://docs.sdk.anghami.com/api-reference/videocatalogservice/getshow.md): GetShow retrieves a single show by its unique identifier.  Returns the show with season summaries for navigation.
- [Architecture](https://docs.sdk.anghami.com/architecture.md): How the SDK is organized — proto sources, build pipeline, and the generated artifacts you actually consume.
- [Authentication (Developer Reference)](https://docs.sdk.anghami.com/authentication.md): Implementation-level reference for OAuth + PKCE and API key authentication. See Usage / Authentication for the user-facing guide.
- [Changelog](https://docs.sdk.anghami.com/changelog.md): Notable changes to the SDK — proto evolution, generated-client releases, and API behavior.
- [Content Model](https://docs.sdk.anghami.com/content-model.md): Typed IDs, the Content wrapper, and how music and video entities relate.
- [Contributing](https://docs.sdk.anghami.com/contributing.md): How to propose changes to the SDK — proto-first workflow, conventions, and CI gates.
- [CORS](https://docs.sdk.anghami.com/cors.md): CORS posture for the public API and what's allowed from the browser.
- [Developer Portal](https://docs.sdk.anghami.com/developer-portal.md): How developers register, manage API keys, and operate against the SDK.
- [Health Endpoints](https://docs.sdk.anghami.com/health-endpoints.md): Liveness and readiness checks for monitoring SDK availability.
- [Introduction](https://docs.sdk.anghami.com/introduction.md): Public API SDK for Anghami music and OSN+ video streaming. Proto-first, multi-language, agent-ready.
- [Library](https://docs.sdk.anghami.com/library.md): The authenticated user's liked songs/albums, saved movies/shows, followed artists, and playback history.
- [License](https://docs.sdk.anghami.com/license.md): License terms for the SDK source and generated clients.
- [llms.txt](https://docs.sdk.anghami.com/llms-txt.md): The LLM-friendly briefing file at /.well-known/llms.txt — what's in it, how to use it.
- [Music Catalog](https://docs.sdk.anghami.com/music-catalog.md): Songs, albums, artists, and lyrics — the read-only Anghami music surface.
- [Search & Browse](https://docs.sdk.anghami.com/music-search.md): Full-text search plus editorial browsing — featured sections, new releases, charts, genres.
- [OAuth Scopes](https://docs.sdk.anghami.com/oauth-scopes.md): What each scope grants and how to request the right ones.
- [Platform Overview](https://docs.sdk.anghami.com/overview.md): What the Anghami + OSN+ SDK exposes, who it's for, and how the services compose.
- [Playlists](https://docs.sdk.anghami.com/playlists.md): Read playlists and the authenticated user's own playlist library.
- [Quickstart](https://docs.sdk.anghami.com/quickstart.md): Get an API key, make your first request, and acquire a music stream in under five minutes.
- [Soundtrack](https://docs.sdk.anghami.com/soundtrack.md): Bidirectional cross-content linking between music and video — the unique Anghami + OSN+ value proposition.
- [Streaming & Billing](https://docs.sdk.anghami.com/streaming-billing.md): Stream acquisition is the billable event. No separate playback reporting. Here is the contract.
- [Authentication](https://docs.sdk.anghami.com/usage-auth.md): API key for server-to-server access, OAuth 2.0 + PKCE for user-scoped access.
- [Errors](https://docs.sdk.anghami.com/usage-errors.md): Structured error responses, error codes, and field-level validation feedback.
- [Pagination](https://docs.sdk.anghami.com/usage-pagination.md): Cursor-based pagination via PaginationRequest / PaginationResponse — no offsets, no skips, no missed records.
- [Rate Limits](https://docs.sdk.anghami.com/usage-rate-limits.md): Per-key and per-user limits, response headers, and back-off strategy.
- [User Profile](https://docs.sdk.anghami.com/user-service.md): Read the authenticated user's profile.
- [Versioning](https://docs.sdk.anghami.com/versioning.md): Proto package versioning, backwards compatibility, and the deprecation policy.
- [Video Catalog](https://docs.sdk.anghami.com/video-catalog.md): OSN+ video — shows, seasons, episodes, and movies.

## OpenAPI Specs

- [anghami-sdk.openapi](https://docs.sdk.anghami.com/api/anghami-sdk.openapi.yaml)
- [openapi](https://docs.sdk.anghami.com/api-reference/openapi.json)