API

这是译文。 以德语版本为准。本文与其有出入之处，以德语文本为准。你可以在页面底部切换语言。

概览

v2 让你自己的程序与 tellmelo 对话：每个请求一个密钥，返回 JSON，所有列表都以相同方式分页。规则与应用中相同。

每个路径都以本站地址下的 /api/v2 开头。
请求和响应都是 UTF-8 编码的 JSON。字段名、代码和值都是英文，并保持英文。
密钥代表你的账号：你在应用里看不到的，它也读不到。

https://tellmelo.com/api/v2

快速开始

在“设置 → 应用与数据 → API”中创建密钥并复制。它只显示一次。
用它调用根路径。响应会显示版本、密钥权限以及本分钟剩余的请求数。
所有路径的用法都一样：请求头带密钥，返回 JSON，列表用 items 和 next。

curl -H "Authorization: Bearer tm_key_…" https://tellmelo.com/api/v2

{
  "name": "tellmelo",
  "version": "2.10",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/legal/api",
  "spec": "/api/v2/openapi.json"
}

接下来：/me 获取你的个人主页，/posts 获取公开帖子，/feed 获取你的动态。

试一试

选择一项任务，填写字段，然后复制请求或直接从这里发送。写入操作会先询问。代码从 TELLMELO_KEY 读取密钥。

任务

read API 版本和本站名称。

curl \
  -H "Authorization: Bearer $TELLMELO_KEY" \
  "https://tellmelo.com/api/v2"

你的密钥只保留在此页面，直到你关闭它。

你的密钥

每个账号一个密钥。它以 tm_key_ 开头，只显示一次。丢了？新建一个；旧的会失效。

在“设置 → 应用与数据 → API”中创建。它放在请求头中：

curl -H "Authorization: Bearer tm_key_…" \
  https://tellmelo.com/api/v2/posts

或者，如果更方便，放在单独的请求头里：

curl -H "X-Tellmelo-Key: tm_key_…" https://tellmelo.com/api/v2

不要放在 URL 里：它会出现在日志和浏览器历史中。

同一个密钥也可加载图片：每个 url 都指向 /api/media；在那里同样把密钥放在请求头中。

curl -H "Authorization: Bearer tm_key_…" \
  -o picture.webp "https://tellmelo.com/api/media?id=…"

密钥能做什么

密钥拥有两种权限之一，下面每个路径都注明了所需权限：

read：读取。公开的帖子、个人主页、群组和标签，以及你的动态、通知和私信。
write：操作。发帖、回复、投票、发送私信、关注、加入、屏蔽、将通知标为已读。

任何密钥都做不到的事

任何密钥都无法触及密码、邮箱地址、账号类型、地点、角色、删除、会话、推送设备或其他密钥，也无法触及管理后台或群组管理。密码所保护的，任何密钥都做不到。

请求与响应

处处都是 JSON。 每个响应都是 UTF-8 编码的 application/json，包括错误。只有图片以图片形式返回。
你发送的内容。 POST 在正文中以 JSON 携带字段。如果某个字段也出现在 URL 中，以正文为准。
时间是自 1970 年 1 月 1 日（UTC）起的毫秒数。
ID 是字符串。只能整体比较。
每个字段始终存在。 缺失的值为 null；列表可以为空。
文本是纯文本，与写入时完全一致。#标签、@名字 和链接保持原样，本站自定义表情也以 :name: 形式保留；其图片列在 /emojis 中。
图片是相对地址 /api/media?id=…。请求头中没有密钥会返回 401。

分页

每个列表都接受 limit 和 cursor，并返回 items 和 next。把 next 作为 cursor 传回即可获取下一页；next 为空时即结束。游标是不透明的：不要解析，也不要自己构造。

{ "items": [ … ], "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx" }

curl -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts?limit=20&cursor=MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"

不传 limit 时为 20 条，最多 50 条。有些列表不分页；它们的 next 始终为 null。

只取新内容

每个响应都带有 ETag。下次请求时作为 If-None-Match 传回：如果没有变化，你会收到无正文的 304。

ETag: W/"3Qk1mJ7fQe2Yb0sVxT9aL4pNdRc"
If-None-Match: W/"3Qk1mJ7fQe2Yb0sVxT9aL4pNdRc"  →  304

例外：/feed 没有 ETag，因为它的顺序一直在变；写入操作永远不会返回 304。

限额

每个密钥每分钟可发送 120 个请求，“机构”套餐为 600 个，除非管理员另有设置。超出后会收到 429，且不会执行任何操作。等一分钟再发送请求。

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1758624060

写入操作也计入应用的限额，例如几分钟内可发多少帖子。这同样返回带 rate_limited 的 429。

请求头

除密钥外，不需要任何请求头。

你发送的

请求头	含义
`Authorization`	携带密钥：`Bearer tm_key_…`。通常的方式。
`X-Tellmelo-Key`	密钥，作为 `Authorization` 的替代。
`Content-Type`	`application/json`，用于带正文的请求。
`If-None-Match`	上一次响应的 `ETag`。如果此后没有变化，响应为无正文的 `304`。

返回的

