# goshimmer.ai — 完整 API 参考

> 深慢Shimmer 的个人内容平台。Agent-first 设计，所有公开内容免费获取，无需认证。

## 基础信息

- Base URL: https://goshimmer.ai
- 认证: 读取无需认证，写入需 Bearer token
- 内容类型: application/json
- CORS: 允许所有来源
- Markdown for Agents: 任何页面加 Accept: text/markdown header 返回 Markdown

---

## GET /api/v1/posts

获取已发布帖子列表。

### 参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| type | string | - | 筛选帖子类型: micro, short, long |
| tag | string | - | 按标签筛选 |
| limit | integer | 20 | 每页数量，最大 100 |
| offset | integer | 0 | 分页偏移 |

### 请求示例

```bash
# 获取最新 20 篇帖子
curl https://goshimmer.ai/api/v1/posts

# 只获取短帖子
curl "https://goshimmer.ai/api/v1/posts?type=short&limit=5"

# 按标签筛选
curl "https://goshimmer.ai/api/v1/posts?tag=ai"
```

### 响应示例

```json
{
  "data": [
    {
      "id": 1,
      "slug": "hello-world",
      "type": "short",
      "status": "published",
      "title": "Hello World",
      "excerpt": "这是第一篇帖子...",
      "locale": "zh",
      "tags": ["dev", "ai"],
      "publishedAt": "2026-02-19T10:00:00.000Z",
      "createdAt": "2026-02-19T10:00:00.000Z",
      "updatedAt": "2026-02-19T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  },
  "_links": {
    "self": "/api/v1/posts?limit=20&offset=0",
    "next": null
  }
}
```

---

## GET /api/v1/posts/{slug}

获取单篇帖子，包含全部内容块 (blocks)。

### 请求示例

```bash
curl https://goshimmer.ai/api/v1/posts/hello-world
```

### 响应示例

```json
{
  "data": {
    "id": 1,
    "slug": "hello-world",
    "type": "short",
    "title": "Hello World",
    "excerpt": "这是第一篇帖子...",
    "locale": "zh",
    "tags": ["dev", "ai"],
    "publishedAt": "2026-02-19T10:00:00.000Z",
    "blocks": [
      {
        "id": 1,
        "type": "text",
        "content": "这是正文内容。支持多段落。",
        "order": 0
      },
      {
        "id": 2,
        "type": "image",
        "mediaUrl": "https://goshimmer.ai/media/photo.jpg",
        "altText": "描述文字",
        "caption": "图片说明",
        "order": 1
      }
    ]
  }
}
```

### Block 类型

| type | 字段 | 说明 |
|------|------|------|
| text | content | 文本段落 |
| image | mediaUrl, altText, caption | 图片 |
| video | mediaUrl | 视频 |
| code | content | 代码块 |
| quote | content | 引用 |
| embed_youtube | metadata.videoId | YouTube 嵌入 |
| embed_map | metadata | 地图嵌入 |
| gallery | metadata.images | 图片画廊 |

---

## 订阅

| 格式 | URL | Content-Type |
|------|-----|-------------|
| RSS 2.0 | /feed.xml | application/xml |
| JSON Feed 1.1 | /feed.json | application/feed+json |

---

## Markdown for Agents

任何页面都支持 Markdown 格式响应，由 Cloudflare 自动处理：

```bash
# 获取首页的 Markdown 版本
curl -H "Accept: text/markdown" https://goshimmer.ai/

# 获取某篇帖子的 Markdown
curl -H "Accept: text/markdown" https://goshimmer.ai/posts/hello-world
```

比 HTML 节省约 95% tokens，推荐 LLM 调用时使用。

---

## 发现入口

- OpenAPI 3.1: https://goshimmer.ai/openapi.json
- AI Plugin: https://goshimmer.ai/.well-known/ai-plugin.json
- llms.txt: https://goshimmer.ai/llms.txt
- 人类文档: https://goshimmer.ai/docs/api