Saudi Building Code (SBC) compliance as a platform. Integrate permit-prep, rule-checking, and 7-year audit-by-replay into your workflow.
Full interactive reference with try-it-out console. All 46 endpoints documented.
Register, login, refresh tokens, and secure your API calls with JWT Bearer auth.
Bilingual error taxonomy. Every error code with HTTP status and AR/EN messages.
Machine-readable OpenAPI 3.1 specification. Import into any compatible tool.
Ready-to-import Postman collection with environment variables for base_url and JWT token.
Production endpoint: https://api.emtithal.aisc.sa
Get a JWT token in two API calls:
# 1. Register (one-time)
curl -X POST https://api.emtithal.aisc.sa/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{"email": "you@example.sa", "password": "S3cur3P@ss!"}'
# 2. Login to get your access token
curl -X POST https://api.emtithal.aisc.sa/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "you@example.sa", "password": "S3cur3P@ss!"}'
# Response contains access_token — use it as a Bearer token:
curl https://api.emtithal.aisc.sa/api/v1/auth/me \
-H "Authorization: Bearer <access_token>"See the Authentication Guide for the full flow including token refresh and logout.
| Method | Path | Tag | Summary |
|---|---|---|---|
POST | /api/v1/admin/code-editions | admin | Register a new tenant-scoped code-edition |
POST | /api/v1/admin/code-editions/{edition_id}/ingest | admin | Kick off the ingestion workflow for a code-edition |
GET | /api/v1/admin/code-editions/{edition_id}/review-queue | admin | List rules pending engineer review for a code-edition |
GET | /api/v1/admin/code-editions/{edition_id}/status | admin | Return ingestion status + rule counts for a code-edition |
POST | /api/v1/auth/login | auth | Authenticate and obtain session tokens |
POST | /api/v1/auth/logout | auth | Log out and invalidate session |
GET | /api/v1/auth/me | auth | Retrieve current user profile |
POST | /api/v1/auth/refresh | auth | Rotate access token using refresh cookie |
POST | /api/v1/auth/register | auth | Register a new user account |
POST | /api/v1/auth/request-password-reset | auth | Request a password-reset code |
POST | /api/v1/auth/reset-password | auth | Reset password using the emailed code |
POST | /api/v1/auth/verify-email | auth | Verify email and activate account |
DELETE | /api/v1/billing/me/subscription | billing | Soft-cancel the caller's subscription (effective at period end) |
GET | /api/v1/billing/me/subscription | billing | Get the caller's subscription (RLS-scoped) |
POST | /api/v1/billing/me/subscription | billing | Create a subscription for the caller (sign-up) |
PATCH | /api/v1/billing/me/subscription/payg | billing | Toggle PAYG opt-in + monthly ceiling |
POST | /api/v1/billing/me/subscription/reactivate | billing | Undo a soft-cancel before the period ends |
GET | /api/v1/billing/me/usage | billing | Get the caller's current-period usage meter |
GET | /api/v1/billing/plans | billing | List published plan catalog |
GET | /api/v1/billing/plans/{plan_code} | billing | Get a single plan by code |
POST | /api/v1/billing/webhooks/moyasar | webhooks-moyasar | Moyasar payment + subscription webhook intake (body-token verified) |
GET | /api/v1/codes | codes | List code-editions visible to the caller |
POST | /api/v1/codes/{code_id}/qa | codes | Ask a question about a code's rules (bilingual, with citations) |
POST | /api/v1/jobs | jobs | Create a compliance check job |
GET | /api/v1/jobs/{job_id} | jobs | Get compliance job state |
POST | /api/v1/jobs/{job_id}/cancel | jobs | Cancel a running compliance job |
GET | /api/v1/jobs/{job_id}/events | jobs | Stream job progress events (SSE) |
POST | /api/v1/jobs/{job_id}/override | jobs | Override a compliance verdict |
GET | /api/v1/jobs/{job_id}/result.pdf | jobs | Get verdict PDF download URL |
GET | /api/v1/jobs/{job_id}/rules/{rule_id}/verdicts | jobs | Per-element verdict drill-down for a single rule (AUD-048) |
GET | /api/v1/jobs/{job_id}/verdicts | jobs | List job verdicts in Phase-7 workbench shape (paginated) |
POST | /api/v1/jobs/{job_id}/versions | versions | Create a new working version of a job (Phase 5 scaffold) |
GET | /api/v1/jobs/{job_id}/versions/{version_a}/diff/{version_b} | versions | Diff verdicts between two versions of a job (Phase 9) |
GET | /api/v1/projects | projects | List your projects |
POST | /api/v1/projects | projects | Create a project |
POST | /api/v1/projects/{project_id}/documents | projects | Register a document + get a presigned upload URL |
POST | /api/v1/projects/{project_id}/documents/{document_id}/complete | projects | Finalize an upload (head + hash the object, register the document) |
GET | /api/v1/projects/{project_id}/jobs | jobs | List compliance jobs for a project |
GET | /api/v1/rule-review/pdf/{filename} | rule-review | Download SBC rule PDF |
GET | /api/v1/rule-review/queue | rule-review | List rule review queue items |
GET | /api/v1/rule-review/queue/{queue_id} | rule-review | Get detailed review queue item |
PATCH | /api/v1/rule-review/queue/{queue_id} | rule-review | Apply incremental corrections to pending review item |
POST | /api/v1/rule-review/queue/{queue_id}/approve | rule-review | Approve rule and finalize review |
POST | /api/v1/rule-review/queue/{queue_id}/reject | rule-review | Reject rule and return to submission queue |
POST | /api/v1/users/me/dsar | users | Submit a PDPL data-subject access/erasure request |
GET | /api/v1/webhooks/subscriptions | webhooks | List webhook subscriptions visible to caller (RLS-scoped) |
POST | /api/v1/webhooks/subscriptions | webhooks | Register a webhook subscription |
DELETE | /api/v1/webhooks/subscriptions/{subscription_id} | webhooks | Soft-delete (deactivate) a webhook subscription |
POST | /api/v1/webhooks/subscriptions/{subscription_id}/test | webhooks | Send a synchronous test ping to verify endpoint setup |
GET | /healthz | health | Liveness probe |
GET | /readyz | health | Readiness probe |