为自主性而设计,因目标而受限
为什么一个 API 密钥就是整个集成
让代理接触社交媒体的难点并不在于 HTTP 本身,而在于确保一个出错的模型不会发布到错误的品牌、不会因重试而重复发布,也不会发出一条无人审阅过的内容。这些保障机制内置于 API 接口本身,而不是依赖于你的提示词。
MCP 客户端
在客户端里登录。无需粘贴任何东西。
Claude Code、Claude、Cursor、ChatGPT、Grok、Grok Bot、OpenClaw、Hermes 以及任何支持 Model Context Protocol 的客户端,都可以在不配置任何凭证的情况下连接 Markaestro 托管的 MCP 服务器。第一次调用工具时会打开浏览器:登录,选择代理可以操作的工作区和品牌,检查权限,然后点击允许。客户端会收到绑定到该品牌的密钥,并自行刷新。
这是带 PKCE 和动态客户端注册的标准 OAuth 2.1,与其他托管 MCP 服务器采用相同机制,因此无需任何 Markaestro 专用插件。服务器位于 https://markaestro.com/api/public/v1/mcp,在公共 API 之上提供三十一个工具:品牌与目标发现、媒体上传、草稿与排期帖子、带任务轮询的发布、批量操作、Webhook,以及各渠道规则。
连接你的代理
选择你的代理。三步之后,它就能发帖。
下面的每个客户端都连接到同一个托管 MCP 服务器。大多数通过浏览器登录:第一次调用工具时会打开一个授权页面,你在其中选择代理可以操作的工作区和品牌,客户端随后获得一个绑定到该品牌的密钥。无法打开浏览器的客户端则改用工作区 API 密钥。同一个服务器,同样的权限,设置中的同一份列表。
Claude Code
插件会同时安装技能和托管服务器。无需配置,无需粘贴。
开始之前
- 你是已验证邮箱的工作区所有者或管理员,且该工作区有有效套餐和至少一个品牌。
- 已安装 Claude Code 并登录你的 Anthropic 账户。
登录
验证
- 让代理调用 list_products。它应返回你授权的那一个品牌及其已连接的渠道。
- 该连接会显示在“设置,API”中,带有“已连接代理”标记、最近使用时间和请求量。你可以随时在那里撤销。
添加服务器
- 在任意终端运行两条插件命令,或用第三条命令仅添加服务器。
# The plugin bundles the skill and the hosted server.
claude plugin marketplace add D3vBaba/Markaestro
claude plugin install markaestro@markaestro
# Or add just the server. No key, no header: the first call opens the browser.
claude mcp add --transport http markaestro https://markaestro.com/api/public/v1/mcpClaude
claude.ai 和 Claude Desktop 将服务器 URL 作为自定义连接器接入,并通过同一个授权页面登录。
开始之前
- 你是已验证邮箱的工作区所有者或管理员,且该工作区有有效套餐和至少一个品牌。
- 自定义连接器在 Claude 付费套餐中可用。Team 和 Enterprise 可能需要所有者先启用。
登录
- 点击 Markaestro 旁边的“连接”。授权页面会在新标签页中打开。
- 选择工作区和品牌,检查权限,点击“允许”。标签页关闭后,连接器显示为已连接。
- 在对话中需要代理使用时,从工具菜单启用 Markaestro。
验证
- 让代理调用 list_products。它应返回你授权的那一个品牌及其已连接的渠道。
- 该连接会显示在“设置,API”中,带有“已连接代理”标记、最近使用时间和请求量。你可以随时在那里撤销。
添加服务器
- 打开“设置,连接器”,然后点击“添加自定义连接器”。
- 粘贴下面的服务器 URL,OAuth 客户端字段留空,点击“添加”。
https://markaestro.com/api/public/v1/mcpCursor
一键即可把服务器添加到 Cursor。第一次调用工具时会打开浏览器登录;Cursor 将令牌保存在系统钥匙串中。
开始之前
- 你是已验证邮箱的工作区所有者或管理员,且该工作区有有效套餐和至少一个品牌。
- 已启用 MCP 的 Cursor。远程 MCP 服务器在所有 Cursor 套餐中都可用。
登录
验证
- 让代理调用 list_products。它应返回你授权的那一个品牌及其已连接的渠道。
- 该连接会显示在“设置,API”中,带有“已连接代理”标记、最近使用时间和请求量。你可以随时在那里撤销。
添加服务器
- 点击“添加到 Cursor”,并在 Cursor 中确认安装提示。
- 或者将 JSON 粘贴到项目的 .cursor/mcp.json(通过 git 与团队共享)或 ~/.cursor/mcp.json(仅自己)。
// .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
{
"mcpServers": {
"markaestro": {
"url": "https://markaestro.com/api/public/v1/mcp"
}
}
}在共享构建机或 CI 上,可在 headers 中放入工作区 API 密钥来代替登录。
// Without a browser: pass a workspace API key instead.
{
"mcpServers": {
"markaestro": {
"url": "https://markaestro.com/api/public/v1/mcp",
"headers": { "Authorization": "Bearer mk_live_..." }
}
}
}ChatGPT
ChatGPT 在开发者模式下以自定义应用的形式连接 Markaestro,并通过授权页面登录。
开始之前
- 你是已验证邮箱的工作区所有者或管理员,且该工作区有有效套餐和至少一个品牌。
- 开发者模式需要 ChatGPT Pro、Business、Enterprise 或 Edu。Pro 仅提供只读工具;Business、Enterprise 和 Edu 提供全部工具。
- 在 Business、Enterprise 和 Edu 中,管理员可能需要先为工作区允许自定义应用。
登录
- ChatGPT 扫描工具时会打开授权页面。选择工作区和品牌,点击“允许”,然后点击“创建”。
- 在对话中点击加号,“更多”,再点击 Markaestro 即可使用这些工具。
- ChatGPT 每次连接都会向 Markaestro 注册一次。重新连接会创建一个可单独撤销的新连接。
验证
- 让代理调用 list_products。它应返回你授权的那一个品牌及其已连接的渠道。
- 该连接会显示在“设置,API”中,带有“已连接代理”标记、最近使用时间和请求量。你可以随时在那里撤销。
添加服务器
- 打开“设置,应用与连接器,高级设置”,开启开发者模式。
- 回到“应用与连接器”,点击“创建”。命名为 Markaestro,粘贴服务器 URL,认证方式选择 OAuth,然后点击“扫描工具”。
https://markaestro.com/api/public/v1/mcpGrok
Grok 有三种方式连接 Markaestro:grok.com 上的自定义连接器、Grok Build 终端,以及 xAI API 中的远程 MCP 工具。
开始之前
- 你是已验证邮箱的工作区所有者或管理员,且该工作区有有效套餐和至少一个品牌。
- grok.com 连接器在个人套餐中可用。Grok Business 和 Enterprise 需要团队管理员先配置连接器。
- xAI API 路径在服务端运行,因此始终使用工作区 API 密钥。
登录
验证
- 让代理调用 list_products。它应返回你授权的那一个品牌及其已连接的渠道。
- 该连接会显示在“设置,API”中,带有“已连接代理”标记、最近使用时间和请求量。你可以随时在那里撤销。
添加服务器
- grok.com:打开 grok.com/connectors,点击 New Connector,选择 Custom,粘贴服务器 URL。如果对话框要求客户端 ID,使用下面的值。
- Grok Build:在终端运行两条命令。Grok Build 也会读取 Claude Code 的 .mcp.json 或 Cursor 的 mcp.json 中的 Markaestro 条目。
- xAI API:将工具块添加到 Responses API 请求的 tools 数组中。
grok.com 自定义连接器
Server URL: https://markaestro.com/api/public/v1/mcp
grok.com's Custom Connector asks only for a name and this URL. It registers
itself and opens the browser sign-in, no client id or secret to enter.
(If a future dialog does ask, use client id markaestro-grok-web with a blank secret.)Grok Build 终端
# Grok Build (terminal). The first tool call opens the browser.
grok mcp add --transport http markaestro https://markaestro.com/api/public/v1/mcp
grok mcp doctor markaestro
# Headless: pass a workspace API key instead.
grok mcp add --transport http markaestro https://markaestro.com/api/public/v1/mcp \
--header "Authorization: Bearer ${MARKAESTRO_API_KEY}"xAI Responses API 工具块
// xAI Responses API: one entry in the request's "tools" array.
// Server-side, so it always uses a workspace API key.
{
"type": "mcp",
"server_url": "https://markaestro.com/api/public/v1/mcp",
"server_label": "markaestro",
"authorization": "Bearer mk_live_...",
"allowed_tools": ["list_products", "list_destinations", "upload_media",
"create_post", "publish_post", "get_job_run"]
}Grok Bot
Grok Bot 运行在云端计算机上,通过静态密钥接入自定义 MCP 服务器。测试版尚不支持自定义服务器的浏览器登录。
开始之前
- 你是已验证邮箱的工作区所有者或管理员,且该工作区有有效套餐和至少一个品牌。
- Grok Bot 目前在 SuperGrok 套餐和 Cursor Pro 中处于早期测试。Enterprise 需加入等候名单。
- 你已有一个带代理权限范围的工作区 API 密钥。可用下面的按钮创建。
使用 API 密钥
验证
- 让代理调用 list_products。它应返回你授权的那一个品牌及其已连接的渠道。
- 该连接会显示在“设置,API”中,带有“已连接代理”标记、最近使用时间和请求量。你可以随时在那里撤销。
添加服务器
- 打开 Bot 的连接器设置,添加一个自定义 MCP 服务器。
- 粘贴服务器 URL,然后按下面的值把密钥作为 header 添加。
连接器对话框所需的 header 值
Server URL: https://markaestro.com/api/public/v1/mcp
Header name: Authorization (or x-api-key if that is the only field)
Header value: Bearer mk_live_... (with x-api-key: just mk_live_...)OpenClaw
OpenClaw 通过其 CLI 添加远程 MCP 服务器,并在回环端口上完成登录,因此可在运行网关的机器上使用。
开始之前
- 你是已验证邮箱的工作区所有者或管理员,且该工作区有有效套餐和至少一个品牌。
- 已安装 OpenClaw 且网关正在运行。
- 没有浏览器的服务器可通过 --code 备用方式完成登录。
登录
验证
- 让代理调用 list_products。它应返回你授权的那一个品牌及其已连接的渠道。
- 该连接会显示在“设置,API”中,带有“已连接代理”标记、最近使用时间和请求量。你可以随时在那里撤销。
添加服务器
- 运行三条命令,或将服务器块添加到 ~/.openclaw/openclaw.json。
- Markaestro 技能上架 ClawHub 后,openclaw skills install markaestro 还会添加代理指令。
openclaw mcp add markaestro \
--url https://markaestro.com/api/public/v1/mcp \
--transport streamable-http \
--auth oauth
openclaw mcp login markaestro # prints the sign-in URL; add --code <code> when headless
openclaw mcp reload等价的配置条目
// ~/.openclaw/openclaw.json
{
"mcp": {
"servers": {
"markaestro": {
"url": "https://markaestro.com/api/public/v1/mcp",
"transport": "streamable-http",
"auth": "oauth"
}
}
}
}无浏览器时
# Without a browser: a workspace API key from the environment.
openclaw mcp add markaestro \
--url https://markaestro.com/api/public/v1/mcp \
--transport streamable-http \
--header "Authorization: Bearer ${MARKAESTRO_API_KEY}"Hermes
Hermes Agent 从 config.yaml 注册 HTTP MCP 服务器并自行完成登录,令牌保存在 ~/.hermes/mcp-tokens 下。
开始之前
- 你是已验证邮箱的工作区所有者或管理员,且该工作区有有效套餐和至少一个品牌。
- 已安装 Hermes Agent。密钥放在 ~/.hermes/.env 中,并在配置里以 ${VAR} 引用。
登录
验证
- 让代理调用 list_products。它应返回你授权的那一个品牌及其已连接的渠道。
- 该连接会显示在“设置,API”中,带有“已连接代理”标记、最近使用时间和请求量。你可以随时在那里撤销。
添加服务器
- 将 mcp_servers 块添加到 ~/.hermes/config.yaml。
- 在运行中的会话里发送 /reload-mcp。工具会以 mcp_markaestro_<tool> 的形式出现。
# ~/.hermes/config.yaml
mcp_servers:
markaestro:
url: "https://markaestro.com/api/public/v1/mcp"
auth: oauth无浏览器时
# Without a browser: a workspace API key, kept in ~/.hermes/.env
mcp_servers:
markaestro:
url: "https://markaestro.com/api/public/v1/mcp"
headers:
Authorization: "Bearer ${MARKAESTRO_API_KEY}"其他 MCP 客户端
任何支持 Streamable HTTP 以及带动态客户端注册的 OAuth 2.1 的客户端,只需服务器 URL 即可连接。
开始之前
- 你是已验证邮箱的工作区所有者或管理员,且该工作区有有效套餐和至少一个品牌。
- 客户端支持通过 Streamable HTTP 连接远程 MCP 服务器,并能为 OAuth 打开浏览器。如果不能,请使用“API 密钥”标签。
登录
验证
- 让代理调用 list_products。它应返回你授权的那一个品牌及其已连接的渠道。
- 该连接会显示在“设置,API”中,带有“已连接代理”标记、最近使用时间和请求量。你可以随时在那里撤销。
添加服务器
- 在客户端的 MCP 配置中添加服务器 URL。下面的 JSON 是常见的 mcpServers 格式。
- 不要配置客户端 ID 或密钥。客户端会在首次使用时自行注册。
{
"mcpServers": {
"markaestro": {
"type": "http",
"url": "https://markaestro.com/api/public/v1/mcp"
}
}
}API 密钥
适用于 CI 任务、cron 工作进程以及无法打开浏览器的客户端:在 Authorization header 中放入工作区 API 密钥,即可以相同权限访问同一服务器。
开始之前
- 你是已验证邮箱的工作区所有者或管理员,且该工作区有有效套餐和至少一个品牌。
- 你可以创建密钥:已验证邮箱的工作区所有者或管理员。
验证
- 让代理调用 list_products。它应返回你授权的那一个品牌及其已连接的渠道。
- 该连接会显示在“设置,API”中,带有“已连接代理”标记、最近使用时间和请求量。你可以随时在那里撤销。
添加服务器
- 创建一个绑定到单个品牌、仅包含代理所需权限范围并设有过期时间的密钥。
- 对托管服务器以 bearer header 传入,或对本地 stdio 服务器以 MARKAESTRO_API_KEY 传入,后者还能从磁盘上传文件。
# CI, cron, or any client without a browser: pass a key instead.
claude mcp add --transport http markaestro https://markaestro.com/api/public/v1/mcp \
--header "Authorization: Bearer mk_live_..."
# Local stdio server (can also upload files from disk)
claude mcp add markaestro -e MARKAESTRO_API_KEY=mk_live_... -- npx -y @markaestro/mcp{
"mcpServers": {
"markaestro": {
"type": "http",
"url": "https://markaestro.com/api/public/v1/mcp",
"headers": { "Authorization": "Bearer mk_live_..." }
}
}
}客户端连接时会发生什么
五个步骤全部由客户端和浏览器处理。你只会看到同意页面。
POST /api/public/v1/mcp → 401 + WWW-Authenticate客户端在没有凭证的情况下调用 MCP 端点。Markaestro 返回 401,并附带指向受保护资源元数据文档的 WWW-Authenticate 头。正是这个头告诉客户端可以登录。
GET /.well-known/oauth-protected-resource · /.well-known/oauth-authorization-server客户端读取两份公开文档:哪个授权服务器保护该端点,以及该服务器的注册、授权和令牌端点在哪里。两份文档都由 markaestro.com 提供,可以缓存。
POST /api/public/v1/oauth/register客户端用名称和回调地址注册自己。回环地址、https 回调和原生应用 scheme 会被接受;指向真实主机的明文 http 会被拒绝。不需要预先共享的客户端 ID。
GET /oauth/authorize (browser)浏览器打开同意页面。邮箱已验证的工作区所有者或管理员选择工作区和品牌,调整权限,然后点击允许。Markaestro 带着一次性授权码把浏览器送回客户端。
POST /api/public/v1/oauth/token客户端用授权码加上 PKCE verifier 换取访问令牌和刷新令牌。访问令牌就是一个普通的工作区 API 密钥,绑定到所选品牌。它在 30 天后过期;刷新会轮换其密钥并再延长 30 天。
令牌就是真正的 API 密钥
作用域、品牌绑定、速率限制、订阅检查、幂等性和撤销,与手动创建的密钥走完全相同的代码路径。不存在需要另外理解的第二套权限模型。
在设置中可见、可撤销
已连接的代理会显示在设置的 API 中,带有“已连接的代理”徽章、最近使用时间和请求量。在那里撤销后,客户端的下一次调用即失败;断开连接时客户端也可以自行撤销令牌。
一个连接,一个品牌
每个连接都精确绑定到同意时选择的一个品牌。要让代理处理第二个品牌,请再次连接并选择该品牌。客户端永远无法触及未被授予的品牌。
授权码和刷新令牌都是一次性的
授权码有效期十分钟并以原子方式消费,因此重放的授权码会失败。刷新令牌每次使用都会轮换,并以哈希形式存储。闲置的客户端注册在 180 天后过期。
端点
面向构建 MCP 客户端或审计此流程的人。所有内容都可以从两份 well-known 文档中发现,这里没有任何需要手动配置的东西。
# Discovery (public, cacheable)
GET /.well-known/oauth-protected-resource RFC 9728
GET /.well-known/oauth-authorization-server RFC 8414
# Authorization server
POST /api/public/v1/oauth/register RFC 7591, public clients (PKCE) or client_secret
GET /oauth/authorize?response_type=code&client_id=…&redirect_uri=…
&code_challenge=…&code_challenge_method=S256&state=…
POST /api/public/v1/oauth/token grant_type=authorization_code | refresh_token
POST /api/public/v1/oauth/revoke RFC 7009
# Token response
{ "access_token": "mk_live_<ws>.<client>.<secret>", "token_type": "Bearer",
"expires_in": 2592000, "refresh_token": "…", "scope": "products.read posts.write …" }代理循环
从头到尾,只需五次调用
Markaestro 的每一次自动化本质上都是这个循环的变体。第一到第三步是 Connect API,大多数代理应该对接的扁平接口。第四步和第五步则会调用完整的 /api/public/v1 API,用于显式发布和任务跟踪。
GET /api/connect/v1/social-accounts返回该密钥所属品牌下所有已连接、可发布的账号,每个账号都包含平台、用户名和一个不透明 ID。请在每次运行开始时调用,连接关系会发生变化。
POST /api/connect/v1/media/create-upload-url → PUT生成一个短时有效、一次性使用的已签名 URL,然后向其 PUT 原始字节数据。你会获得一个素材 ID。图片最大支持 10MB;完整版 API 还支持最大 250MB 的视频。
POST /api/connect/v1/posts原样传入文案、素材 ID 和账号 ID。可将其保留为草稿以供审阅,或发送 is_draft false 并附带 scheduled_at,将其加入日历。
POST /api/public/v1/posts/:id/publish将一次异步任务加入队列。LinkedIn、Threads 和 Pinterest 会通过官方 API 发布出去。Facebook、Instagram 和 TikTok 则会进入工作区的「待发布」队列,等待真人完成原生发布。
GET /api/public/v1/job-runs/:id · webhooks轮询任务 ID,或注册一个 Webhook 端点,让 Markaestro 主动推送 post.published、post.action_required 和 post.failed。切勿假定发布会同步完成。
快速入门
四条命令即可完成一次可运行的集成
首先生成密钥:打开 设置 → API,选择该密钥可以访问的品牌,勾选所需的权限范围,并可选择设置有效期。密钥只会显示一次,请直接将其存入代理的密钥存储库中。生成密钥需要拥有已验证邮箱的管理员或所有者身份。
# The API is served from the marketing apex and the app subdomain alike.
export MARKAESTRO_URL="https://markaestro.com"
export MARKAESTRO_API_KEY="mk_live_<workspaceId>.<clientId>.<secret>"
# 1. What can this key post to?
curl -s "$MARKAESTRO_URL/api/connect/v1/social-accounts" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY"{
"data": [
{
"id": "prod_123#instagram:instagram:ig_123",
"product_id": "prod_123",
"product": "Northwind Coffee",
"platform": "instagram",
"username": "northwindcoffee"
}
]
}# 2. Mint a signed upload url, then PUT the bytes.
RESP=$(curl -s -X POST "$MARKAESTRO_URL/api/connect/v1/media/create-upload-url" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "mime_type": "image/png", "size_bytes": 184320, "name": "cold-brew.png" }')
# → { "media_id": "ast_777", "upload_url": "https://.../media/upload?token=..." }
curl -X PUT "<upload_url>" \
-H "Content-Type: image/png" \
--data-binary @cold-brew.pngis_draft: false 并附带 scheduled_at 时间戳,即可将内容排入日历。# 3. Put it on the calendar. Pass the account id back verbatim.
curl -X POST "$MARKAESTRO_URL/api/connect/v1/posts" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"caption": "Cold brew season starts Friday.",
"media": ["ast_777"],
"social_accounts": ["prod_123#instagram:instagram:ig_123"],
"is_draft": false,
"scheduled_at": "2026-08-14T15:00:00.000Z"
}'
# 4. Check where everything stands.
curl -s "$MARKAESTRO_URL/api/connect/v1/posts?limit=20" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY"开箱即用
工具定义与代理简介
有两样东西可以直接复制使用。第一是一套覆盖整个发布循环的工具 Schema,以 JSON Schema 编写,因此可直接用作 Claude 工具定义、OpenAI 函数,或你自行托管的 MCP 服务器的输入格式。第二是一份运行简介,用于防止模型做出出人意料的操作。
[
{
"name": "markaestro_list_accounts",
"description": "List the social accounts this Markaestro key can publish to. Call this first in every run. Never hardcode account ids. Returns id, platform, and username.",
"input_schema": { "type": "object", "properties": {}, "required": [] }
},
{
"name": "markaestro_upload_media",
"description": "Upload one image or video to Markaestro and return a media asset id. Images: png, jpeg, webp, gif up to 10 MB. Video: mp4, mov, webm up to 250 MB.",
"input_schema": {
"type": "object",
"properties": {
"file_path": { "type": "string", "description": "Local path to the file to upload." },
"mime_type": { "type": "string", "description": "MIME type of the file." }
},
"required": ["file_path", "mime_type"]
}
},
{
"name": "markaestro_create_post",
"description": "Create a post for one channel. Facebook, Instagram, and TikTok are manual-first: a human posts them natively from the To Post queue. Omit delivery_mode unless the user explicitly asked for unattended publishing.",
"input_schema": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": ["facebook", "instagram", "tiktok", "linkedin", "threads", "pinterest", "x"]
},
"caption": { "type": "string", "description": "Caption text, max 4000 characters." },
"media_asset_ids": {
"type": "array",
"items": { "type": "string" },
"description": "Ids from markaestro_upload_media. Instagram and TikTok require at least one."
},
"destination_id": {
"type": "string",
"description": "From markaestro_list_accounts. Required only when the brand has more than one destination on that channel."
},
"delivery_mode": {
"type": "string",
"enum": ["manual_reminder", "direct_publish", "platform_inbox"],
"description": "Omit for the channel default."
}
},
"required": ["channel", "caption"]
}
},
{
"name": "markaestro_publish_post",
"description": "Queue an async publish run for an existing post. Returns a run id. Poll it, do not assume the post is live.",
"input_schema": {
"type": "object",
"properties": { "post_id": { "type": "string" } },
"required": ["post_id"]
}
},
{
"name": "markaestro_list_posts",
"description": "List posts for this brand, newest first. Filter by status: draft, scheduled, publishing, published, platform_action_required, failed, partial_failed.",
"input_schema": {
"type": "object",
"properties": {
"status": { "type": "string" },
"limit": { "type": "integer", "minimum": 1, "maximum": 100 }
},
"required": []
}
},
{
"name": "markaestro_delete_post",
"description": "Remove a post from Markaestro. Use it to cancel something scheduled. Deleting an already-published post does NOT retract the live copy on the platform.",
"input_schema": {
"type": "object",
"properties": { "post_id": { "type": "string" } },
"required": ["post_id"]
}
}
]You have a Markaestro API key for exactly one brand. Markaestro is the
publishing layer: you supply the caption and the media, it handles the
platform rules, the calendar, and delivery.
Base URL: https://markaestro.com
Auth: Authorization: Bearer $MARKAESTRO_API_KEY
Rules:
- Call GET /api/connect/v1/social-accounts before posting. Pass the returned
account ids back verbatim. Never invent or cache an id across runs.
- Upload media before creating a post; posts reference media ids, not files.
- Facebook, Instagram, and TikTok are manual-first. Creating and publishing
them queues a reminder for a human. That is the intended behavior. Only
send deliveryMode "direct_publish" if the operator explicitly asked for it.
- Send a unique Idempotency-Key on every POST. Reuse the SAME key when
retrying the SAME request; never reuse it for a different one.
- On 429, wait the number of seconds in Retry-After, then retry. On 4xx other
than 429, do not retry. Report the error code and requestId and stop.
- Publishing is async. POST /publish returns a run id; poll
GET /api/public/v1/job-runs/<id> until succeeded or failed.
- To cancel, list with ?status=scheduled and DELETE the post id. Deleting a
published post does not remove it from the platform.
- Never claim a post is live until a run reports succeeded or a post reports
published.你的代理也可以自行获取这份内容:curl https://markaestro.com/llms.txt 会返回整个 API 的纯文本简介,涵盖接口、规则和错误处理,体积足够小,可以放入上下文中。
示例场景
代理实际运行的四种工作流
# Full control: draft → publish → poll. No productId needed:
# the key is already bound to one brand.
POST_ID=$(curl -s -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: post-2026-08-14-linkedin" \
-d '{
"channel": "linkedin",
"caption": "We shipped agent-driven publishing.",
"mediaAssetIds": ["ast_777"]
}' | jq -r .post.id)
RUN_ID=$(curl -s -X POST "$MARKAESTRO_URL/api/public/v1/posts/$POST_ID/publish" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY" \
-H "Idempotency-Key: publish-$POST_ID" | jq -r .run.id)
# queued → running → succeeded | failed
curl -s "$MARKAESTRO_URL/api/public/v1/job-runs/$RUN_ID" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY"# Review the queue, then cancel what the operator rejected.
curl -s "$MARKAESTRO_URL/api/public/v1/posts?status=scheduled&limit=100" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY"
curl -X DELETE "$MARKAESTRO_URL/api/public/v1/posts/pst_123" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY"
# → { "deleted": true, "id": "pst_123" }# One call, up to 25 posts. Per-item results: one bad item
# does not fail the batch.
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: week-33-drop" \
-d '{
"posts": [
{ "channel": "instagram", "caption": "Monday", "mediaAssetIds": ["ast_1"] },
{ "channel": "facebook", "caption": "Tuesday", "mediaAssetIds": ["ast_2"] },
{ "channel": "linkedin", "caption": "Thursday" }
]
}'
# → { "results": [...], "created": 3, "total": 3 }# Let Markaestro call you instead of polling.
curl -X POST "$MARKAESTRO_URL/api/public/v1/webhook-endpoints" \
-H "Authorization: Bearer $MARKAESTRO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-agent.example.com/hooks/markaestro",
"events": ["post.published", "post.action_required", "post.failed"]
}'
# Each delivery carries:
# X-Markaestro-Event post.action_required
# X-Markaestro-Timestamp 2026-08-14T15:00:04.000Z
# X-Markaestro-Signature HMAC of the body with your webhook secret
# The secret is shown once at creation and stored hashed. Verify before acting.安全护栏
代理能做什么,不能做什么
自主性只有在影响范围可控时才有价值。Markaestro 的默认设置假定调用方是可能出错的软件。
Facebook、Instagram 和 TikTok 以人工优先
你的代理为这些渠道创建的内容,默认使用 manual_reminder:Markaestro 不会调用这些平台的 API。发布操作会将内容移入工作区的「待发布」队列,由真人下载素材、原生发布并确认,因此内容看起来与手动制作的完全一致,且在公开存在之前,每一条都会经过人工过目。代理可以通过 deliveryMode: "direct_publish" 为单篇内容选择官方 API 发布,在 TikTok 上这意味着转交至创作者收件箱,绝不会成为无人监督的公开发布。LinkedIn、Threads 和 Pinterest 会在你的代理明确请求后以程序化方式发布。
缩小密钥权限范围
只选择代理所需的权限范围:products.read、media.write、posts.read、posts.write、posts.publish、job_runs.read、webhooks.manage。一个只读取日历的研究型代理,只需拥有 posts.read 即可。
设置有效期
密钥可在创建时设置有效期。过期的密钥表现与被撤销的密钥完全相同,因此从代理环境中泄露的密钥会自行失效。
轮换与撤销
你可以在「设置 → API」中原地轮换密钥,或直接将其彻底撤销。每个密钥都会显示最近使用时间和请求量,因此无论代理沉寂下来还是行为失控,都能被及时发现。
速率限制会被强制执行
每个接口每分钟 60 次请求,每个密钥每分钟 240 次请求。每个响应都携带 X-RateLimit-Limit、-Remaining 和 -Reset;429 响应会携带 Retry-After。请遵守这些限制,而不是强行发起请求。
Markaestro 不会替你撰写内容
系统中不存在生成环节。文案来自你的代理,素材来自你的素材库或代理的处理流程。Markaestro 是执行的手,而不是发声的口。
删除操作仅作用于 Markaestro 一侧
删除一篇已排期的内容会在其发布前取消该内容。删除一篇已发布的内容只会停止 Markaestro 对其进行跟踪,该内容在平台上仍会保持发布状态,直到有人在平台上将其移除为止。
错误处理
教会代理哪些错误值得重试
每个错误响应都是包含稳定 error 代码和 requestId 的 JSON。请让你的代理在报告失败时引用 requestId,这是支持团队追踪该次调用所需的信息。
| 状态码 | 错误代码 | 代理应采取的操作 |
|---|---|---|
| 401 | UNAUTHENTICATED | 密钥缺失、已被撤销或已过期。请停止操作并请求人工提供新密钥,重试无济于事。 |
| 403 | FORBIDDEN | 密钥缺少该调用所需的权限范围。请报告是哪次调用失败;权限范围可在「设置 → API」中修改。 |
| 403 | API_KEY_NOT_BOUND_TO_PRODUCT | 这是一个在品牌绑定机制启用之前签发的密钥。请申请一个替代密钥。 |
| 400 | VALIDATION_* | 请求负载违反了某个渠道规则(素材缺失、投递方式无效、scheduled_at 错误等)。请修正请求;不要在未做修改的情况下重试。 |
| 400 | VALIDATION_IDEMPOTENCY_KEY_REUSED | 同一个 Idempotency-Key 被用于不同的请求体发送。请为每个不同的请求生成一个新密钥。 |
| 400 | VALIDATION_POST_IS_PUBLISHING | 在发布任务进行中时尝试删除该内容。请等待任务完成后再删除。 |
| 409 | VALIDATION_POST_ALREADY_PUBLISHING | 该内容的发布任务已在队列中。请勿再次发布,请轮询现有任务的状态。 |
| 402 | SUBSCRIPTION_REQUIRED | 此工作区未关联有效套餐。请让工作区所有者在“设置”中检查账单。 |
| 402 | QUOTA_EXCEEDED_MEDIA_UPLOADS | 工作区已达到月度上传配额。请停止上传并展示该状态,已有素材仍会正常发布。 |
| 404 | NOT_FOUND | 该 ID 不属于此密钥所在的品牌范围。为防止密钥探测其不拥有的 ID,此处返回 404 而非 403。 |
| 429 | RATE_LIMITED | 等待 Retry-After 指定的秒数,然后使用相同的 Idempotency-Key 重试同一请求。 |
自由选择你的技术栈
只要能发起 HTTPS 请求,就能实现发布
没有需要引入的 Markaestro 专属客户端库,也没有需要遵循的特定框架。持有者令牌、传入 JSON、返回 JSON。
Claude 与 Claude Agent SDK
将上方的工具定义直接添加到你的工具列表中。这些 JSON Schema 结构已经符合 Claude 的工具使用格式。
OpenAI 的 function calling
相同的 Schema 可以一对一映射为函数定义,只需将 input_schema 重命名为 parameters。
MCP 客户端
Claude Code、Claude、Cursor、ChatGPT、Grok、Grok Bot、OpenClaw、Hermes:添加托管服务器 URL 并通过浏览器登录。对于仅支持 stdio 的客户端,npx -y @markaestro/mcp 会在本地运行同样的三十一个工具。
n8n、Make、Zapier
每个接口都是携带持有者令牌的普通 HTTP 请求。无需 SDK,无需签名流程,代理也无需处理 OAuth 授权流程。
LangChain 与 LlamaIndex
标准的 REST 工具。两步式的素材上传是唯一需要多次调用的流程,且仅需两行代码。
一个 cron 任务加 curl
并非每个代理都需要一个完整框架。上方的快速入门就是一个用四条命令即可完成的完整可运行集成。