Developer portal

FARUQ API

The same screening engine that powers this site is available as a versioned REST API. Responses are JSON, errors are consistent, and every assessment carries its methodology version, criteria and sources.

Manage API keys

Endpoints

Base path /api/v1. All responses are wrapped in a data envelope; list endpoints add a pagination object.

GET/api/v1/assetsPublic

List and search the asset catalogue.

q: Free-text search across name, ticker, network and contract address.
status: Filter by assessment status, e.g. HALAL or NOT_SCREENED.
sort: Result ordering.
page: Page number, starting at 1.
pageSize: Results per page.

GET/api/v1/assets/{id}Public

Fetch a single canonical asset record.

GET/api/v1/assets/{id}/assessments/latestPublic

Latest assessment for an asset. Returns data: null with status NOT_SCREENED when no assessment exists.

GET/api/v1/assets/{id}/assessmentsPublic

Full immutable assessment history, including activity scopes.

POST/api/v1/screeningsBearer token

Queue a durable screening job. Responds 202 with a job identifier. Requires an Idempotency-Key header.

GET/api/v1/screenings/{jobId}Bearer token

Operational state of a screening job — queued, processing, succeeded, failed or cancelled.

GET/api/v1/methodologiesPublic

Published methodology versions, criteria and citations.

GET/api/v1/healthPublic

Service health. Returns HTTP 503 when the service is not fully configured.

Listing assets

Search, filter and paginate the catalogue.

bash

curl "https://<your-deployment>/api/v1/assets?q=ETH&page=1&pageSize=25"

{
  "data": [
    {
      "id": "…",
      "providerId": "…",
      "symbol": "ETH",
      "name": "…",
      "assetClass": "crypto",
      "network": "…",
      "contractAddress": null,
      "status": "NOT_SCREENED"
    }
  ],
  "pagination": { "page": 1, "pageSize": 25, "total": 1 }
}

Requesting a screening

Screening is asynchronous. The request returns a durable job identifier; poll the job endpoint for its operational state.

bash

curl -X POST "https://<your-deployment>/api/v1/screenings" \
  -H "Authorization: Bearer <supabase-access-token>" \
  -H "Idempotency-Key: 6f0c1c2e-…" \
  -H "Content-Type: application/json" \
  -d '{"assetId":"<asset-id>","scope":"asset"}'

HTTP/1.1 202 Accepted
{ "data": { "id": "<job-id>", "state": "queued" } }

Supply a stable Idempotency-Key per logical request. Repeating a request with the same key returns the existing job instead of queuing a duplicate.

Errors

Every failure uses the same envelope. Include the requestId when reporting a problem.

json

{
  "error": {
    "code": "ASSET_NOT_FOUND",
    "message": "No asset exists with that identifier.",
    "requestId": "req_…"
  }
}

401 — missing or expired credentials.
403 — authenticated but not permitted, including admin routes.
404 — unknown asset, job or route.
429 — rate limit or quota exceeded for the key.
503 — the service is not configured or a dependency is down.

curl "https://<your-deployment>/api/v1/assets?q=ETH&page=1&pageSize=25" { "data": [ { "id": "…", "providerId": "…", "symbol": "ETH", "name": "…", "assetClass": "crypto", "network": "…", "contractAddress": null, "status": "NOT_SCREENED" } ], "pagination": { "page": 1, "pageSize": 25, "total": 1 } }

curl -X POST "https://<your-deployment>/api/v1/screenings" \ -H "Authorization: Bearer <supabase-access-token>" \ -H "Idempotency-Key: 6f0c1c2e-…" \ -H "Content-Type: application/json" \ -d '{"assetId":"<asset-id>","scope":"asset"}' HTTP/1.1 202 Accepted { "data": { "id": "<job-id>", "state": "queued" } }