Developer Docs

API Access Documentation

This page defines the production API key flow, security rules, endpoint catalog, and testing standards. Production API base URL: https://api.sarafa.pk

Create API Key 5-minute quickstart Developer Home

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.

Only authenticated users can create API keys.
API keys are valid only for city-wise gold/silver rate endpoints (single-city and multi-city).
Every request must include X-API-Key header and use the production API host https://api.sarafa.pk.
For web clients, configure allowed website origins and keep web platform enabled.
For mobile/server clients, use X-Client-Platform: mobile or 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.

Loading 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.

For multi-city calls, pass comma-separated city slugs in slugs query param (maximum 50).
Daily quota is enforced per key (429 on exceed).
Raw key is shown only once during creation.

Endpoints

Gold rates

Single-city gold rate (optional ?include_pathoor=true for Pathoor)

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 silver rate

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 silver rates

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	Daily quota
X-RateLimit-Remaining-Day	Remaining requests today
X-RateLimit-Reset	Reset timestamp

X-Client-Platform: server | mobile | web
Web requests are validated against allowed origins using the Origin header.
Mobile and server requests should set X-Client-Platform and usually do not send Origin.

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

Test your API key with a real request against the production API host (https://api.sarafa.pk) and inspect status, rate-limit headers, and 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 or API key
403	Key revoked/disabled/forbidden
404	City or key resource not found
429	Daily limit exceeded

Testing Checklist (Production QA)

API key creation succeeds after JWT login.
Raw key appears only in create response, never in list endpoint.
Origin allowlist is enforced for web requests.
Platform restrictions block disallowed client types.
Gold/silver city endpoints return 200 with valid key.
Multi-city endpoints return correct requested_count, count, data, and not_found.
Missing/invalid key returns 401.
Revoked key returns 403.
429 is returned when daily quota is exceeded with reset header.
Usage endpoint reports accurate today hits and remaining quota.
No quota bypass under high concurrency.

# 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

Daily quota

X-RateLimit-Remaining-Day

Remaining requests today

X-RateLimit-Reset

Reset timestamp

Live API Tester

Test your API key with a real request against the production API host (https://api.sarafa.pk) and inspect status, rate-limit headers, and 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 or API key

403

Key revoked/disabled/forbidden

404

City or key resource not found

429

Daily limit exceeded