请求头	含义
`ETag`	本次响应的指纹（`W/`）。作为 `If-None-Match` 传回。
`X-RateLimit-Limit`	此密钥每分钟可发送多少请求。
`X-RateLimit-Remaining`	当前分钟内还剩多少。
`X-RateLimit-Reset`	下一分钟何时开始，以自 1970 年（UTC）起的秒数表示。
`X-Tellmelo-Scope`	此密钥能做什么：`read` 或 `read write`。
`Retry-After`	收到 `429` 时：再次请求前需要等待的秒数。
`WWW-Authenticate`	没有密钥返回 `401` 时：`Bearer`。
`Cache-Control`	`no-store`：任何代理都不能缓存响应。你仍可以用 `ETag` 检查。

出错时

错误以 JSON 返回：error 中是供程序使用的固定英文代码，message 中是给人看的句子，并附相应的状态码。只比较代码；句子可能会变。

{ "error": "rate_limited",
  "message": "Too many requests. Try again in a minute.",
  "limit": 120 }

有些错误会多带一个字段：缺少密钥的 401 带 docs，429 带 limit。

状态	代码	含义
`400`	`bad_request`	请求无法读取、缺少必填字段或某个值不被允许。
`401`	`key_missing`	请求头中没有密钥。
`401`	`key_invalid`	密钥无效：输错、已被替换，或账号已被封禁。
`401`	`unauthorized`	因未登录被拒绝，原因与密钥无关。
`403`	`scope_missing`	密钥缺少所需权限，通常是 `write`。
`403`	`account_data_locked`	密码、邮箱地址或删除等账号数据不对密钥开放。
`403`	`forbidden`	你的账号不能这样做，例如因权限被收回或被屏蔽。
`404`	`unknown_path`	没有这个路径，或不支持该方法。
`404`	`not_found`	未找到，或你无权查看。
`409`	`conflict`	与已有内容冲突，例如名称已被占用。
`413`	`too_large`	对本站来说太大。
`422`	`unprocessable`	可以读取，但这种形式无法处理。
`429`	`rate_limited`	请求太多。未执行任何操作；请稍候再试。
`500`	`internal_error`	服务器出了问题。

版本

版本号在路径中。只要写的是 v2，路径和字段就保持不变；只会新增内容。

新增内容会提升第二位数字。每个路径都注明了从哪个版本开始提供。

/api/v1/ 已停用：旧路径返回 410，并在正文中指明新路径。

端点

先一览所有路径，再逐个附上示例。

路径	权限	用途
入口
GET`/api/v2`	`read`	API 版本和本站名称。
帖子
GET`/api/v2/posts`	`read`	公开帖子，最新的在前。
GET`/api/v2/posts/{id}`	`read`	按 `id` 获取单条帖子。
POST`/api/v2/posts`	`write`	发布帖子。
DELETE`/api/v2/posts/{id}`	`write`	删除你自己的一条帖子。
回复
GET`/api/v2/posts/{id}/replies`	`read`	帖子的回复，不含已屏蔽的账号。
POST`/api/v2/posts/{id}/replies`	`write`	回复帖子。
投票
POST`/api/v2/posts/{id}/vote`	`write`	参与投票。
个人主页
GET`/api/v2/profiles/{handle}`	`read`	按短名称获取个人主页。
GET`/api/v2/profiles/{handle}/posts`	`read`	某个个人主页的公开帖子，最新的在前。
群组
GET`/api/v2/communities`	`read`	本站的开放群组。
GET`/api/v2/communities/{id}`	`read`	按 `id` 获取单个群组。
GET`/api/v2/communities/{id}/posts`	`read`	某个群组的公开帖子，最新的在前。
发现
GET`/api/v2/tags`	`read`	当前流行的标签。
GET`/api/v2/search`	`read`	在帖子、名字、短名称和标签中搜索。
GET`/api/v2/emojis`	`read`	本站自定义表情及其图片地址。
你的账号
GET`/api/v2/me`	`read`	你自己的个人主页，包含其他路径需要的 `id`。
GET`/api/v2/feed`	`read`	你自己的动态，与应用中的排列方式相同。
通知
GET`/api/v2/notifications`	`read`	你的通知，最新的在前。
POST`/api/v2/notifications/read`	`write`	将你的通知标为已读。
私信
GET`/api/v2/conversations`	`read`	你的收件箱：每个对话一行，最新的在前。
GET`/api/v2/conversations/{with}/messages`	`read`	某个对话中的私信，最新的在前。
POST`/api/v2/conversations/{with}/messages`	`write`	在对话中发送私信。
POST`/api/v2/conversations/{with}/read`	`write`	将某个对话的所有私信标为已读。
关系
POST`/api/v2/relations`	`write`	点赞、收藏、转发、关注、加入、屏蔽、静音，取决于 `kind`。

入口

每个程序的第一个请求：密钥能用吗，它能做什么？

GET`/api/v2`

API 版本和本站名称。

权限 read
带 ETag
自 v2.0

末尾不要加斜杠：/api/v2/ 会以 308 重定向到 /api/v2，并非所有程序都会跟随。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2"

响应

返回一个 Service。

示例

{
  "name": "tellmelo",
  "version": "2.10",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/legal/api",
  "spec": "/api/v2/openapi.json"
}

可能的状态： 200304401429

帖子

读取公开帖子、发布自己的帖子，以及再次删除。

GET`/api/v2/posts`

公开帖子，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

在公开路径上，counts.likes 和 counts.reposts 始终为 0，pinned 为 false。

