Developer Docs

API Access دستاویزات

یہ صفحہ production استعمال کے لیے API key flow، سیکیورٹی rules، endpoint catalog، اور testing standards واضح کرتا ہے۔ Production API base URL: https://api.sarafa.pk

API Key بنائیں 5-minute quickstart ڈیولپر ہوم

Learn

How the API works

Three steps: log in to get a JWT, create an API key, then call city rate endpoints with X-API-Key. Base URL is fixed — only the path and query change.

Production base URL: https://api.sarafa.pk

1
Login
POST /auth/v2/login with phone + password → JWT.
2
Create key
POST /api-keys/ with Bearer JWT → raw key (shown once).
3
Call rates
GET public-rates with X-API-Key + X-Client-Platform.

API key صرف authenticated user بنا سکتا ہے۔
API key صرف city-wise gold/silver rate endpoints (single-city اور multi-city) کے لیے valid ہے۔
ہر request میں X-API-Key header لازمی ہے اور production API host https://api.sarafa.pk استعمال کریں۔
Web clients کے لیے allowed website origins شامل کریں اور web platform فعال رکھیں۔
Mobile/server clients کے لیے X-Client-Platform: mobile یا server استعمال کریں۔

Quickstart — first 200 in 5 minutes

Copy, paste, replace the placeholders. Works from any terminal.

bash

# 1) Login (get JWT)
curl -X POST "https://api.sarafa.pk/api/v1/auth/v2/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=03001234567&password=YourPassword"

# 2) Create API key
curl -X POST "https://api.sarafa.pk/api/v1/api-keys/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Backend Server Key"}'

# 3) First rate call
curl -X GET "https://api.sarafa.pk/api/v1/public-rates/gold/cities/karachi" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

Setup

Create & manage keys

Keys live here when you are signed in. Raw key is shown once — store it as a secret.

API access workspace لوڈ ہو رہا ہے...

Authentication

Two credentials, two jobs: JWT manages keys, X-API-Key reads rates.

Bearer JWT

Key management only: create, list, update, revoke, usage. Never send it to rate endpoints.

X-API-Key + X-Client-Platform

Rate endpoints only. Platform is server | mobile | web. Web requests are checked against allowed origins via the Origin header.

Multi-city call کے لیے slugs query param میں comma-separated city slugs دیں (زیادہ سے زیادہ 50).
روزانہ quota ہر key پر enforce ہوتا ہے (exceed ہونے پر 429).
Raw key صرف create کے وقت دکھایا جاتا ہے۔

Endpoints

Gold rates

Single-city سونے کی قیمت (پٹھور کے لیے ?include_pathoor=true)

GET

/api/v1/public-rates/gold/cities/{location_slug}

Auth: X-API-Key

One city's 24K tola rate with city adjustment and calculation version.

Request

curl -X GET "https://api.sarafa.pk/api/v1/public-rates/gold/cities/karachi" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

Response

{
  "metal": "gold",
  "city": "Karachi",
  "slug": "karachi",
  "rate_24k_tola": 461300,
  "adjustment": -200,
  "adjustment_percent": 0.04,
  "calculation_version": "2026.09.pathoor.v1",
  "currency": "PKR"
}

GET

/api/v1/public-rates/gold/cities?slugs={karachi,lahore}

Auth: X-API-Key

Up to 50 cities per call. Returns requested_count, count, data[], not_found[].

Request

curl -X GET "https://api.sarafa.pk/api/v1/public-rates/gold/cities?slugs=karachi,lahore,islamabad" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: mobile"

Silver rates

Same shape as gold, 999-pure base.

GET

/api/v1/public-rates/silver/cities/{location_slug}

Auth: X-API-Key

Single-city چاندی کی قیمت

Request

curl -X GET "https://api.sarafa.pk/api/v1/public-rates/silver/cities/lahore" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

GET

/api/v1/public-rates/silver/cities?slugs={karachi,lahore}

Auth: X-API-Key

Multi-city چاندی کی قیمتیں

Request

curl -X GET "https://api.sarafa.pk/api/v1/public-rates/silver/cities?slugs=karachi,lahore,islamabad" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: mobile"

Pathoor Gold (opt-in)

Local 24K, Rs. 5,500 below 24K Piece Gold. Off by default to keep payloads small — add ?include_pathoor=true only when you need it.

GET

/api/v1/public-rates/gold/cities/karachi?include_pathoor=true

adds rate_pathoor_tola

Auth: X-API-Key

Single-city with Pathoor. Multi-city works the same: ?slugs=karachi,lahore&include_pathoor=true.

Request

curl -X GET "https://api.sarafa.pk/api/v1/public-rates/gold/cities/karachi?include_pathoor=true" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

Response

{
  "metal": "gold",
  "city": "Karachi",
  "slug": "karachi",
  "rate_24k_tola": 461300,
  "rate_pathoor_tola": 455800,
  "adjustment": -200,
  "adjustment_percent": 0.04,
  "calculation_version": "2026.09.pathoor.v1",
  "currency": "PKR"
}

Fuel prices (paid plans only)

API-only — fuel rates are not shown on the Sarafa.pk website. Free-plan keys get 403; Starter and higher get 200. Pakistan comes from PSO (city-level Octane+, refreshed every 30 min); 168 countries come from OpenVan.camp.

GET

