Majal - public API & agent discovery

Majal (مجال) at majal.link hosts link-in-bio profiles and digital business cards for Arabic- and English-speaking creators and businesses. This page explains what an automated client (crawler, AI agent, API tooling) can fetch from the site and how to find it.

In short: everything public is readable without credentials. There is no public write API and no self-service agent registration. Account actions are only available to the signed-in human owner through the web app.

Discovery documents

Resource URL Format
API catalog (RFC 9727) /.well-known/api-catalog application/linkset+json
OpenAPI 3.1 description /openapi.json application/json
This documentation /docs/api (HTML) · /docs/api.md (Markdown) text/html / text/markdown
MCP server (Streamable HTTP) /mcp JSON-RPC 2.0
MCP Server Card /.well-known/mcp/server-card.json application/json
UCP business profile /.well-known/ucp application/json
UCP catalog (search, lookup, product) /ucp/catalog/search, /ucp/catalog/lookup, /ucp/catalog/product JSON over POST
Agent registration & credential policy /auth.md text/markdown
Health status /health application/json
Sitemap /sitemap.xml application/xml
Crawler rules /robots.txt text/plain

The homepage response also carries Link headers (RFC 8288) with the api-catalog, service-desc, service-doc and service-meta relations pointing at the resources above, so a client that only knows https://majal.link can find everything from one request:

GET / HTTP/1.1
Host: majal.link

HTTP/1.1 200 OK
Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json",
      </openapi.json>; rel="service-desc"; type="application/json",
      </docs/api>; rel="service-doc"; type="text/html",
      </auth.md>; rel="service-meta"; type="text/markdown"

Reading pages as Markdown

Every HTML page on majal.link can also be read as Markdown. Send Accept: text/markdown and the same URL answers with Content-Type: text/markdown; charset=utf-8 (and Vary: Accept). The body starts with a small front-matter block (title, description, url, lang) followed by the page content converted to Markdown, with scripts, styles and forms removed and links made absolute.

GET /p/{page} HTTP/1.1
Host: majal.link
Accept: text/markdown

HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Vary: Accept

Error pages negotiate the same way and keep their status code (for example 404).

Public resources

All of these are served as HTML (or Markdown, see above) and need no credentials.

Resource URL Notes
Profile page /p/{page} A creator's link-in-bio profile. Paid-plan owners may also have a short alias at /{alias} that redirects here.
Digital business card /c/{cardId} The card page. Cards configured as a plain redirect answer 302 to the owner's website.
Blog index /ar/blog, /en/blog /blog without a language segment follows the visitor's language preference.
Blog article /ar/blog/{slug}, /en/blog/{slug} Articles are also listed in the sitemap.

Unknown profiles, cards and articles return 404 with an HTML error page.

MCP server

Majal runs a public, read-only Model Context Protocol server at https://majal.link/mcp (Streamable HTTP, stateless, no authentication). Its Server Card is at /.well-known/mcp/server-card.json.

Tool Input Returns
get_profile page A public profile (/p/{page}) as Markdown
get_digital_card cardId A digital business card (/c/{cardId}) as Markdown
list_blog_articles lang? JSON list of articles with slug, title, date and URL
get_blog_article slug, lang? An article as Markdown
read_page path Any public majal.link page as Markdown
search_catalog meta, catalog UCP catalog search over the Majal store (see below)
lookup_catalog meta, catalog UCP catalog lookup by product, variant, handle or SKU id
get_product meta, catalog One UCP product with option availability

Resources: the API documentation, auth.md and the OpenAPI document. Nothing on this server writes data or reaches account information.

Store catalog (Universal Commerce Protocol)

Majal publishes a UCP business profile at /.well-known/ucp and implements the two catalog capabilities, dev.ucp.shopping.catalog.search and dev.ucp.shopping.catalog.lookup, over REST at https://majal.link/ucp and over the MCP server above. The catalog lists what the store sells, with live prices from the same table the store uses:

Product Variants Store page
Professional Plan monthly auto-renew, prepaid 1 / 3 / 6 / 12 months /store
Content Creator Plan monthly auto-renew, prepaid 1 / 3 / 6 / 12 months /store
Activation Key (gift code) Professional or Content Creator x 1 / 3 / 6 / 12 months /store/product/{key}
Majal Smart Card (NFC) plain, or with printed name / job title / QR code /store/product/smart-card
Majal Digital Card (Apple Wallet) one card /store/product/digital-card

Prices are returned in SAR by default and in USD when context.currency is "USD"; text is Arabic or English following context.language or Accept-Language. Amounts are ISO 4217 minor units (halalas / cents).

curl -s https://majal.link/ucp/catalog/search \
  -H 'Content-Type: application/json' \
  -H 'UCP-Agent: profile="https://your-platform.example/.well-known/ucp"' \
  -d '{"query":"smart card","context":{"language":"en","currency":"SAR"}}'

What is deliberately missing: Majal declares no dev.ucp.shopping.checkout, cart or order capability and no payment handlers. Every product and variant carries the /store URL (also in metadata.purchase_url) where the buyer completes the purchase while signed in to their own Majal account, paying with StreamPay (SAR: mada, Apple Pay, cards) or PayPal (USD). Requests to any other /ucp/* path answer 404 with a UCP error response pointing at the store.

curl -s https://majal.link/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

WebMCP (in-browser tools)

The homepage registers tools with the browser's WebMCP API (navigator.modelContext.registerTool) when the browser supports it: open_profile, open_digital_card, read_page, list_blog_articles, navigate and switch_language. The script lives at /global-scripts/webmcp.js and does nothing in browsers without the API.

Authentication

Rules for automated clients

  1. Respect /robots.txt. The current policy allows crawling of all public pages.
  2. Do not attempt the login, one-time-code, OAuth callback or payment flows. They create accounts, send e-mail and issue credentials.
  3. Cache the discovery documents. They are served with Cache-Control: public, max-age=3600; /health is never cached.
  4. Identify yourself with a descriptive User-Agent and keep request rates reasonable.
  5. Questions and access requests: contact@majal.link or majal.link/contact.

Health endpoint

GET /health returns 200 with {"status":"ok"} when the application and its database are reachable, and 503 with {"status":"degraded"} otherwise. Each response also includes service ("majal") and an ISO-8601 time stamp.