群组中的帖子不在这里，而在 /communities/{id}/posts。

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts?limit=20"

响应

返回一页 Post，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304401429

GET`/api/v2/posts/{id}`

按 id 获取单条帖子。

权限 read
带 ETag
自 v2.0

在公开路径上，counts.likes 和 counts.reposts 始终为 0，pinned 为 false。

群组中的帖子不在这里，而在 /communities/{id}/posts。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1"

响应

返回一个 Post。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "text": "The bees are back in the garden 🐝 #garden",
  "kind": "poll",
  "author": {
    "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
    "handle": "mara",
    "name": "Mara 🌻",
    "verified": true,
    "accountKind": "person"
  },
  "community": {
    "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
    "name": "Urban Gardening"
  },
  "media": [
    {
      "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "kind": "image",
      "poster": null
    }
  ],
  "poll": {
    "options": [
      {
        "text": "Lavender",
        "votes": 12
      },
      {
        "text": "Sunflowers",
        "votes": 7
      },
      {
        "text": "Clover",
        "votes": 3
      }
    ],
    "total": 22,
    "multiple": false,
    "endsAt": 1758710400000,
    "running": true,
    "resultsVisible": true,
    "myVotes": [
      0
    ]
  },
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 4,
    "likes": 31,
    "reposts": 2
  },
  "pinned": false,
  "createdAt": 1758624000000
}

可能的状态： 200304400401404429

POST`/api/v2/posts`

发布帖子。

权限 write
自 v2.0

帖子需要文字或投票。长度、投票选项和频率由本站设定；超出时会收到 400 或 429。

目前还不能通过 API 附加图片，只能在应用中操作。

参数

名称	类型	含义
`text`在正文中	`string`可选	帖子、回复或私信的文字。
`community`在正文中	`string`可选	帖子所属群组的 `id`。不传则不属于任何群组。
`quotes`在正文中	`string`可选	本帖引用的帖子的 `id`。
`poll`在正文中	`string[]`可选	选项，以文本列表形式。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"The bees are back in the garden 🐝 #garden"}' \
  "https://tellmelo.com/api/v2/posts"

响应

返回一个 Created。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

可能的状态： 200400401403429

DELETE`/api/v2/posts/{id}`

删除你自己的一条帖子。

权限 write
自 v2.0

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。

请求示例

curl -X DELETE \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

帖子下的回复，以带 parentId 的列表形式。

GET`/api/v2/posts/{id}/replies`

帖子的回复，不含已屏蔽的账号。

权限 read
可分页
带 ETag
自 v2.0

列表是扁平的，按写作顺序排列；parentId 可将其组成树。一页总是包含完整的讨论串。已屏蔽账号的回复不包含在内。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies?limit=20"

响应

返回一页 Reply，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a",
      "text": "Same here, the lavender is full of them.",
      "kind": "post",
      "author": {
        "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
        "handle": "jon",
        "name": "Jon",
        "verified": false,
        "accountKind": "person"
      },
      "community": null,
      "media": [],
      "poll": null,
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 0,
        "likes": 3,
        "reposts": 0
      },
      "pinned": false,
      "createdAt": 1758624600000,
      "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "parentId": null
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401404429

POST`/api/v2/posts/{id}/replies`

回复帖子。

权限 write
自 v2.0

慢速模式下，每人每 10 分钟可回复一次，否则返回 429。作者及其关注的账号不受限制。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。
`text`在正文中	`string`必填	帖子、回复或私信的文字。
`parentId`在正文中	`string`可选	本回复所回复的回复的 `id`。不传则直接回复帖子。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"Same here, the lavender is full of them."}' \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/replies"

响应

返回一个 Created。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

可能的状态： 200400401403404429

投票

投票是设置了 poll 的帖子。投票操作有单独的路径。

POST`/api/v2/posts/{id}/vote`

参与投票。

权限 write
自 v2.0

在你投票或投票结束之前，各选项的票数为 null。total 始终存在。

参数

名称	类型	含义
`id`在路径中	`string`必填	帖子的 `id`。
`option`在正文中	`integer`必填	哪个选项，从 0 开始计数。多选时每个选项调用一次。
`retract`在正文中	`boolean`可选	`true` 撤回投票。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"option":0}' \
  "https://tellmelo.com/api/v2/posts/5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1/vote"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

个人主页

按短名称获取公开个人主页及其发布的内容。

GET`/api/v2/profiles/{handle}`

按短名称获取个人主页。

权限 read
带 ETag
自 v2.0

参数

名称	类型	含义
`handle`在路径中	`string`必填	个人主页的短名称。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/profiles/mara"

响应

返回一个 Profile。

示例

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

可能的状态： 200304400401404429

GET`/api/v2/profiles/{handle}/posts`

某个个人主页的公开帖子，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

在公开路径上，counts.likes 和 counts.reposts 始终为 0，pinned 为 false。

群组中的帖子不在这里，而在 /communities/{id}/posts。

参数

名称	类型	含义
`handle`在路径中	`string`必填	个人主页的短名称。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/profiles/mara/posts?limit=20"

响应

返回一页 Post，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401404429

群组

开放群组及其帖子。

GET`/api/v2/communities`

本站的开放群组。

权限 read
带 ETag
自 v2.0

按成员数排序，不分页；next 始终为 null。

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/communities?limit=20"

响应