/api/v1/public-rates/fuel/pakistan

403 on free plan

Auth: X-API-Key (paid)

PSO retail: Premier, Hi-Cetane Diesel, Octane+ per city, LDO/SKO/JP-1, LPG. Optional ?product=premier&city=karachi filters.

Request

curl -X GET "https://api.sarafa.pk/api/v1/public-rates/fuel/pakistan?product=octane_plus&city=karachi" \
  -H "X-API-Key: YOUR_PAID_API_KEY" \
  -H "X-Client-Platform: server"

Response

{
  "country": "Pakistan",
  "country_code": "PK",
  "count": 1,
  "data": [{
    "product": "octane_plus",
    "city": "Karachi",
    "price": 370,
    "unit": "Ltr",
    "effective_from": "2026-09-02"
  }],
  "source": "psopk"
}

GET

/api/v1/public-rates/fuel/international?country=DE

168 countries

Auth: X-API-Key (paid)

Omit ?country for all countries (lean rows). Per-country returns full prices, changes, sources, attribution.

Request

curl -X GET "https://api.sarafa.pk/api/v1/public-rates/fuel/international?country=DE" \
  -H "X-API-Key: YOUR_PAID_API_KEY" \
  -H "X-Client-Platform: server"

GraphQL alternative

Same data, field-selective. Pathoor is opt-in here too.

GraphQL

query {
  goldRates(citySlug: "karachi", includePathoor: true) {
    cityRate { city slug rate24kTola ratePathoorTola calculationVersion }
  }
}

Reference

Limits & headers

Quota is per key, per day. Every rate response carries the headers below.

Header	Meaning
X-RateLimit-Limit-Day	روزانہ quota
X-RateLimit-Remaining-Day	آج باقی requests
X-RateLimit-Reset	Reset timestamp

X-Client-Platform: server | mobile | web
Web requests میں Origin header کو allowed origins کے خلاف validate کیا جاتا ہے۔
Mobile اور server requests میں عموماً Origin نہیں ہوتا، اس لیے X-Client-Platform سیٹ کریں۔

Test

Try it live

Paste a key, pick gold or silver, toggle Pathoor, and hit the real API without leaving this page.

Live API Tester

اپنی API key کے ساتھ production API host (https://api.sarafa.pk) پر live request چلا کر status، rate-limit headers، اور response payload دیکھیں۔

cURL

curl -X GET "https://api.sarafa.pk/api/v1/public-rates/gold/cities/karachi" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

Error Contract

All errors return { "detail": "message" }.

Status	Meaning
401	Missing/invalid auth یا API key
403	Key revoked/disabled/forbidden
404	City یا key resource نہیں ملا
429	روزانہ limit exceed ہو گئی

Testing Checklist (Production QA)

JWT login کے بعد API key creation کامیاب ہو۔
Raw key صرف create response میں آئے، list endpoint میں نہیں۔
Web requests پر origin allowlist نافذ ہو۔
Platform restrictions غیر مجاز client types کو بلاک کریں۔
Valid key کے ساتھ gold/silver city endpoints 200 دیں۔
Multi-city endpoints میں requested_count، count، data، not_found درست آئیں۔
Invalid/missing key پر 401 آئے۔
Revoked key پر 403 آئے۔
Daily quota exceed ہونے پر 429 اور reset header آئے۔
Usage endpoint میں آج کے hits اور remaining quota درست ہوں۔
High-concurrency میں limit bypass نہ ہو۔

# 1) Login (get JWT) curl -X POST "https://api.sarafa.pk/api/v1/auth/v2/login" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=03001234567&password=YourPassword" # 2) Create API key curl -X POST "https://api.sarafa.pk/api/v1/api-keys/" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"Backend Server Key"}' # 3) First rate call curl -X GET "https://api.sarafa.pk/api/v1/public-rates/gold/cities/karachi" \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-Client-Platform: server"

{ "metal": "gold", "city": "Karachi", "slug": "karachi", "rate_24k_tola": 461300, "adjustment": -200, "adjustment_percent": 0.04, "calculation_version": "2026.09.pathoor.v1", "currency": "PKR" }

{ "metal": "gold", "city": "Karachi", "slug": "karachi", "rate_24k_tola": 461300, "rate_pathoor_tola": 455800, "adjustment": -200, "adjustment_percent": 0.04, "calculation_version": "2026.09.pathoor.v1", "currency": "PKR" }

{ "country": "Pakistan", "country_code": "PK", "count": 1, "data": [{ "product": "octane_plus", "city": "Karachi", "price": 370, "unit": "Ltr", "effective_from": "2026-09-02" }], "source": "psopk" }

Header

Meaning

X-RateLimit-Limit-Day

روزانہ quota

X-RateLimit-Remaining-Day

آج باقی requests

X-RateLimit-Reset

Reset timestamp

Live API Tester

اپنی API key کے ساتھ production API host (https://api.sarafa.pk) پر live request چلا کر status، rate-limit headers، اور response payload دیکھیں۔

cURL

curl -X GET "https://api.sarafa.pk/api/v1/public-rates/gold/cities/karachi" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Client-Platform: server"

Status

Meaning

401

Missing/invalid auth یا API key

403

Key revoked/disabled/forbidden

404

City یا key resource نہیں ملا

429

روزانہ limit exceed ہو گئی