# Matthews Wong API — Developer Docs, Quickstart and OpenAPI

> Developer docs for the Matthews Wong API: a public REST API with no key, an OpenAPI 3.1 spec, curl quickstart, error codes, versioning and a live sandbox.

URL: https://www.matthewswong.com/en/developers/

A small public REST API behind matthewswong.com: ask the site's assistant about Matthews Wong's work, get follow-up questions, or send him a message. No API key, JSON in and out, described by OpenAPI 3.1.

- Base URL: https://www.matthewswong.com
- Version: v1, in the path
- Authentication: None, rate limited per IP
- Formats: JSON, server-sent events

## Your first request in a minute

Everything below runs from a terminal as-is. The base URL is https://www.matthewswong.com, and every path ends in a slash.

### 1. List the endpoints

The index names every endpoint, the current version and where the OpenAPI description lives.

```sh
curl https://www.matthewswong.com/api/v1/
```

### 2. Ask the assistant

The answer streams back as server-sent events: one JSON object per "data:" line, ending with "done".

```sh
curl -N https://www.matthewswong.com/api/v1/chat/ \
  -H "Content-Type: application/json" \
  -d '{"message": "What does Matthews Wong work on?"}'
```

### 3. Read any page as Markdown

Not an endpoint, but often what an agent wants: send Accept: text/markdown to any page URL.

```sh
curl -H "Accept: text/markdown" https://www.matthewswong.com/en/about/
```

## No API key needed

Every endpoint is public and unauthenticated. There is no sign-up, no key to request and nothing to rotate: send the request.

Fair use is kept by rate limits per client IP, listed per endpoint below. Responses report where you stand in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; over the limit you get a 429 with Retry-After in seconds.

Need a higher limit for a real integration? Send a message through the contact page and describe what you are building.

## Endpoints

The three operations take a JSON body over POST. Full request and response schemas are in the OpenAPI description.

| Method | Path | Purpose | Limit per minute |
| --- | --- | --- | --- |
| GET | `/api/v1/` | List the endpoints, the version and the OpenAPI URL. | None |
| POST | `/api/v1/chat/` | Ask the assistant about Matthews Wong; the answer streams as server-sent events. | 20 |
| POST | `/api/v1/chat/followups/` | Suggest up to three follow-up questions for the assistant's last answer. Never fails: it returns an empty list instead. | 30 |
| POST | `/api/v1/contact/` | Email Matthews Wong a message, with you as reply-to. Real messages from a person only. Retrying the same message is safe: it is delivered once. | 5 |

## One error shape everywhere

Every failure is JSON with the same fields: branch on code, show error to a person, follow hint to recover. The docs field points back to the OpenAPI description.

```json
{
  "success": false,
  "error": "Too many requests. Please try again later.",
  "code": "rate_limited",
  "hint": "Wait 42 seconds before retrying; the limit is 20 requests per minute per client.",
  "docs": "https://www.matthewswong.com/openapi.json",
  "retryAfter": 42
}
```

| Code | Status | Meaning |
| --- | --- | --- |
| `invalid_json` | 400 | The body is not valid JSON. |
| `invalid_request` | 400 | A field is missing or out of range; the hint names it. |
| `rejected_input` | 400 | The input was refused, for example an attempt to override the assistant's instructions. |
| `not_found` | 404 | No endpoint at that path; the hint lists the real ones. |
| `method_not_allowed` | 405 | Wrong method; the Allow header names the right one. |
| `rate_limited` | 429 | Too many requests; wait retryAfter seconds. |
| `service_unavailable` | 500 | The server is missing a dependency it needs; retry later. |
| `internal_error` | 500 | An unexpected server failure; retry later. |
| `upstream_error` | 502 | The email provider refused the message. |

## Versioning and deprecation

The contract is built so that a client written today keeps working.

- The version is in the path, /api/v1/. Pin it in your client.
- Within a version, changes are additive only: new endpoints, new optional request fields, new response fields. Nothing is removed, renamed or retyped, so ignore fields you do not know.
- A breaking change ships as a new version, /api/v2/. The previous version keeps working for at least 180 days after it is deprecated.
- A deprecated endpoint answers with a Deprecation header (RFC 9745) and a Link to its successor-version, and the OpenAPI description marks it deprecated. Once a removal date is set it also sends Sunset (RFC 8594), at least 90 days ahead.

### Deprecated endpoints

| Path | Use instead | Deprecated | Sunset |
| --- | --- | --- | --- |
| `/api/chat/` | `/api/v1/chat/` | 2026-10-08 | Not scheduled |
| `/api/chat/followups/` | `/api/v1/chat/followups/` | 2026-10-08 | Not scheduled |
| `/api/contact/` | `/api/v1/contact/` | 2026-10-08 | Not scheduled |

### What a deprecated endpoint sends

```http
POST /api/chat/

HTTP/1.1 200 OK
Deprecation: @1791417600
Link: <https://www.matthewswong.com/api/v1/chat/>; rel="successor-version", <https://www.matthewswong.com/en/developers/#versioning>; rel="deprecation"; type="text/html", <https://www.matthewswong.com/openapi.json>; rel="service-desc"
```

## Resources for tools and agents

Stable URLs that describe this API and the site, for code generators, API clients and language models.

- [OpenAPI 3.1](https://www.matthewswong.com/openapi.json): Import into Postman, Insomnia or a client generator.
- [API index](https://www.matthewswong.com/api/v1/): Endpoints and version, as JSON.
- [API catalog (RFC 9727)](https://www.matthewswong.com/.well-known/api-catalog): The standard well-known URL for finding this API.
- [llms.txt](https://www.matthewswong.com/llms.txt): Site index for language models.
- [llms-full.txt](https://www.matthewswong.com/llms-full.txt): The index with every article summary.
- [Sitemap](https://www.matthewswong.com/sitemap.xml): Every page, in both languages.
- [RSS](https://www.matthewswong.com/feed.xml): New articles as they publish.
- [JSON Feed](https://www.matthewswong.com/feed.json): The same feed, as JSON.
- [RSS (Bahasa Indonesia)](https://www.matthewswong.com/id/feed.xml): The same articles, in Indonesian.

---

- HTML version: https://www.matthewswong.com/en/developers/
- Bahasa Indonesia: https://www.matthewswong.com/id/developers/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
