# Chuck Blog Content API

Read-only, unauthenticated API over this blog. No API key is required.

- `locale` accepts `zh`, `en` or `all`; detail endpoints require an explicit locale.
- Rate limit: 120 requests per minute per IP (60 for `/search`), with `X-RateLimit-*` headers on every response.
- Responses are cacheable (`s-maxage` 600–3600s) and expose `Access-Control-Allow-Origin: *`.
- Every error body has the shape `{ "error": string }`.

## Links

- **Base URL**: https://www.chuckblog.com
- **Alternate server**: http://localhost:3000
- **OpenAPI spec**: https://www.chuckblog.com/api/openapi.json
- **Interactive docs**: https://www.chuckblog.com/docs
- **Contact**: https://www.chuckblog.com
- **License**: Content © Chuck. All rights reserved.

## GET /api/content/search

Search blog posts and notes

Keyword search across blog posts and notes.

- `locale=all` merges `zh` and `en` and ranks every candidate in one score space, so a highly relevant older post is not dropped by date ordering.
- Blog posts are scored on title (5), heading (4), tags (3), summary (2) and body text (1).
- Notes are pre-chunked at write time by a database trigger; only the best matching chunk is returned.
- `tag` filtering applies to blog posts only — notes have no tags.
- Every result carries a plain-text `snippet` around the match plus a relative `path` and an absolute `url`.

### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `q` | query | yes | Keyword or phrase. Matched against title, headings, tags, summary and body text. (type: string) |
| `locale` | query | no | Locale filter. `all` merges `zh` and `en` results into a single ranked list. Defaults to `all`. (type: string, default: "all") |
| `type` | query | no | Restrict results to blog posts, notes, or both. Defaults to `all`. (type: string) |
| `tag` | query | no | Tag filter (blog posts only; notes have no tags). (type: string) |
| `limit` | query | no | Maximum number of search results (1–50). Defaults to `10`. (type: integer, default: 10) |

### Example

```bash
curl -s 'https://www.chuckblog.com/api/content/search?q=zilliz&locale=zh&type=all&limit=5'
```

### Responses

- `200` OK — `SearchResponse`
- `400` Invalid query or path parameter. — `Error`
- `404` The requested item does not exist. — `Error`
- `429` Rate limit exceeded (120 requests per minute per IP, 60 for search). — `Error`
- `500` Unexpected server error. Retry later or report the issue. — `Error`

## GET /api/content/items

List blog posts and/or notes

Paged list of blog posts and notes, newest first.

- `type=all` merges both collections before paginating, so `pagination.total` is the merged total.
- `tag` filtering applies to blog posts only.
- Blog entries are read from the build-time search index; notes are read from Postgres.

### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `locale` | query | no | Locale filter. `all` merges `zh` and `en` results into a single ranked list. Defaults to `all`. (type: string, default: "all") |
| `type` | query | no | Restrict results to blog posts, notes, or both. Defaults to `all`. (type: string) |
| `tag` | query | no | Tag filter (blog posts only; notes have no tags). (type: string) |
| `page` | query | no | Page number, starting at 1. Defaults to `1`. (type: integer, default: 1) |
| `pageSize` | query | no | Items per page (1–50). Defaults to `10`. (type: integer, default: 10) |

### Example

```bash
curl -s 'https://www.chuckblog.com/api/content/items?locale=all&page=1&pageSize=5'
```

### Responses

- `200` OK — `ItemsResponse`
- `400` Invalid query or path parameter. — `Error`
- `404` The requested item does not exist. — `Error`
- `429` Rate limit exceeded (120 requests per minute per IP, 60 for search). — `Error`
- `500` Unexpected server error. Retry later or report the issue. — `Error`

## GET /api/content/items/{type}/{slug}

Get a blog post or note with Markdown

Full content of a single item, including raw Markdown.

- `locale` is required: slugs are locale-scoped, so the same slug may exist in both `zh` and `en`.
- Blog slugs come from the content directory name, note slugs from the database row.
- Returns `404` when the slug does not exist for that locale.

### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `type` | path | yes | (type: string) |
| `slug` | path | yes | (type: string) |
| `locale` | query | yes | Locale of the item. Required because slugs are locale-scoped. (type: string) |

### Example

```bash
curl -s 'https://www.chuckblog.com/api/content/items/blog/250520-Zilliz-Hybrid-Search?locale=zh'
```

### Responses

- `200` OK — `ItemResponse`
- `400` Invalid query or path parameter. — `Error`
- `404` The requested item does not exist. — `Error`
- `429` Rate limit exceeded (120 requests per minute per IP, 60 for search). — `Error`
- `500` Unexpected server error. Retry later or report the issue. — `Error`

## GET /api/content/tags

List blog tags with counts

Blog tags with post counts.

- Sorted by count descending, then by tag name.
- `locale` defaults to `zh`; notes are not included because they have no tags.

### Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `locale` | query | no | Locale of the tag list. Defaults to `zh`. (type: string, default: "zh") |

### Example

```bash
curl -s 'https://www.chuckblog.com/api/content/tags?locale=zh'
```

### Responses

- `200` OK — `TagsResponse`
- `400` Invalid query or path parameter. — `Error`
- `404` The requested item does not exist. — `Error`
- `429` Rate limit exceeded (120 requests per minute per IP, 60 for search). — `Error`
- `500` Unexpected server error. Retry later or report the issue. — `Error`