返回一页 Community，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
      "name": "Urban Gardening",
      "description": "Balconies, allotments, rooftops: whatever grows.",
      "tags": [
        "garden",
        "bees"
      ],
      "members": 312,
      "joinPolicy": "open",
      "visibility": "open"
    }
  ],
  "next": null
}

可能的状态： 200304401429

GET`/api/v2/communities/{id}`

按 id 获取单个群组。

权限 read
带 ETag
自 v2.0

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60"

响应

返回一个 Community。

示例

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening",
  "description": "Balconies, allotments, rooftops: whatever grows.",
  "tags": [
    "garden",
    "bees"
  ],
  "members": 312,
  "joinPolicy": "open",
  "visibility": "open"
}

可能的状态： 200304400401404429

GET`/api/v2/communities/{id}/posts`

某个群组的公开帖子，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

在公开路径上，counts.likes 和 counts.reposts 始终为 0，pinned 为 false。

参数

名称	类型	含义
`id`在路径中	`string`必填	群组的 `id`。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/communities/c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60/posts?limit=20"

响应

返回一页 Post，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401404429

发现

趋势、搜索和本站自定义表情。

GET`/api/v2/tags`

当前流行的标签。

权限 read
带 ETag
自 v2.0

按分数最多 10 个热门标签：每次使用计 1 分，每 3 天减半，同一账号每天最多计 3 分。posts 是四舍五入后的分数。limit 只会缩短列表。团队推荐的标签可能排得更靠前。

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/tags?limit=10"

响应

返回一页 Tag，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "tag": "garden",
      "posts": 58
    }
  ],
  "next": null
}

可能的状态： 200304401429

GET`/api/v2/search`

在帖子、名字、短名称和标签中搜索。

权限 read
带 ETag
自 v2.0

只搜索公开内容：群组外的帖子、个人主页和标签。limit 对每类分别生效。

参数

名称	类型	含义
`q`在查询中	`string`必填	要搜索的词。
`type`在查询中	`string`可选	哪种结果。不传则返回所有类型。`allpostsprofilestags`
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/search?q=garden&type=posts"

响应

返回一个 SearchResult。

示例

{
  "posts": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "profiles": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "tags": [
    {
      "tag": "garden",
      "posts": 58
    }
  ]
}

可能的状态： 200304400401429

GET`/api/v2/emojis`

本站自定义表情及其图片地址。

权限 read
带 ETag
自 v2.1

在文本中，表情显示为 :name:。用此列表中的图片替换；未知名称保持为文本。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/emojis"

响应

返回一页 Emoji，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "name": "tellmelo",
      "url": "/api/media?id=e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
    }
  ],
  "next": null
}

可能的状态： 200304401429

你的账号

你的个人主页和动态。

GET`/api/v2/me`

你自己的个人主页，包含其他路径需要的 id。

权限 read
带 ETag
自 v2.0

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/me"

响应

返回一个 Profile。

示例

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

可能的状态： 200304401429

GET`/api/v2/feed`

你自己的动态，与应用中的排列方式相同。

权限 read
可分页
自 v2.0

没有 ETag，因为顺序一直在变。你已开始的列表在结束前保持不变。

参数

名称	类型	含义
`tab`在查询中	`string`可选	哪个动态：`for-you`、`following`、`latest` 或 `bookmarks`。默认 `latest`。`for-youfollowinglatestbookmarks`
`tag`在查询中	`string`可选	只返回与此标签有关的帖子：用它写的或服务器在其中识别出的。不传则不过滤。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/feed?tab=following&limit=20"

响应

返回一页 Post，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200400401429

通知

你的账号周围发生了什么，逐页查看。

GET`/api/v2/notifications`

你的通知，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

读取不会将任何内容标为已读；POST /notifications/read 才会。同一帖子上的同类事件共用一行；more 表示数量。

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/notifications?limit=20"

响应

返回一页 Notification，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "kind": "like",
      "text": null,
      "actor": {
        "handle": "jon",
        "name": "Jon"
      },
      "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "read": false,
      "more": 2,
      "createdAt": 1758624300000,
      "updatedAt": 1758624900000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304401429

POST`/api/v2/notifications/read`

将你的通知标为已读。

权限 write
自 v2.0

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/notifications/read"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200401403429

私信

你的收件箱和对话。对话以对方账号命名。

GET`/api/v2/conversations`

你的收件箱：每个对话一行，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

参数

名称	类型	含义
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/conversations?limit=20"

响应

返回一页 Conversation，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "with": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
      "handle": "jon",
      "name": "Jon",
      "excerpt": "See you on Saturday at the market!",
      "truncated": false,
      "fromMe": true,
      "lastMessageId": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
      "unread": 0,
      "updatedAt": 1758624060000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304401429

GET`/api/v2/conversations/{with}/messages`

某个对话中的私信，最新的在前。

权限 read
可分页
带 ETag
自 v2.0

读取不会将任何内容标为已读；POST /conversations/{with}/read 才会。

参数

名称	类型	含义
`with`在路径中	`string`必填	另一个账号的 `id`。对话本身没有 `id`。
`limit`在查询中	`integer`可选	每页条目数：默认 20，最多 50。
`cursor`在查询中	`string`可选	上一个响应中的 `next`。不传则从头开始。

请求示例

curl \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages?limit=20"

响应

返回一页 Message，形式为 `items` 和 `next`。

