以逗号分隔的要返回的文章字段。未知名称将被忽略。如需获取默认省略的正文，请包含 content_html。

fields[posts]

仅返回由指定作者撰写的文章。

filter[author_id]

filter[content_type]

仅返回在该日期或之后发布的文章。（ISO 8601 格式）

filter[published_at_gte]

仅返回在该日期或之前发布的文章。（ISO 8601 格式）

filter[published_at_lte]

filter[published]

按 slug 筛选。仅返回完全匹配的文章。

filter[slug]

filter[tag_id]

指定要包含的关联资源，以逗号分隔

Posts 的可用值：
- `tags` - 文章标签
- `authors` - 文章作者


include

每页条目数 同时接受 JSON:API 形式的 `page[size]`。

limit

order

页码（从 1 开始） 同时接受 JSON:API 形式的 `page[number]`。

page

sort

API key 的属性及已授予的权限范围。

资源类型标识符。始终为 `api_keys`。

作者显示名称
- 显示在博客上的名称
- 可以使用昵称或笔名


头像图片 URL
- 建议上传到 Inblog 存储
- 比例：1:1（正方形）
- 推荐尺寸：400x400px


资源类型标识符
- 遵循 JSON:API 标准的固定值
- 始终为 "authors"


博客语言代码（ISO 639-1）
- 默认：ko（韩语）
- 用于 HTML lang 属性


Favicon URL
- 尺寸：32x32px 或 64x64px
- ICO 或 PNG 格式


与博客关联的 Google Analytics 4 measurement ID

Google Search Console 当前是否已连接

Logo 图片 URL
- 推荐尺寸：200x50px（横向）
- 建议使用透明背景 PNG


Open Graph 特色图片 URL
- 在社交媒体上分享时显示的图片
- 推荐尺寸：1200x630px


订阅套餐（只读）
- free：免费套餐
- team：团队套餐
- enterprise：企业套餐


与此博客关联的 Google Search Console 资源 URL

与 UTC 的时差（以小时为单位）
- 韩国：9（UTC+9）
- 日本：9（UTC+9）
- 美国东部：-5（UTC-5）


资源类型标识符
- 遵循 JSON:API 标准的固定值
- 始终为 "blogs"


横幅背景颜色，采用十六进制格式

横幅标题颜色，采用十六进制格式

用于更新自定义 UI 设置的 JSON:API 风格负载。

提供任意字段子集进行更新。仅会修改所包含的字段。

用于添加自定义域名的 JSON:API 风格负载。

要连接的自定义域名。仅提供主机名，不含协议。

原始的 Vercel 域名创建响应。具体字段集会根据当前 Vercel 域名状态而有所不同。

当前是否为该博客配置了自定义域名

原始的 Vercel project-domain 状态响应

当域名尚未验证时返回的原始 Vercel 验证尝试响应

从表单到其已提交回复的关联关系。

与此表单生成的表单回复之间的关联关系。

资源类型标识符。始终为 `forms`。

回复数据（JSON 对象）。键会被解析为表单字段标签（dataLabel 或 label）

与相关的 form、post 和 blog 之间的关联关系。

与拥有该表单回复的博客之间的关联关系。

与收集此回复的表单之间的关联关系。

与嵌入该表单的文章之间的关联关系（如可用）。

资源类型标识符。始终为 `form_responses`。

包含在每个 JSON:API 响应中的 JSON:API 版本元数据。

文章标题（当 include=title 时包含）

所请求日期范围内的单篇文章流量指标数据行。

Canonical URL（用于防止重复内容）

"文章正文 HTML（由 TipTap 编辑器生成）

**生成方式：**

- Inblog 使用基于 TipTap 的所见即所得（WYSIWYG）编辑器生成 HTML

- 通过 editor.getHTML() 方法实时转换为 HTML

- 所有内容以结构化的块（block）为单位进行管理

**基础 HTML 标签：**

- 段落：`<p>`

- 标题：`<h2>`、`<h3>`、`<h4>`（不支持 h1、h5、h6）

- 列表：`<ul>`、`<ol>`、`<li>`（支持嵌套）

- 文本样式：`<strong>`、`<em>`、`<u>`、`<s>`、`<code>`

- 链接：`<a>`（无 rel 属性，已移除 nofollow）

- 引用：`<blockquote>`

- 分隔线：`<hr>`

- 换行：`<br>`

**高级格式：**

- 高亮：`<mark>`（支持多种颜色）
- 文本颜色：`<span style="color: #hex;">` - 文本对齐：`style="text-align: left|center|right;"`
- 代码块：`<pre><code class="language-*">`（支持语法高亮）

**表格：**

