> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sdk.anghami.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

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

The **Anghami + OSN+ SDK** is the official public API surface for the Anghami music catalog and OSN+ video library. It is built proto-first — every endpoint is generated from a single set of [Protocol Buffer](https://protobuf.dev) definitions, then projected into Go, TypeScript, Swift, Java (lite), Python, OpenAPI 3.1, and Postman collections.

This documentation covers what the API does, how to authenticate, how the catalog is shaped, and how AI agents can discover and consume it without prior knowledge.

## What you can build

* **Music apps** — browse and stream the full Anghami catalog: songs, albums, artists, playlists, lyrics, charts, and editorial sections.
* **Video apps** — browse and stream the OSN+ library: shows, seasons, episodes, and movies.
* **Cross-content experiences** — uniquely surface the soundtrack of a show or the shows that feature a song through [`SoundtrackService`](/soundtrack).
* **Personal libraries** — read a user's liked songs, saved movies/shows, followed artists, and playback history.
* **Server-to-server integrations** — programmatic access via API key for catalog browsing without user context.
* **AI agents** — point any agent at this API and it can discover the OpenAPI spec, OAuth flow, and an `llms.txt` briefing automatically. See [Agent Discovery](/agent-discovery).

## What's inside

| Area               | Service                                 |
| ------------------ | --------------------------------------- |
| Music catalog      | [`MusicCatalogService`](/music-catalog) |
| Video catalog      | [`VideoCatalogService`](/video-catalog) |
| Search & browse    | [`DiscoveryService`](/music-search)     |
| Cross-content      | [`SoundtrackService`](/soundtrack)      |
| Playlists          | [`PlaylistService`](/playlists)         |
| User library       | [`LibraryService`](/library)            |
| Stream acquisition | `StreamingService` (billable)           |
| User profile       | [`UserService`](/user-service)          |
| OAuth              | `AuthService`                           |
| API key management | [`DeveloperService`](/developer-portal) |

A single bundled OpenAPI 3.1 spec covering every service is generated from the protos and lives at [`/api/anghami-sdk.openapi.yaml`](/api/anghami-sdk.openapi.yaml). Drop it into Postman, Insomnia, or any OpenAPI codegen — one file, every operation.

## Design tenets

* **Proto-first.** `.proto` files are the source of truth. Every client, doc, and HTTP handler is generated.
* **Cursor pagination everywhere.** No offset/limit — see [`PaginationRequest`](/usage-pagination).
* **Typed IDs.** `SongID`, `AlbumID`, `EpisodeID`, etc. — never raw `int64`.
* **Stream acquisition is the billable event.** No separate playback-reporting RPCs — `AcquireMusicStream` and `AcquireVideoStream` are the only events that count.
* **Agent-native.** OpenAPI bundle, `llms.txt`, and a documented OAuth flow let any agent self-onboard.

## Next steps

* [Quickstart](/quickstart) — get a token and make your first call in under five minutes.
* [Architecture](/architecture) — how the SDK is organized and generated.
* [Authentication](/usage-auth) — API key vs OAuth + PKCE.
* [Agent Discovery](/agent-discovery) — point an LLM at the SDK and let it self-configure.