API guide

Everything a developer or an AI agent needs, on one page: get a key, call the REST API or the MCP connector, read the answer and cite it.

هذا الدليل بالإنجليزية لأنه موجّه للمطورين والوكلاء الأذكياء. لأي سؤال بالعربية راسلنا على data@fast.sa.

Quick start

Get a key. Fill in the form at https://source.fast.sa/#key. During v0 we issue keys by hand and email them; a key starts with sdl_live_. Keep it secret.

Call the API with the key in the Authorization header:

curl -H "Authorization: Bearer $SDL_KEY" \
  "https://source.fast.sa/v1/calendar/convert?gregorian=2026-10-23"

Use data, cite citations. Every answer says where it came from. Show the source and its link with the answer, and keep any notice.
Handle errors by their code (table below). After 429 rate_limited, wait the Retry-After seconds and try again.

No key yet? The MCP connector needs none.

Base URL and versions

Base URL: https://source.fast.sa. This is v0: paths start with /v1/ and every answer carries "meta": {"version": "v0"}. We may add fields; existing fields keep their meaning.

Authentication

Every /v1/ call needs the header Authorization: Bearer sdl_live_… (the prefix plus 32 characters). A missing, unknown or revoked key gets 401 unauthorized. We store only a hash of your key, so we cannot show it again: if you lose it, ask for a new one.

Answer format

Every successful answer, REST or MCP, has the same shape:

{
  "data": { … },
  "citations": [
    {
      "source": "Saudi Building Code 2024 catalogue (sbc.gov.sa)",
      "url": "https://www.sbc.gov.sa/En/BC/Pages/BuildingCode/BC.aspx?year=2024",
      "checked_at": "2026-10-23T10:00:00.000Z",
      "licence": "Facts only: code numbers, names and editions",
      "notice": "Full text sold by the Saudi Building Code Center"
    }
  ],
  "meta": { "shelf": "standards", "version": "v0" }
}

data: the answer itself, an object or a list.
citations: one entry per source used: source (who published it), url, checked_at (when we last checked that source), licence, and a notice when the source asks for one.
notice: present when a whole shelf needs one.
meta: the shelf that answered and the API version.

Field names are snake_case. Dates are YYYY-MM-DD, timestamps are ISO 8601 in UTC, and times of day (prayer times) are Asia/Riyadh.

Errors

{"error": {"code": "not_found", "message": "No standard with that id"}}

Code	HTTP	Meaning and what to do
`bad_request`	400	A parameter is missing or invalid; the message names it. Fix the request.
`out_of_range`	400	The date or year is outside the data we hold (Hijri 1300 to 1600 AH; holidays for 2026 and 2027). Ask within range.
`unauthorized`	401	No key, an unknown key or a revoked key. Check the header.
`not_found`	404	No such endpoint, record or article. Check the path and the id.
`quota_exceeded`	429	This month's calls are used up. They reset on the 1st (Riyadh time); email us if you need more.
`rate_limited`	429	Too many requests at once. Wait the `Retry-After` seconds.
`internal_error`	500	Our fault. Try again later, and tell us if it keeps happening.

Limits

Free plan: 250 counted calls per calendar month, Asia/Riyadh time. /v1/usage shows what you have used.
/v1/sources and /v1/usage are not counted either.
Up to 10 requests a second per key, and 30 a second from one IP address.
Answers are bounded: at most 50 results per call.
MCP connector: up to 60 requests a minute per IP address.

Endpoints

All endpoints are GET and answer JSON. Full schemas: /openapi.json (OpenAPI 3.1).

`GET /v1/calendar/convert`

Convert a date between Gregorian and Hijri (Umm al-Qura) Counts toward the monthly quota

gregorian query, optional date, YYYY-MM-DD
hijri query, optional date, YYYY-MM-DD

`GET /v1/calendar/prayer-times`

Prayer times for a Saudi city or coordinates (Umm al-Qura method, Asia/Riyadh time) Counts toward the monthly quota

city query, optional text
lat query, optional number
lng query, optional number
date query, optional date, YYYY-MM-DD

`GET /v1/calendar/holidays`

Official holidays by sector, each with the regulation it comes from. Counts toward the monthly quota

year query, optional integer
sector query, optional one of government, private

`GET /v1/calendar/working-day`

Whether a date is a working day for a sector, and why. Counts toward the monthly quota

date query, optional date, YYYY-MM-DD
sector query, required one of government, private

`GET /v1/standards/search`

Search Saudi standards and building codes by number or title (facts and where to buy, never the text) Counts toward the monthly quota

q query, required text
body query, optional one of SASO, SBC
kind query, optional one of standard, technical_regulation, building_code
limit query, optional integer 1–50, default 10

`GET /v1/standards/{id}`

One standard's facts: titles, edition, what it adopts, where to read or buy it. Counts toward the monthly quota

id path, required text

`GET /v1/sources`

The public source register: verdict, licence and when each source was last checked. Not counted toward the quota

No parameters.

`GET /v1/usage`

Calls counted this month (Riyadh time) across all of the account's keys, and calls by shelf. Not counted toward the quota