- `<table>`、`<thead>`、`<tbody>`、`<tr>`、`<th>`、`<td>`
- 可调整宽度的列（colwidth 属性）
- 自动水平滚动包裹

**自定义块（通过 data-type 属性区分）：**

- 图片：`<img data-type="imageBlock">` - 单张图片块
- 图片网格：`<div data-type="imageGrid">` - 网格布局
- 图片轮播：`<div data-type="imageCarousel">` - 幻灯片形式
- 标注框：`<div data-type="callOut">` - 强调框
- 链接按钮：`<div data-type="linkButton">` - CTA 按钮
- 书签：`<div data-type="bookmark">` - URL 预览

**嵌入支持：**

- YouTube：`<div data-type="youtube" data-youtube-video-id="*">`
- 表单服务：
  - Google Forms：`<div data-type="googleForm">`
  - HubSpot：`<div data-type="hubspot">`
  - Tally：`<div data-type="tally">`
  - Typeform：`<div data-type="typeform">`
- HTML 代码块：`<section data-type="code-block"><div>...</div></section>` - 插入自定义 HTML（iframe 等）。必须使用 `section` 标签 + `data-type="code-block"` + 内层 `<div>` 包裹，以匹配 tiptap schema。`<div data-type="htmlCodeBlock">` 将无法生效

**安全与限制：**

- `<script>` 标签会被自动移除（防止 XSS）
- 图片应使用 Inblog CDN（source.inblog.dev）
- 外部样式表链接受到限制
- 仅允许为受支持的嵌入服务使用 iframe

**示例：**

```html
<h2>Title</h2>
<p>Regular text with <strong>emphasis</strong>, <em>italic</em></p>
<div data-type="imageBlock" data-width="wide">
  <img src="https://source.inblog.dev/..." alt="Description">
</div>
<div data-type="callOut" data-emoji="💡">
  <p>Important information</p>
</div>
<pre><code class="language-javascript">console.log('Hello');</code></pre>
```\n"


CTA 按钮背景颜色（hex 颜色）
- 6 位 hex 代码（#RRGGBB）
- 默认：博客主题色


CTA 按钮背景颜色类型
- custom：使用 cta_color 中指定的自定义颜色
- preset：使用博客预设颜色
- default：使用博客主题色


CTA 按钮文本颜色（hex 颜色）
- 6 位 hex 代码（#RRGGBB）
- 默认：#ffffff（白色）


CTA 按钮文本颜色类型
- custom：使用 cta_text_color 中指定的自定义颜色
- default：根据按钮背景对比度自动计算（#ffffff 或 #000000）
- 在未将此项设为 'custom' 的情况下发送 cta_text_color，颜色可能会被编辑器覆盖


文章摘要描述（SEO meta description）

要附加到文章的 Form ID。设为 null 可移除该表单。

SEO meta description（显示在搜索结果中）

SEO meta title（显示在浏览器标签页中）

URL 友好的唯一标识符。仅允许字母、数字和连字符

文章标题（建议控制在 60 个字符以内以利于 SEO）

文章与标签和作者之间的关系。

资源类型标识符
- 按照 JSON:API 标准为固定值
- 始终为 "posts"


随文章一并包含的关联资源，例如标签或作者。

单篇文章的流量时间序列数据行。

源路径（重定向来源）
- 必须以 / 开头
- 必须唯一
- 不支持通配符


重定向类型
- 307：Temporary Redirect
- 308：Permanent Redirect


目标路径（重定向目的地）
- 必须以 / 开头
- 也允许外部 URL（http:// 或 https://）


资源类型标识符
- 按照 JSON:API 标准的固定值
- 始终为 "redirects"


关联资源标识符、资源标识符数组，或 `null`。

资源 ID（必填）
- 字符串格式
- 在其类型内必须唯一

**重要：** 示例值（123）仅为样例。实际使用时：
- 获取 Tag ID：`GET /v1/tags`
- 获取 Author ID：`GET /v1/authors`

使用不存在的 ID 将返回 400 错误。


资源类型（必填）
- posts、tags、authors 等。


OAuth 流程中使用的 Redirect URI。省略它以使用默认的仪表盘回调。

操作完成后 Search Console 是否仍保持连接

已连接的 Search Console 资源 URL。未连接时返回 `null`。

所请求日期范围内的 Search Console 效果数据行。

Tag 名称（区分大小写，必须唯一）

URL 友好的唯一标识符
- 仅允许小写字母、数字和连字符
- 可以根据 name 自动生成


资源类型标识符
- 按照 JSON:API 标准为固定值
- 始终为 "tags"


所请求日期范围内的流量时间序列数据行。