示例

{
  "items": [
    {
      "id": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
      "text": "See you on Saturday at the market!",
      "from": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "to": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
      "read": true,
      "media": [],
      "replyTo": null,
      "createdAt": 1758624060000
    }
  ],
  "next": "MTc1ODYyNDAwMDAwMDo1ZjBjMmE5ZS04ZDQx"
}

可能的状态： 200304400401404429

POST`/api/v2/conversations/{with}/messages`

在对话中发送私信。

权限 write
自 v2.0

适用应用的规则：屏蔽了你的人无法联系，对方的设置也会生效。

目前还不能通过 API 附加图片，只能在应用中操作。

参数

名称	类型	含义
`with`在路径中	`string`必填	另一个账号的 `id`。对话本身没有 `id`。
`text`在正文中	`string`必填	帖子、回复或私信的文字。
`replyTo`在正文中	`string`可选	本条私信所回复的本对话中较早私信的 `id`。自 2.2 起。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"text":"See you on Saturday at the market!"}' \
  "https://tellmelo.com/api/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/messages"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

POST`/api/v2/conversations/{with}/read`

将某个对话的所有私信标为已读。

权限 write
自 v2.1

参数

名称	类型	含义
`with`在路径中	`string`必填	另一个账号的 `id`。对话本身没有 `id`。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  "https://tellmelo.com/api/v2/conversations/a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05/read"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403404429

关系

点赞、收藏、转发、关注、加入、屏蔽：同一个路径，用 active 设置和解除。

POST`/api/v2/relations`

点赞、收藏、转发、关注、加入、屏蔽、静音，取决于 kind。

权限 write
自 v2.0

对 like、save 和 repost，target 是帖子；对 join 是群组；对 follow、block 和 mute 是账号。active: false 解除关系。

参数

名称	类型	含义
`kind`在正文中	`string`必填	哪种关系：`like`、`save`、`repost`、`follow`、`join`、`block` 或 `mute`（自 2.2 起）。`likesaverepostfollowjoinblockmute`
`target`在正文中	`string`必填	帖子、个人主页或群组的 `id`，取决于 `kind`。
`active`在正文中	`boolean`可选	`true` 建立关系，`false` 解除关系。

请求示例

curl -X POST \
  -H "Authorization: Bearer tm_key_…" \
  -H "Content-Type: application/json" \
  -d '{"kind":"like","target":"5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1","active":true}' \
  "https://tellmelo.com/api/v2/relations"

响应

返回一个 Ok。

示例

{
  "ok": true
}

可能的状态： 200400401403429

对象

所有对象，逐个字段说明。[] 表示列表。

`Service`

根路径的响应：谁在响应，以及此密钥能做什么。

字段	类型	含义
`name`	`string`	始终为 `tellmelo`。
`version`	`string`	API 版本，例如 `2.1`。
`scope`	`string`	此密钥能做什么：`read` 或 `read write`。
`rateLimit`	`RateLimit`	此密钥的额度。
`docs`	`string`	本文档的位置，即本站上的路径。
`spec`	`string`	机器可读描述的位置。

示例

{
  "name": "tellmelo",
  "version": "2.10",
  "scope": "read write",
  "rateLimit": {
    "limit": 120,
    "remaining": 117
  },
  "docs": "/legal/api",
  "spec": "/api/v2/openapi.json"
}

`RateLimit`

此密钥在当前分钟的额度。

字段	类型	含义
`limit`	`integer`	每分钟请求数。
`remaining`	`integer`	本分钟剩余的数量。

示例

{
  "limit": 120,
  "remaining": 117
}

`Post`

帖子，在各处形式相同。

字段	类型	含义
`id`	`string`	帖子的 id。
`text`	`string`或 null	原文（只有投票或只有图片的帖子为 `null`）。
`kind`	`string`	帖子的类型。 `post` — 带文字、图片或引用的帖子。 `poll` — 带投票的帖子。
`author`	`ProfileBrief`	作者。
`community`	`CommunityBrief`或 null	所在群组（不在任何群组中时为 `null`）。
`media`	`Media[]`	其图片，按顺序；没有则为空。
`poll`	`Poll`或 null	投票（没有则为 `null`）。
`quotes`	`string`或 null	本帖引用的帖子的 id。
`continues`	`string`或 null	本帖作为补充所续写的帖子的 id。
`counts`	`Counts`	回复、赞和转发。
`pinned`	`boolean`	是否置顶在作者个人主页顶部。
`createdAt`	`integer`	写作时间。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "text": "The bees are back in the garden 🐝 #garden",
  "kind": "poll",
  "author": {
    "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
    "handle": "mara",
    "name": "Mara 🌻",
    "verified": true,
    "accountKind": "person"
  },
  "community": {
    "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
    "name": "Urban Gardening"
  },
  "media": [
    {
      "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
      "kind": "image",
      "poster": null
    }
  ],
  "poll": {
    "options": [
      {
        "text": "Lavender",
        "votes": 12
      },
      {
        "text": "Sunflowers",
        "votes": 7
      },
      {
        "text": "Clover",
        "votes": 3
      }
    ],
    "total": 22,
    "multiple": false,
    "endsAt": 1758710400000,
    "running": true,
    "resultsVisible": true,
    "myVotes": [
      0
    ]
  },
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 4,
    "likes": 31,
    "reposts": 2
  },
  "pinned": false,
  "createdAt": 1758624000000
}

