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`
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

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

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

Reading public pages and the MCP server: no authentication.
Everything else (creating or editing profiles and cards, orders, analytics, account settings) is restricted to the account owner, who signs in through the web app at /login with an e-mail one-time code, Google or Facebook. The browser then holds a session cookie named token.
The session cookie is not issued to automated clients and no endpoint described in /openapi.json requires it.
Majal does not operate an OAuth authorization server and does not publish OAuth Protected Resource Metadata. Details, including how to request operator-provisioned access, are in /auth.md.

Rules for automated clients

Respect /robots.txt. The current policy allows crawling of all public pages.
Do not attempt the login, one-time-code, OAuth callback or payment flows. They create accounts, send e-mail and issue credentials.
Cache the discovery documents. They are served with Cache-Control: public, max-age=3600; /health is never cached.
Identify yourself with a descriptive User-Agent and keep request rates reasonable.
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.