对已认证用户可见的博客属性。

当前用户是否被允许在该博客上发布文章

已连接的自定义域名（如已配置）

资源类型标识符。始终为 `blogs`。

使用 API key 作为 Bearer token。

格式：`Authorization: Bearer YOUR_API_KEY`

API key 可在 inblog 控制台中生成。


使用已签名的用户 JWT 作为 Bearer token。

格式：`Authorization: Bearer USER_JWT`

此方案用于用户范围的端点，例如 `/user/blogs`。


Inblog Support

使用 Inblog API 管理博客内容。

## 🚀 快速开始

### 1. 获取 API Key
从控制台获取你的 API key：
1. 登录 [Inblog Dashboard](https://inblog.ai/dashboard)
2. 进入 Settings → API Keys
3. 点击 "Create New API Key" 按钮
4. 选择所需的权限范围（permission scopes）
5. 安全地保管你的 API key

### 2. 第一个请求
```bash
curl -X GET https://api.inblog.ai/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 3. 使用 npm 开发者工具
如果你不想手动调用 API，可以安装 CLI：
```bash
npm install -g @inblog/cli
inblog auth login
```
对于 AI 编程助手，请安装 AI Skills：
```bash
npx @inblog/ai-skills
```
CLI 可让你在终端中管理文章、图片、标签、作者、重定向、表单、分析数据以及博客设置。AI Skills 会为 Codex、Claude Code、Cursor、GitHub Copilot 和 Gemini 等工具安装 Inblog 工作流。
请阅读 [Developer Tools guide](/docs/developer-tools/inblog-cli-and-ai-skills)。

### 4. Content-Type
- **请求**：`Content-Type: application/json` 或 `application/vnd.api+json`
- **响应**：`Content-Type: application/vnd.api+json`

## 📋 主要功能

- **文章管理**：创建、更新、删除和发布文章
- **标签与作者**：管理分类和作者信息
- **博客设置**：修改基本设置
- **URL 重定向**：配置 307（临时）和 308（永久）重定向
- **表单与提交**：查看潜在客户表单和提交数据
- **JSON:API 标准**：一致的响应格式

## 🔐 身份认证

所有 API 请求都需要通过 Authorization 头进行 Bearer token 认证：

```
Authorization: Bearer YOUR_API_KEY
```
## 📚 了解更多

- [JSON:API Specification](https://jsonapi.org/)

Proprietary

Inblog API

检索博客中注册的所有作者资料。

移除该作者与本博客中文章的关联。作者资料本身不会被删除。

更新作者的资料信息。

**可编辑字段：**
- author_name：作者显示名称
- avatar_url：资料图片 URL

**图片处理：**
默认情况下，资料图片 URL 会被上传到 Inblog R2 storage。
若要保留原始 URL，请使用 `preserve_external_images=true` 查询参数。


保留外部图片 URL，而不上传到 R2 storage

preserve_external_images

使用 PUT 更新作者的资料信息。

**可编辑字段：**
- author_name：作者显示名称
- avatar_url：资料图片 URL

**图片处理：**
默认情况下，资料图片 URL 会被上传到 Inblog R2 storage。
若要保留原始 URL，请使用 `preserve_external_images=true` 查询参数。


获取每篇文章的性能指标，包括访问量、点击量、自然流量和转化率。

开始日期（YYYY-MM-DD）。默认为 28 天前。

start_date

结束日期（YYYY-MM-DD）。默认为今天。

end_date

设置为 "title" 可在响应中包含文章标题

按天或按小时粒度获取特定文章随时间变化的流量数据。

interval

获取特定文章的流量来源分析，展示引荐来源数据。

获取流量来源分析，展示按访问量排序的引荐来源数据。

获取按天或按小时粒度统计的全博客流量数据。包含 visits、clicks、自然流量和页面类型细分。

type

获取你博客当前的横幅和 UI 自定义设置。

更新横幅和 UI 自定义设置。仅更新所提供的字段。

从你的博客中移除自定义域名。博客将恢复为默认的 subdomain。

检查当前的自定义域名配置和 DNS 验证状态。

为你的博客添加自定义域名。返回域名配置，包括验证所需的 Vercel DNS 设置。

检索与当前 API key 关联的博客的信息。

更新博客名称、描述、logo、favicon 和特色图片等基本设置。

**图片处理：**
默认情况下，logo、favicon 和特色图片 URL 会被上传到 Inblog R2 storage。
若要保留原始 URL，请使用 `preserve_external_images=true` 查询参数。


使用 PUT 更新博客名称、描述、logo、favicon 和特色图片等基本设置。

**图片处理：**
默认情况下，logo、favicon 和特色图片 URL 会被上传到 Inblog R2 storage。
若要保留原始 URL，请使用 `preserve_external_images=true` 查询参数。


用 OAuth 授权码交换令牌以完成 Search Console 连接。

断开 Google Search Console 与你的博客的连接。移除已存储的 OAuth 令牌。

从 Google Search Console 获取关键词级别的搜索效果数据。返回每个关键词的 clicks、impressions、CTR 和平均 position。

获取用于连接 Search Console 的 Google OAuth URL。对于基于 CLI 的认证流程，请使用可选的 redirect_uri 参数。

用于 CLI 回调的自定义 redirect URI

redirect_uri

从 Google Search Console 获取页面级别的搜索效果数据。返回每个页面的 clicks、impressions、CTR 和平均 position。

检查 Google Search Console 是否已连接到你的博客。

获取博客的分页表单响应列表。你可以按表单 ID 进行筛选，并且每条响应在可用时都会包含相关表单、文章和博客的关系标识符。

form_id

通过 ID 获取特定表单响应的详细信息。

获取博客的分页表单列表。每个表单都包含其当前的响应数。

通过 ID 获取特定表单的详细信息。

获取当前生效 API key 的信息和权限。

查看已连接的博客以及已授予的权限列表。


获取博客中已发布的文章列表。
你可以指定页码和每页数量，并包含标签或作者信息。
列表响应中不包含正文(content_html)。如需获取，请通过 fields[posts] 显式请求。


创建一篇新的博客文章。

**必填字段：**
- title：文章标题
- slug：URL slug（在博客内必须唯一）

**图片处理：**
默认情况下，外部图片 URL 会被上传到 Inblog R2 存储。
若要保留原始 URL，请使用 `preserve_external_images=true` 查询参数。

**限制：**
- 不允许使用 id 字段。文章 ID 由服务器自动生成。
- 若要更新已有文章，请使用 PATCH /posts/{id}。

**响应代码：**
- 201：文章创建成功
- 400：错误请求（例如包含了 id 字段）
- 409：Slug 已存在

外部图片 URL 将被自动保存到 Inblog 存储。


保留外部图片 URL，而不是上传到 R2 存储

永久删除文章。此操作无法撤销。


按 ID 获取特定文章的详细信息。

更新现有文章的内容和设置。

**图片处理：**
外部图片 URL 默认会上传到 Inblog R2 存储。
若要保留原始 URL，请使用 `preserve_external_images=true` 查询参数。


保留外部图片 URL，而不上传到 R2 存储

使用 PUT 更新文章。当前实现将 PUT 和 PATCH 视为完全相同。


用一组新的作者替换文章上的所有作者。
所有现有作者都会被移除，仅保留新指定的作者。


向文章添加一个或多个作者。
已关联的作者会自动跳过。


authorId

立即发布文章或将其安排在稍后发布。

**支持的操作**：
- `publish` - 立即发布
- `unpublish` - 取消发布
- `schedule` - 安排发布（仅限将来的时间）


用一组新标签替换文章上的所有标签。
所有现有标签都会被移除，仅保留新指定的标签。


向文章添加一个或多个标签。
已关联的标签会被自动跳过。


tagId

检索为博客配置的所有 URL 重定向规则。

创建一条新的重定向规则。
**必填字段：** - from_path：要重定向的源路径 - to_path：重定向到的目标路径
**响应代码：** - 201：重定向创建成功 - 409：from_path 已存在


永久删除重定向规则。⚠️ 此操作无法撤销！

检索指定重定向规则的详细信息。

使用 PUT 更新重定向规则。当前实现将 PUT 和 PATCH 视为相同处理。

创建一个新标签。

**必填字段：**
- name：标签名称
- slug：URL slug（在博客内必须唯一）

**响应代码：**
- 201：标签创建成功
- 409：slug 已存在


删除标签。现有的文章与标签关联会随标签一并移除。


按 ID 获取指定标签的详细信息。

使用 PUT 更新标签。当前实现对 PUT 和 PATCH 的处理完全相同。


上传图片文件并获取一个公开 URL。

**请求流程：**
- 通过 `fileKey` 查询参数传入目标 key。
- 将原始文件字节作为请求体发送。
- 允许的 MIME 类型：`image/png`、`image/jpeg`、`image/gif`、`image/webp`、`image/svg+xml`、`image/x-icon`

**限制：**
- 最大文件大小：10MB
- 适用上传速率限制。


目标对象 key。示例：`post-image/2026-04-02T10:00:00.000Z-uuid`

fileKey

获取当前已认证用户可以访问的博客列表，包含权限元数据。
