Quickstart

This walkthrough takes you from zero to a working playback URL.

1. Get credentials

You need either an API key (server-to-server) or an OAuth access token (user-scoped).

API key — register at the Developer Portal, create a key in the dashboard, and copy the secret (shown once).
OAuth — use the standard OAuth 2.0 Authorization Code + PKCE flow. See Authentication.

export ANGHAMI_API_KEY="ang_live_..."

2. Browse the catalog

Hit a public catalog endpoint with your API key. Reads are GET:

curl -sS "https://sdk.anghami.com/v1/discovery/browse/featured" \
  -H "x-api-key: $ANGHAMI_API_KEY" | jq '.sections[0]'

You’ll get back curated featured sections (think “Made For You”, “Trending Now”). Single-resource reads are GET; batch reads (:batchGet) and stream acquisition are POST with a JSON body.

3. Search for a song

curl -sS "https://sdk.anghami.com/v1/discovery/search?query=Fairouz&page_size=5" \
  -H "x-api-key: $ANGHAMI_API_KEY" | jq '.results[].content.title'

The response is a paginated list of Content wrappers — a generic envelope with a typed oneof id and display fields.

4. Acquire a stream

Stream acquisition requires an OAuth access token with the stream scope — this is the billable event. With a valid token:

curl -sS https://sdk.anghami.com/v1/streaming/music \
  -H "Authorization: Bearer $ANGHAMI_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"song_id":{"value":"123456"},"quality":"STREAM_QUALITY_HIGH"}' | jq

The response carries a time-limited stream URL plus DRM metadata where applicable. Re-acquire when the URL expires.

5. Generate a typed client

Every release ships clients in the languages we support — pull them directly from the repo:

Language	Package
Go	`github.com/anghami/sdk/api`
TypeScript	`@anghami/sdk`
Swift	`AnghamiSDK` (SPM)
Java	`com.anghami:anghami-sdk`
Python	`anghami-sdk`

If you’d rather generate your own from the bundled spec:

curl -sS https://docs.sdk.anghami.com/api/anghami-sdk.openapi.yaml -o anghami-sdk.openapi.yaml
npx @openapitools/openapi-generator-cli generate \
  -i anghami-sdk.openapi.yaml -g typescript-fetch -o ./client

Architecture — what the build pipeline produces and why.
Usage / Authentication — full OAuth + PKCE walkthrough.
Music Catalog — browse songs, albums, artists, lyrics.
Streaming & Billing — what counts as a billable event.

Getting Started

Usage

Platform & Features

Music

Video & Soundtrack

User & Developer

AI & Agents

Developer Guide

Legal

1. Get credentials

2. Browse the catalog

3. Search for a song

4. Acquire a stream

5. Generate a typed client

Next

​1. Get credentials

​2. Browse the catalog

​3. Search for a song

​4. Acquire a stream

​5. Generate a typed client

​Next

1. Get credentials

2. Browse the catalog

3. Search for a song

4. Acquire a stream

5. Generate a typed client

Next