`Reply`

帖子下的回复：多两个字段的帖子。

Post 的所有字段，另外还有：

字段	类型	含义
`postId`	`string`	整个讨论所属的帖子。
`parentId`	`string`或 null	本回复所回复的回复（直接回复帖子时为 `null`）。

示例

{
  "id": "9e4b1c7d-2a3f-4d5e-8b6c-0f1e2d3c4b5a",
  "text": "Same here, the lavender is full of them.",
  "kind": "post",
  "author": {
    "id": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
    "handle": "jon",
    "name": "Jon",
    "verified": false,
    "accountKind": "person"
  },
  "community": null,
  "media": [],
  "poll": null,
  "quotes": null,
  "continues": null,
  "counts": {
    "replies": 0,
    "likes": 3,
    "reposts": 0
  },
  "pinned": false,
  "createdAt": 1758624600000,
  "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "parentId": null
}

`Counts`

帖子有多少回复、赞和转发。

字段	类型	含义
`replies`	`integer`	回复，所有层级合计。
`likes`	`integer`	赞。
`reposts`	`integer`	转发。

示例

{
  "replies": 4,
  "likes": 31,
  "reposts": 2
}

`Media`

帖子或私信中的一张图片。

字段	类型	含义
`url`	`string`	图片或视频的地址，相对于本站。加载时请在请求头中带上密钥。
`kind`	`string`	`image`、`video` 或 `gif`（自 2.10 起）。视频和 GIF 均为 MP4 文件。 `image` — 一张图片（WebP 或 JPEG）。 `video` — 带声音的 MP4 视频。 `gif` — GIF，以无声循环的 MP4 形式提供。
`poster`	`string`或 null	视频和 GIF 的预览图地址，否则为 `null`（自 2.10 起）。

示例

{
  "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
  "kind": "image",
  "poster": null
}

`Poll`

帖子的投票。

字段	类型	含义
`options`	`PollOption[]`	选项，按顺序。投票时 `option` 从 0 开始计数。
`total`	`integer`	所有票数合计，始终存在。
`multiple`	`boolean`	是否可以选择多个选项。
`endsAt`	`integer`或 null	投票结束时间（无截止时为 `null`）。
`running`	`boolean`	是否仍可投票。
`resultsVisible`	`boolean`	是否显示各选项的票数（见 `votes`）。
`myVotes`	`integer[]`	你选择的选项，从 0 开始计数。

示例

{
  "options": [
    {
      "text": "Lavender",
      "votes": 12
    },
    {
      "text": "Sunflowers",
      "votes": 7
    },
    {
      "text": "Clover",
      "votes": 3
    }
  ],
  "total": 22,
  "multiple": false,
  "endsAt": 1758710400000,
  "running": true,
  "resultsVisible": true,
  "myVotes": [
    0
  ]
}

`PollOption`

投票的一个选项。

字段	类型	含义
`text`	`string`	选项内容。
`votes`	`integer`或 null	其票数（结果隐藏期间为 `null`）。

示例

{
  "text": "Lavender",
  "votes": 12
}

`ProfileBrief`

出现在其他对象中的个人主页：作为作者或在搜索中。

字段	类型	含义
`id`	`string`	账号的 id：`/relations` 和 `/conversations/{with}` 需要的值。
`handle`	`string`	短名称，不含 `@`。
`name`	`string`	显示名称。可能包含表情，包括 `:name:`。
`verified`	`boolean`	账号是否已认证。
`accountKind`	`string`	账号类型。 `person` — 个人。 `business` — 商家。 `association` — 俱乐部或社团。 `automated` — 自动化账号，例如机器人。

示例

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person"
}

`Profile`

单独的个人主页，包含简介和关注者。

ProfileBrief 的所有字段，另外还有：

字段	类型	含义
`about`	`string`或 null	简介（没有则为 `null`）。
`website`	`string`或 null	个人主页的网站（没有则为 `null`）。自 2.3 起。
`websiteVerified`	`boolean`	网站是否通过 `rel=me` 回链到此个人主页，每周检查一次。自 2.3 起。
`followers`	`integer`	有多少账号关注它。
`createdAt`	`integer`或 null	账号创建时间（成员隐藏加入日期时为 `null`；自 2.9 起）。

示例

{
  "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "handle": "mara",
  "name": "Mara 🌻",
  "verified": true,
  "accountKind": "person",
  "about": "Beekeeper, allotment, too many seeds. :tellmelo:",
  "website": "https://mara-imkerei.example/",
  "websiteVerified": true,
  "followers": 148,
  "createdAt": 1750848000000
}

`CommunityBrief`

帖子所在的群组。

字段	类型	含义
`id`	`string`	群组的 id。
`name`	`string`或 null	群组名称。

示例

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening"
}

`Community`

本站的一个群组。

字段	类型	含义
`id`	`string`	群组的 id。
`name`	`string`	群组名称。
`description`	`string`或 null	简介（没有则为 `null`）。
`tags`	`string[]`	涉及的话题。
`members`	`integer`	成员数量。
`joinPolicy`	`string`	加入方式。 `open` — 任何人都可以加入。 `application` — 加入需要提交申请并获群组接受。 `invite` — 仅限邀请。
`visibility`	`string`	通过密钥访问时始终为 `open`。 `open` — 所有人可见。

