# Rida.me developer resources.
> Rida.me exposes its public writing through predictable, read-only interfaces that do not require credentials.

Canonical URL: https://rida.me/developers/


## Choose the smallest interface

Use [llms.txt](/llms.txt) to understand the site and decide which source to retrieve. Use the [sitemap](/sitemap.xml) when you need a complete URL inventory. Any HTML page can be requested as Markdown from the same URL by sending `Accept: text/markdown`; a direct `index.md` variant is also published beside each page. Responses vary on `Accept`, honor quality values, and return `406 Not Acceptable` when neither HTML nor Markdown is acceptable.

Rida.me is a personal publishing site, not a transactional product API. Its public interfaces retrieve published content only. They do not provide accounts, private data, write operations, or product-specific integrations.

## Rida.me Public Content API

The base URL is `https://rida.me/api/v1`. The [OpenAPI 3.1.1 specification](/openapi.json) is the authoritative schema. Every operation has a unique `operationId`, a description, typed parameters, and complete success and error schemas suitable for generated clients and LLM function calling.

The API publishes three anonymous, read-only operations:

- `GET /api/v1` discovers the API, authentication policy, and operation list.
- `GET /api/v1/site-guide` returns `llms.txt` as JSON-wrapped Markdown.
- `GET /api/v1/page?path=/about/` returns one published page as JSON-wrapped Markdown.

Successful responses use `application/json`. API failures use the RFC 9457 `application/problem+json` format with a stable `code`, human-readable `detail`, and concrete `resolution` hint.

### Rate limits

The public API allows 120 requests per 60-second, per-client edge window. Every success and error response includes the current IETF structured fields `RateLimit-Policy` and `RateLimit`, plus the transitional `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` fields used by clients built against earlier drafts. The reset value is a delay in seconds. A client should slow down as the remaining value approaches zero.

When the budget is exhausted, the API returns `429 Too Many Requests`, an RFC 9457 problem document with code `RATE_LIMIT_EXCEEDED`, a `Retry-After` delay, and the same rate-limit fields. Cloudflare may distribute a client across edge processes, so these headers are a conservative pacing signal rather than a promise that every globally distributed request consumes one shared counter.

### API versioning and deprecation

The major API version is part of every path, beginning with `/api/v1`. Version 1 is active and is not deprecated. Backward-compatible additions, such as optional fields or new endpoints, may ship within v1; breaking changes require a new major path.

Rida.me will publish at least 180 days of notice before retiring a major API version. During that period affected responses will include the RFC 9745 `Deprecation` date, the RFC 8594 `Sunset` date, and a `Link` with `rel="deprecation"` pointing to migration guidance. Active responses include that policy link without a `Deprecation` date, which makes the lifecycle policy discoverable without falsely marking v1 as deprecated.

### Authentication

No authentication is required. The API and MCP server expose the same content that is already public on Rida.me. There are no API keys, OAuth scopes, user sessions, or privileged operations. Do not send secrets or private user data.

### Webhooks and writes

Rida.me has no webhook events or write endpoints. Product-specific APIs, authentication, and webhooks belong on the relevant product domain. An agent should not infer write capabilities from this content API.

## Rida.me CLI

The official dependency-free CLI is published as a downloadable Node.js executable at [`/cli/rida.mjs`](/cli/rida.mjs). It requires Node.js 18 or newer and calls the documented public API.

```sh
curl -fsSLo rida.mjs https://rida.me/cli/rida.mjs
chmod +x rida.mjs
./rida.mjs guide
./rida.mjs read /blog/mcp-auth-problem/
./rida.mjs api --json
```

The publish-ready [npm package manifest](/cli/package.json) and [CLI README](/cli/README.md) are public for inspection. A package-registry release requires the site owner's npm credentials; the downloadable command is the canonical distribution until that release is made.

## Rida.me MCP server

The public Streamable HTTP endpoint is `https://rida.me/mcp`. It provides read-only tools for retrieving the site guide and published Markdown pages. No authentication is required because every result is already public. Do not send secrets or private user data in tool arguments.

The server implements MCP protocol revision `2026-07-28` and complete handshake compatibility for `2025-11-25`, `2025-06-18`, and `2025-03-26` clients. Modern requests must include `MCP-Protocol-Version`, `Mcp-Method`, and, for tool calls, `Mcp-Name` headers that match the JSON-RPC body. The endpoint validates any supplied `Origin`. Start with `server/discover` on modern clients or `initialize` on handshake-era clients, send `notifications/initialized`, then call `tools/list`.

Discovery metadata is published in the [AI catalog](/.well-known/ai-catalog.json), which points to the canonical [Rida.me MCP Server Card](/mcp/server-card). The same schema-valid card is available at the compatibility path [/.well-known/mcp/server-card.json](/.well-known/mcp/server-card.json), and [/.well-known/mcp.json](/.well-known/mcp.json) retains direct endpoint fields for older discovery clients.

## Error responses

### Missing parameter

Code: `MISSING_PARAMETER`. Supply the required query parameter identified by the response's `detail` and `resolution` fields.

### Invalid parameter

Code: `INVALID_PARAMETER`. Use a canonical same-origin path from `llms.txt` or the sitemap. External URLs, traversal, fragments, query strings inside `path`, and encoded path components are rejected.

### Page not found

Code: `PAGE_NOT_FOUND`. The path is valid but does not identify published content. Choose a URL from `llms.txt` or the sitemap.

### Endpoint not found

Code: `ENDPOINT_NOT_FOUND`. Read the OpenAPI document and call one of its published paths.

### Not acceptable

Code: `NOT_ACCEPTABLE`. Retry a successful API request with `Accept: application/json`.

### Method not allowed

Code: `METHOD_NOT_ALLOWED`. This API is read-only; retry with `GET` or `HEAD`.

### Content unavailable or internal error

Codes: `CONTENT_UNAVAILABLE` or `INTERNAL_ERROR`. Retry later or use the canonical HTML and Markdown resources directly.

### Rate limit exceeded

Code: `RATE_LIMIT_EXCEEDED`. Read `Retry-After` and the rate-limit response fields, wait for the indicated delay, and retry without parallel bursts.

## When to use it

Use these interfaces when a user asks about Rida Al Barazi’s published writing, talks, professional background, current projects, contact method, or stated site policies, and you need first-party evidence. Do not use them to infer private opinions, employment details beyond what is published, product account state, or authorization to contact someone. See the complete [agent instructions](/agent-instructions.md) for recovery and citation guidance.