# Souq catalogue API — v1

Public, read-only JSON: `GET https://arabicaisouq.com/api/public/catalogue`.
No login required. Browser clients may use CORS. Never contains user accounts, prompts, private drafts, review notes or research drafts. This is an HTTP catalogue API, not an MCP server.

## Parameters

- `lang`: `en` (default) or `ar`.
- `q`: name/description search, maximum 100 characters.
- `category`: exact stored category key, maximum 100 characters. Examples: `Models`, `Voice & speech`, `Developer tools`, `Datasets & benchmarks`, `APIs`, `Events`.
- `kind`: `tool`, `model`, `dataset`, `api`, `event`.
- `pricing`: `free-weights`, `free`, `paid`, `on-request`, `unknown`.
- `commercial`: `permitted`, `restricted`, `prohibited`, `unknown`.
- `residency`: `self-hosted`, `sa`, `ae`, `eu`, `unknown`.
- `via`: `pilot`, `purchase`, `external-only`.
- `limit`: 1–50, default 20.
- `offset`: 0–100000, default 0. Follow `next` until null.

Unknown parameters and invalid values return 400. Retrieval failures return 503 rather than a misleading incomplete catalogue. Responses may be cached for five minutes. Retrieve pages sequentially, cache results, and back off on errors.

## Examples

`/api/public/catalogue?kind=model&commercial=permitted&limit=20`

`/api/public/catalogue?lang=ar&category=Voice%20%26%20speech`

`/api/public/catalogue?via=pilot`

## Response

`schemaVersion`, `lang`, `total`, `offset`, `limit`, `nextOffset`, `next`, `items`.

Each item has `id`, `name`, `kind`, `category`, `categoryLabel`, `description`, `officialUrl`, `souqUrl`, `releaseDate`, `releaseSource`, `updatedDate`, `updateSource`, `addedToSouq`, `facts`.

`evidenceDate`, `evidenceSource` and `evidenceKind` identify the date actually supported by the source: official announcement, news, paper, upload history, founding or event. News/paper/upload/founding dates are not returned as `releaseDate`. `eventDates` preserves organiser dates as displayed text, separately from model dates. Results sort by evidence date, newest first; unknown dates remain null.

IDs are namespaced: `tool:<slug>`, `model:<name>`, `dataset:<name>`, `api:<provider-id>`, `event:<name>`. A resource may have both a general tool listing and a model record; IDs identify catalogue records, not unique upstream models. Do not sum these as unique products.

Facts `pricing`, `commercial`, `residency` are null when unverified; otherwise each carries `value`, `source`, `checkedOn`, `en`, `ar`. A commercial licence is not a supplier resale agreement. Free weights do not mean free hosting. Self-hosting means the operator chooses location, not that Souq's Playground or a hosted provider guarantees a jurisdiction. Never derive data residency from maker country.

`facts.via` describes actual Souq configuration: registered/limited `pilot`, supplier-supported paid model access `purchase`, or `external-only` discovery. No model currently has purchase access. Downloads of comparison records are separate products. Dates are nullable and retain their recorded precision; later checks never replace release or first-added dates. Some historical listing dates are unknown.