示例

{
  "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
  "name": "Urban Gardening",
  "description": "Balconies, allotments, rooftops: whatever grows.",
  "tags": [
    "garden",
    "bees"
  ],
  "members": 312,
  "joinPolicy": "open",
  "visibility": "open"
}

`Tag`

一个标签以及有多少帖子使用它。

字段	类型	含义
`tag`	`string`	标签，不含 `#`。
`posts`	`integer`	最近有多少帖子使用它。

示例

{
  "tag": "garden",
  "posts": 58
}

`SearchResult`

三个列表，可能为空。

字段	类型	含义
`posts`	`Post[]`	匹配的帖子，最新的在前。
`profiles`	`ProfileBrief[]`	匹配的个人主页，按短名称。
`tags`	`Tag[]`	匹配的标签，最常用的在前。

示例

{
  "posts": [
    {
      "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
      "text": "The bees are back in the garden 🐝 #garden",
      "kind": "poll",
      "author": {
        "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
        "handle": "mara",
        "name": "Mara 🌻",
        "verified": true,
        "accountKind": "person"
      },
      "community": {
        "id": "c81d4e2a-0f3b-4a6c-9e57-1d2b3c4a5f60",
        "name": "Urban Gardening"
      },
      "media": [
        {
          "url": "/api/media?id=b2d7e9f1-3c4a-4e8b-a1f0-6d5c4b3a2918",
          "kind": "image",
          "poster": null
        }
      ],
      "poll": {
        "options": [
          {
            "text": "Lavender",
            "votes": 12
          },
          {
            "text": "Sunflowers",
            "votes": 7
          },
          {
            "text": "Clover",
            "votes": 3
          }
        ],
        "total": 22,
        "multiple": false,
        "endsAt": 1758710400000,
        "running": true,
        "resultsVisible": true,
        "myVotes": [
          0
        ]
      },
      "quotes": null,
      "continues": null,
      "counts": {
        "replies": 4,
        "likes": 31,
        "reposts": 2
      },
      "pinned": false,
      "createdAt": 1758624000000
    }
  ],
  "profiles": [
    {
      "id": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
      "handle": "mara",
      "name": "Mara 🌻",
      "verified": true,
      "accountKind": "person"
    }
  ],
  "tags": [
    {
      "tag": "garden",
      "posts": 58
    }
  ]
}

`Emoji`

本站的一个表情。

字段	类型	含义
`name`	`string`	名称，即冒号之间的部分。
`url`	`string`	图片地址，相对于本站。

示例

{
  "name": "tellmelo",
  "url": "/api/media?id=e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b"
}

`Notification`

一条通知。一行可以汇总多个同类事件。

字段	类型	含义
`id`	`string`	通知的 id。
`kind`	`string`	发生了什么。 `reply` — 有人回复了你。 `like` — 有人赞了你的帖子。 `reply_like` — 有人赞了你的回复。 `repost` — 有人转发了你的帖子。 `follow` — 有人关注了你。 `mention` — 有人提到了你。 `group_mention` — 有人提到了你管理的群组；`text` 是群组名称。 `message` — 有人给你发了私信。 `scheduled` — 你的一条定时帖子已发布。 `reminder` — 一条关于收藏帖子的提醒到期了。 `report` — 你提交的举报的处理结果。 `moderation` — 关于你账号的决定：警告、限制、申诉。 `team` — 团队有新工作（仅限所有者、管理员和版主）。 `reward` — 邀请奖励即将到期或已到期。 `gift` — 来自团队的礼物：一个套餐，或给你或你管理的群组的火花。 `present` — 来自成员的礼物：火花或套餐时长；该成员即 `actor`。 `spark` — 火花即将用完，或你管理的群组达到了某个等级，或只能暂时保持该等级。 `loyalty` — 关于忠诚节奏：活跃的一周被计入或还差一天，奖励是新的或即将消失。 `impact` — 你十二小时内的帖子在一天后的表现，合并为一条通知。 `discovery` — “被发现”计划的邀请，或其中某个位置开始或结束。 `group_post` — 某个群组有新帖子，且该群组的铃铛设置为提醒。 `group_moderation` — 群组管理层移除了你的一条帖子，或将你移出了群组。
`text`	`string`或 null	仅用于举报和审核：相关文本，否则为 `null`。
`actor`	`Actor`	谁做的。
`postId`	`string`或 null	涉及的帖子（不涉及任何帖子时为 `null`）。
`read`	`boolean`	是否已标为已读。
`more`	`integer`	除所列事件外，这一行还代表多少其他事件。
`createdAt`	`integer`	首次发生的时间。
`updatedAt`	`integer`	最后一次汇入新事件的时间。列表按此排序。

示例

{
  "id": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
  "kind": "like",
  "text": null,
  "actor": {
    "handle": "jon",
    "name": "Jon"
  },
  "postId": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "read": false,
  "more": 2,
  "createdAt": 1758624300000,
  "updatedAt": 1758624900000
}

`Actor`

谁触发了通知。

字段	类型	含义
`handle`	`string`	短名称。
`name`	`string`	显示名称。

示例

{
  "handle": "jon",
  "name": "Jon"
}

`Conversation`

你收件箱中的一行。

