---
title: "Ashwin Gopalsamy · Developer Resources, API Documentation & SDKs"
description: "Official developer API, OpenAPI 3.1.0 specification, Model Context Protocol server, multi-language SDKs (npm, PyPI, Go, RubyGems), and CLI tool for Ashwin Gopalsamy"
---
# developers

APIs, OpenAPI 3.1.0 specification, Model Context Protocol (MCP) server, official multi-language SDKs (npm, PyPI, Go, RubyGems), and integration guides for developers and AI agents.

All read-only REST and agent interfaces on [ashwingopalsamy.in](/openapi.json) operate with zero onboarding friction. No API keys, payment methods, or authentication credentials are required for standard discovery.

The live endpoints serve as an open sandbox environment returning deterministic, authoritative data with sub-second latency budgets.

[OpenAPI 3.1.0 Spec](/openapi.json)[Design Details](/design/)[AI briefing](/ai/)

## Official Multi-Language SDKs

Official client packages auto-generated and validated against the [OpenAPI 3.1.0](/openapi.json) specification, featuring verified package homepages pointing to [https://ashwingopalsamy.in/developers](/developers):

TypeScriptPythonGoRuby

npm · TypeScript

$`npm install @ashwingopalsamy/sdk`

```
import { AshwinGopalsamyClient } from "@ashwingopalsamy/sdk";

const client = new AshwinGopalsamyClient();
const profile = await client.getProfile();
const results = await client.searchSite("rate limiters", 5);
```

$`pip install ashwingopalsamy`

```
from ashwingopalsamy import Client

client = Client()
profile = client.get_profile()
results = client.search_site("rate limiters", limit=5)
```

$`go get github.com/ashwingopalsamy/site/packages/go`

```
import (
    "context"
    ashwingopalsamy "github.com/ashwingopalsamy/site/packages/go"
)

client := ashwingopalsamy.NewClient()
profile, err := client.GetProfile(ctx)
results, err := client.SearchSite(ctx, "rate limiters", 5)
```

$`gem install ashwingopalsamy`

```
require "ashwingopalsamy"

client = AshwinGopalsamy::Client.new
profile = client.get_profile
results = client.search_site("rate limiters", limit: 5)
```

## Official CLI Tool (ashwingopalsamy)

Script interactions with Ashwin Gopalsamy's profile, notes, and search index directly from your terminal or automation pipeline:

NPX / Node.jsZero-install Node CLI for profile inspection, global search, and note retrieval.

```
npx ashwingopalsamy profile
npx ashwingopalsamy search "rate limiters"
npx ashwingopalsamy note designing-rate-limiters-for-payment-systems
```

Curl / POSIX ShellLightweight POSIX shell runner for Unix environments without Node installed.

```
curl -sSL https://ashwingopalsamy.in/cli.sh | sh -s -- profile
curl -sSL https://ashwingopalsamy.in/cli.sh | sh -s -- search "ISO 8583"
```

## REST v1 Endpoints

Base: `https://ashwingopalsamy.in/api/v1`

GET/api/v1/profile

Authoritative career summary, current role, location, and verified profile facts.

GET/api/v1/search?query={q}&limit={n}

Search technical notes, craft projects, and reading list entries.

GET/api/v1/content?kind={kind}&limit={n}

List public entries by kind (note, craft, book, watch, or all).

GET/api/v1/notes/{slug}

Retrieve raw Markdown content and metadata for a published note.

GET/api/v1/status

API operational status, versioning policy, and capability catalog.

## Protocol Interfaces (MCP, A2A & Web Bot Auth)

### Model Context Protocol (MCP)

</mcp>

Streamable HTTP · JSON-RPC 2.0

Production MCP endpoint offering native tool execution (search\_site, get\_profile, list\_content, get\_note\_markdown), resources, and prompt templates for autonomous AI agents.

`npx -y @modelcontextprotocol/inspector https://ashwingopalsamy.in/mcp`

### Agent-to-Agent (A2A)

</a2a>

JSON-RPC 2.0 Task Routing

Direct agent message exchange protocol for task delegation, profile extraction, and capability handoff.

`curl -s -X POST https://ashwingopalsamy.in/a2a -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"parts":[{"kind":"text","text":"profile"}]}}}'`

### OpenAPI Specification

</openapi.json>

OpenAPI 3.1.0

Complete machine-readable REST API schema defining strongly typed parameters, request contracts, and response schemas.

`curl -s https://ashwingopalsamy.in/openapi.json`

### Web Bot Auth Directory (RFC 9421)

</.well-known/http-message-signatures-directory>

RFC 9421 · Ed25519 JWK

Cryptographic public signature keys directory for verifying authentic bot identities and mitigating spoofing.

`curl -s https://ashwingopalsamy.in/.well-known/http-message-signatures-directory`

## Web Bot Authentication (RFC 9421 HTTP Signatures)

Legitimate automated agents and bots can sign HTTP requests according to **RFC 9421 (HTTP Message Signatures)**. Ashwin Gopalsamy's public signing directory is published at </.well-known/http-message-signatures-directory>.

The directory exposes Ed25519 JSON Web Keys with validity timestamps (`nbf`, `exp`) to cryptographically distinguish genuine bot agents from spoofers.

## Headers & Rate Limiting

All REST and agent endpoints return standard IETF RateLimit and legacy X-RateLimit headers so agents can self-throttle in real time:

RateLimit-Limit120

Maximum requests permitted per sliding window (120 per minute).

RateLimit-Remaining0..120

Remaining request budget available in the active window.

RateLimit-Reset60s

Seconds remaining until current window quota fully resets.

RateLimit-Policy120;w=60

Standard IETF quota policy descriptor (120 req / 60s window).

X-RateLimit-\*Legacy

Compatibility headers provided for legacy HTTP clients and proxies.

API-Version2026-08-22

Contract release timestamp defining endpoint behavior.

If a client exceeds quota, the server responds with HTTP 429 Too Many Requests and includes a Retry-After header with the required wait duration.

## API Versioning & Deprecation Policy

Ashwin Gopalsamy's API employs explicit URL versioning (`/api/v1/...`) combined with response version headers:

Path Versioning/api/v1

Major revisions use dedicated URL prefixes. Non-breaking extensions preserve route stability.

Deprecation SignalingRFC 9594 & 8594

Retiring routes broadcast standard Deprecation and Sunset headers with targeted decommission dates.

Notice Window6 Months

Breaking contract changes require a minimum 6-month advance notice before sunset.

## Typed Error Model (RFC 9457)

All error responses follow the RFC 9457 Problem Details standard (`application/problem+json`) with structured error codes and actionable resolution hints:

```
{
  "type": "https://ashwingopalsamy.in/developers#errors",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "Note slug 'non-existent' was not found in published index.",
  "code": "note_not_found",
  "resolution_hint": "Check /api/v1/content?kind=note for a complete list of valid note slugs."
}
```

## Scoped Permissions & Security Schemes

OAuth 2.0 discovery metadata is published at </.well-known/oauth-protected-resource> and </auth.md>. Supported permission scopes:

site.readRead-Only

Unrestricted read access to public profiles, craft projects, and technical notes.

profile.readRead-Only

Access verified identity facts, career history, and current employment metadata.

content.searchRead-Only

Execute semantic and keyword queries across technical notes and library entries.

notes.readRead-Only

Retrieve raw Markdown source and frontmatter for published technical notes.

## Developer & Machine Discovery Index

Direct links to all machine-readable catalogs, feeds, and discovery surfaces:

### Developer APIs & Specifications

- [/openapi.jsonOpenAPI 3.1.0 complete REST API specification.](/openapi.json)
- [/developers.mdDeveloper integration guide in plain Markdown format.](/developers.md)
- [/auth.mdAgent authentication, token discovery, and security schemes.](/auth.md)
- [/.well-known/oauth-protected-resourceOAuth 2.0 protected resource metadata discovery.](/.well-known/oauth-protected-resource)

### AI & Agent Discovery

- [/mcpModel Context Protocol endpoint (Streamable HTTP · JSON-RPC 2.0).](/mcp)
- [/mcp/catalog.jsonCatalog of registered MCP tools, resources, and prompt templates.](/mcp/catalog.json)
- [/.well-known/mcp/server-card.jsonMCP Server Card metadata for automatic client configuration.](/.well-known/mcp/server-card.json)
- [/a2aAgent-to-Agent communication endpoint for task delegation.](/a2a)
- [/.well-known/agents.mdSystem prompt instructions and capabilities for autonomous agents.](/.well-known/agents.md)
- [/.well-known/ai-catalog.jsonAgent Resource Directory (ARD) index of accessible surfaces.](/.well-known/ai-catalog.json)

### LLM Context & Machine Catalogs

- [/llms.txtConcise profile and content summary for language models.](/llms.txt)
- [/llms-full.txtComplete context bundle covering all technical notes and craft history.](/llms-full.txt)
- [/knowledge.jsonJSON-LD graph dump of all verified biographical and career facts.](/knowledge.json)
- [/cli.shOfficial zero-dependency POSIX shell command-line interface.](/cli.sh)
- [/.well-known/http-message-signatures-directoryRFC 9421 HTTP Message Signatures Ed25519 public key directory.](/.well-known/http-message-signatures-directory)