---
title: "Developer guide"
description: "Keyless public reads, Markdown and remote MCP for Agam."
canonical: https://home.ashwingopalsamy.in/developers/
last_updated: 2026-10-04
revision: c9161e764e52b4dcc96cd87d00efa2306fc165a62799f73bbbac98fc5bd0ec69
language: en
---

# Developer guide

The base origin is https://home.ashwingopalsamy.in. These interfaces retrieve public journal information; they cannot modify records, contact people, access private evidence or make payments. Access is free and no signup or API key is required.

## First request
~~~sh
curl -fsS https://home.ashwingopalsamy.in/api/v1/site
curl -fsS 'https://home.ashwingopalsamy.in/api/v1/search?q=roof&limit=20'
curl -fsS https://home.ashwingopalsamy.in/api/v1/content/journal-summary
~~~

## REST API
| Method | Endpoint | Returns |
| --- | --- | --- |
| GET | `/api/v1/site` | Site identity and documentation links |
| GET | `/api/v1/content` | A page of public records |
| GET | `/api/v1/content/{id}` | One record with source and precision |
| GET | `/api/v1/search?q=roof` | Records matching literal words |

The [OpenAPI 3.1.0 contract](/openapi.json) describes these public reads. Optional kind filters are page, summary, cost and work. These interfaces cannot modify records, contact people, read private evidence or make payments. Search does not execute regex, fetch external URLs or generate answers.

## Pagination and limits
Default limit is 20, maximum 100. Follow next_cursor with the same query, kind and limit. Results use ascending stable IDs against one content snapshot. Signed cursors expire after one hour; invalid, tampered or mismatched cursors return 400, and a changed snapshot returns 409. Start a fresh traversal after expiry or snapshot change. Search is bounded to 160 characters. The Worker enforces 120 integration requests per client IP per 60 seconds using Cloudflare’s per-location limiter, and 32 concurrent requests per isolate. This is approximate infrastructure protection, not a global billing quota. A 429 includes Retry-After: 60. RateLimit-Policy: "public-read";q=120;w=60 describes this enforced policy using draft-ietf-httpapi-ratelimit-headers-11, an Internet-Draft. Successful requests do not advertise a remaining balance because the Cloudflare binding does not expose it. A limiter denial may advertise RateLimit: "public-read";r=0. Concurrency denials carry Retry-After without pretending the request quota was exhausted.

## Errors and caching
REST failures use application/problem+json following RFC 9457, with code and request_id extensions. Codes include invalid_input, not_found, invalid_cursor, snapshot_changed, rate_limited and unavailable. Do not retry invalid input. Retry safe reads with bounded backoff and jitter; never loop indefinitely. Public text representations support gzip via Accept-Encoding, with q=0 exclusions and no-transform guarding against content injection. HTML, Markdown and content encodings use separate ETags, Last-Modified and Vary: Accept, User-Agent, Accept-Encoding; list/search responses use no-store because cursors expire. Cross-origin browser access is not enabled. Server clients are supported without CORS.

## Markdown representations
Fetch [index.md](/index.md), [developers.md](/developers.md), or the deterministic .md counterpart advertised by a public page. Explicit Accept: text/markdown also selects Markdown; q values and exclusions are respected. Wildcard browser requests default to HTML. GPTBot, ClaudeBot and PerplexityBot can receive the same facts as Markdown when no explicit Markdown preference/exclusion is supplied; explicit quality ordering and q=0 exclusions take precedence. This routing grants no permissions. Unsupported representations receive 406. [Search documentation](/api/v1/search.md) and [catalog documentation](/.well-known/api-catalog.md) are Markdown documentation, not API result formats.

## Remote MCP
Connect a compatible Streamable HTTP MCP client to https://home.ashwingopalsamy.in/mcp. Protocol target is 2026-07-28 with official TypeScript SDK 2.0.0; legacy stateless negotiation is also provided by that SDK. The read-only tools are search_content and get_content. Resources expose the site guide and bounded navigation index. All interfaces share the same content projection and access policy. [Agent guide](/agents.md) · [Authentication](/auth.md) · [API catalog](/.well-known/api-catalog). The [experimental upstream server card](/mcp/server-card) and [orank compatibility card](/.well-known/mcp/server-card.json) describe the same real endpoint. The upstream card is an experimental extension, not core MCP; primitives are listed at runtime. [Publisher integrity](/trust/) explains verifiable catalog provenance. The [official MCP registry listing](https://registry.modelcontextprotocol.io/v0.1/servers/in.ashwingopalsamy.home%2Fagam-journal/versions/1.1.0) is live with verified domain ownership.

## Versioning and deprecation
REST paths are /api/v1; compatible additions may be made within v1. Stable IDs, operation IDs and existing field meanings must not change silently. Breaking contracts require a new major path and at least 90 days of documented notice while the prior version remains supported. No interface is currently deprecated. Read the [version policy](/versions.md).

## Clients and local testing
The TypeScript agam-journal-client and Python agam-journal packages provide site, list, search and read operations and structured JSON CLI output. Build artifacts are available from the [official integration source](https://github.com/ashwingopalsamy/agam-integrations). Registry publication status is listed there; do not assume package registry availability. The source includes installation and synthetic fixture commands. Local fixture tests are not production verification. This read-only service has no separate public sandbox because it has no destructive or paid workflow.

## Source

Review: not independently reviewed. Last updated: 2026-10-04.
Freshness comes from source/correction dates; month-only sources use their publication date as a disclosed release-date fallback. Work and payment dates are separate.

[Canonical page](https://home.ashwingopalsamy.in/developers/) · [Developer guide](/developers/) · [Navigation](/llms.txt)