字段	类型	含义
`with`	`string`	对方账号的 id：`/conversations/{with}/messages` 需要的值。
`handle`	`string`	对方的短名称。
`name`	`string`	对方的显示名称。
`excerpt`	`string`或 null	最后一条私信的开头（没有文字时为 `null`）。
`truncated`	`boolean`	摘录是否被截断。
`fromMe`	`boolean`	最后一条私信是否是你发的。
`lastMessageId`	`string`	最后一条私信的 id。
`unread`	`integer`	对方有多少条私信你还没读。
`updatedAt`	`integer`	最后一条私信的写作时间。

示例

{
  "with": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
  "handle": "jon",
  "name": "Jon",
  "excerpt": "See you on Saturday at the market!",
  "truncated": false,
  "fromMe": true,
  "lastMessageId": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
  "unread": 0,
  "updatedAt": 1758624060000
}

`Message`

对话中的一条私信。

字段	类型	含义
`id`	`string`	私信的 id。
`text`	`string`或 null	文字（只有图片的私信为 `null`）。
`from`	`string`	写信账号的 id。
`to`	`string`	收信账号的 id。
`read`	`boolean`	收件人是否已读。
`media`	`Media[]`	其图片；没有则为空。
`replyTo`	`string`或 null	本条私信所回复的私信的 `id`（未回复任何私信时为 `null`）。自 2.2 起。
`createdAt`	`integer`	发送时间。

示例

{
  "id": "7c6b5a49-3827-4165-9f0e-d1c2b3a49586",
  "text": "See you on Saturday at the market!",
  "from": "a3e1f7c2-54b9-4d0e-8f16-7b2c9d4e1a05",
  "to": "d4c3b2a1-6e5f-4a7b-9c8d-1e2f3a4b5c6d",
  "read": true,
  "media": [],
  "replyTo": null,
  "createdAt": 1758624060000
}

`Created`

创建了内容的写入操作的响应。

字段	类型	含义
`id`	`string`	所创建内容的 id。
`scheduledFor`	`integer`或 null	如果设置了定时发布，则为出现时间（否则为 `null`）。
`deleteAt`	`integer`或 null	如果设置了自动删除，则为删除时间（否则为 `null`）。

示例

{
  "id": "5f0c2a9e-8d41-4b7a-9c3e-2e61d0f4a7b1",
  "scheduledFor": null,
  "deleteAt": null
}

`Ok`

无需返回内容的写入操作的响应。

字段	类型	含义
`ok`	`boolean`	始终为 `true`。

示例

{
  "ok": true
}

机器可读的描述

本页背后的表格以 OpenAPI 形式提供，地址为 /api/v2/openapi.json。

https://tellmelo.com/api/v2/openapi.json

我们的期望

规则和其他地方一样：不骚扰、不发垃圾信息、不发你无权发布的内容。你的密钥发布的内容由你负责。

API

概览

快速开始

试一试

你的密钥

密钥能做什么

任何密钥都做不到的事

请求与响应

分页

只取新内容

限额

请求头

你发送的

返回的

出错时

版本

端点

入口

GET/api/v2

请求示例

响应

帖子

GET/api/v2/posts

参数

请求示例

响应

GET/api/v2/posts/{id}

参数

请求示例

响应

POST/api/v2/posts

参数

请求示例

响应

DELETE/api/v2/posts/{id}

参数

请求示例

响应

回复

GET/api/v2/posts/{id}/replies

参数

请求示例

响应

POST/api/v2/posts/{id}/replies

参数

请求示例

响应

投票

POST/api/v2/posts/{id}/vote

参数

请求示例

响应

个人主页

GET/api/v2/profiles/{handle}

参数

请求示例

响应

GET/api/v2/profiles/{handle}/posts

参数

请求示例

响应

群组

GET/api/v2/communities

参数

请求示例

响应

GET/api/v2/communities/{id}

参数

请求示例

响应

GET/api/v2/communities/{id}/posts

参数

请求示例

响应

发现

GET/api/v2/tags

参数

请求示例

响应

GET/api/v2/search

GET`/api/v2`

GET`/api/v2/posts`

GET`/api/v2/posts/{id}`

POST`/api/v2/posts`

DELETE`/api/v2/posts/{id}`

GET`/api/v2/posts/{id}/replies`

POST`/api/v2/posts/{id}/replies`

POST`/api/v2/posts/{id}/vote`

GET`/api/v2/profiles/{handle}`

GET`/api/v2/profiles/{handle}/posts`

GET`/api/v2/communities`

GET`/api/v2/communities/{id}`

GET`/api/v2/communities/{id}/posts`

GET`/api/v2/tags`

GET`/api/v2/search`

GET`/api/v2/emojis`

GET`/api/v2/me`

GET`/api/v2/feed`

GET`/api/v2/notifications`

POST`/api/v2/notifications/read`

GET`/api/v2/conversations`

GET`/api/v2/conversations/{with}/messages`

POST`/api/v2/conversations/{with}/messages`

POST`/api/v2/conversations/{with}/read`

POST`/api/v2/relations`

`Service`

`RateLimit`

`Post`

`Reply`

`Counts`

`Media`

`Poll`

`PollOption`

`ProfileBrief`

`Profile`

`CommunityBrief`

`Community`

`Tag`

`SearchResult`

`Emoji`

`Notification`

`Actor`

`Conversation`

`Message`

`Created`

`Ok`