No parameters.

Examples

Is a date a working day?

curl -H "Authorization: Bearer $SDL_KEY" \
  "https://source.fast.sa/v1/calendar/working-day?date=2026-09-24&sector=government"

Prayer times for a city

curl -H "Authorization: Bearer $SDL_KEY" \
  "https://source.fast.sa/v1/calendar/prayer-times?city=jeddah&date=2026-10-23"

Find a standard by number

curl -G -H "Authorization: Bearer $SDL_KEY" "https://source.fast.sa/v1/standards/search" \
  --data-urlencode "q=SBC 201"

MCP connector

URL: https://source.fast.sa/mcp. Streamable HTTP, stateless (POST only, JSON answers), no key, up to 60 requests a minute per IP address.

In Claude, add a custom connector with this URL. In ChatGPT, add it as a connector in developer mode. Any MCP client that speaks streamable HTTP works too.

Every tool is read-only. A result has two text parts: a one-paragraph summary that ends with its source line, then the same JSON answer as the REST API. Errors come back as {"error": {"code", "message"}} with isError set.

`convert_saudi_date` · Convert Hijri and Gregorian dates

Converts a date between the Gregorian calendar and the Umm al-Qura Hijri calendar, the official calendar of Saudi Arabia. Give exactly one of gregorian or hijri. Returns both dates, the weekday and the Hijri month name in Arabic and English. Covers 1300 to 1600 AH.

gregorian optional date, YYYY-MM-DD — A Gregorian date, YYYY-MM-DD.
hijri optional date, YYYY-MM-DD — An Umm al-Qura Hijri date, YYYY-MM-DD, e.g. 1447-09-01.

`saudi_prayer_times` · Saudi prayer times

Returns the times of the five daily prayers and sunrise for a Saudi city, or for coordinates inside Saudi Arabia, on a date (default: today in Riyadh). Computed with the Umm al-Qura method, in Asia/Riyadh time. Give a city, or both lat and lng.

city optional text, up to 100 characters — A Saudi city in English or Arabic, e.g. riyadh, jeddah or الدمام.
lat optional number -90–90 — Latitude of a place inside Saudi Arabia (with lng).
lng optional number -180–180 — Longitude of a place inside Saudi Arabia (with lat).
date optional date, YYYY-MM-DD — YYYY-MM-DD; default: today in Riyadh.

`saudi_holidays` · Saudi official holidays

Returns the official holidays of a year for the government sector, the private sector, or both: dates, names in Arabic and English, and the regulation or announcement each rests on, with its link. Years covered: 2026 and 2027.

year optional integer — Gregorian year (2026 or 2027); default: the current year in Riyadh.
sector optional one of government, private — government or private; leave out for both.

`is_saudi_working_day` · Check a Saudi working day

Says whether a date is a working day in Saudi Arabia for the government or the private sector, and why: a weekend, an official holiday (with the regulation it rests on and its link), or a normal working day. Default date: today in Riyadh.

date optional date, YYYY-MM-DD — YYYY-MM-DD; default: today in Riyadh.
sector required one of government, private — government or private.

`search_saudi_standards` · Search Saudi standards

Searches Saudi standards (SASO) and the Saudi Building Code (SBC) by number, e.g. «SBC 201» or «SASO 2902», or by words of the Arabic or English title. Returns the matching standards with number, titles, kind, status, edition year, the international standard adopted, the official page and where the issuing body provides the full text. It never returns the text of a standard.

query required text, up to 500 characters — A standard number (e.g. SBC 201, SASO 2902) or title words in Arabic or English.
body optional one of SASO, SBC — SASO or SBC, to search one body only.
kind optional one of standard, technical_regulation, building_code — standard, technical_regulation or building_code.
limit optional integer 1–50, default 10 — How many results to return, 1 to 50 (default 10).

`get_saudi_standard` · Get a Saudi standard

Returns one Saudi standard or building code by its id (from search_saudi_standards): number, titles, kind, status, edition, the international standard adopted, the official page and where the issuing body provides the full text, with the source and the date it was checked.

id required text, up to 100 characters — The standard id returned by search_saudi_standards, e.g. sbc-201.

About the data

Standards come from SASO's open-data list and the Saudi Building Code catalogue: facts and links only. The full texts are sold by their publishers.
Calendar: Umm al-Qura dates from 1300 to 1600 AH; prayer times computed with the Umm al-Qura method; holidays for 2026 and 2027 from the Civil Service and Labor Law regulations and official announcements.
/v1/sources lists every source with its licence and the date we last checked it.

Help

Email data@fast.sa or see Support. Read the Terms and the Privacy Policy. Machine-readable: /openapi.json, /llms.txt, /llms-full.txt.

API guide

Quick start

Base URL and versions

Authentication

Answer format

Errors

Limits

Endpoints

GET /v1/calendar/convert

GET /v1/calendar/prayer-times

GET /v1/calendar/holidays

GET /v1/calendar/working-day

GET /v1/standards/search

GET /v1/standards/{id}

GET /v1/sources

GET /v1/usage