MarkaestroMarkaestro

開発者向け

パブリック投稿API

メディアをアップロードし、投稿を作成して、Facebook、Instagram、TikTok、LinkedIn、Threads、Pinterestに公開できます。すべてワークスペースAPIキーを通じて特定のプロダクトに紐付けられます。統合にはConnect APIを推奨します、ほとんどのスケジューリングツールがそのまま利用できる、小規模でフラットな/api/connect/v1のサーフェスです。

明示的な公開、ジョブ実行のポーリング、署名付きWebhook、バッチ処理、チャネルごとの設定など、より高度な制御が必要な場合は？下部にある高度な/api/public/v1 APIがすべてを公開しています。どちらも同じ認証、プロダクト、投稿パイプラインを共有します。バージョン管理されたこれらのパブリックルートのみを使用してください（内部アプリのルートはFirebaseユーザー認証が必要で、パブリックな契約の対象ではありません）。

Facebook、Instagram、TikTokは、API経由でもマニュアルファーストです。 これらのチャネルはデフォルトでmanual_reminderを使い、MarkaestroはプラットフォームAPIを呼ばず「投稿待ち」キューへ移動します。公式API公開を選ぶにはdeliveryMode: "direct_publish"を渡します。TikTokは通常受信箱への引き渡しを使いますが、settings.postModeがdirect_postの場合はDirect Postを要求します。LinkedIn、Threads、Pinterestはデフォルトでプログラムによる公開が行われます。

ワークスペースは複数のプロダクトを持つことができます。各APIキーは作成時に1つのプロダクトに紐付けられるため、呼び出しは自動的にそのプロダクトを対象とし、他のプロダクトへのリクエストは拒否されます。

AIエージェントを構築していますか？

代わりにAIエージェントガイドから始めてください。コピー＆ペーストできるツールスキーマ、システムプロンプトの概要、エージェントに必要なリトライとエラー処理のルール、4コマンドのクイックスタートが揃っています。エージェントは/llms.txtを直接読み込むこともできます。

機械可読な仕様

すべてのエンドポイント、リクエストとレスポンスの形式、エラーコードを OpenAPI 3.1 で提供します。API が検証に使うスキーマから生成しているため、提供していない API を記述することはありません。

Connect API
推奨
統合のデフォルトの方法：ほとんどのスケジューリングツールがそのまま利用できる、/api/connect/v1のフラットでsnake_caseなサーフェスです。一般的なcreate-upload-url → PUT → postの流れを、下記のフルAPIと同じワークスペース、認証、プロダクト、投稿パイプラインにマッピングします。クライアントのベースURLを/api/connectに設定し、プロダクトに限定されたワークスペースAPIキー（スコープ：posts.read、posts.write、media.write）で認証してください。
GET/api/connect/v1/social-accounts

接続済みのFacebook、Instagram、TikTok、LinkedInの配信先を、それぞれ所属プロダクトのラベル付きでフラットなアカウント一覧として返します。クライアント側でグループ化や識別ができます。各チャネルは専用のパスを持ち、チャネル間のファンアウトはありません。

GET/api/connect/v1/products

接続済みアカウントがネストされたブランド（API上の名称：products）を一覧表示します、ブランドを起点としたピッカーです。

POST/api/connect/v1/media/create-upload-url

短時間有効・1回限り使用の署名付きPUT URLと、メディアIDを返します。

PUT<upload_url>

署名付きURLに画像の生バイトデータをアップロードします。署名自体が認可となるため、APIキーは不要です。

POST/api/connect/v1/posts

選択した各アカウントごとに下書きを作成します。is_draft=falseとscheduled_atを設定すると配信を予約できます。TikTokはクリエイター受信箱への引き渡しを使用します。

GET/api/connect/v1/posts

ワークスペースの投稿を、フラットなステータス、キャプション、メディアURLとともに一覧表示します。

# 1. List connected accounts
curl "$MARKAESTRO_URL/api/connect/v1/social-accounts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

# 2. Request a signed upload url, then PUT the bytes
curl -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": "slide-1.png" }'
curl -X PUT "<upload_url>" -H "Content-Type: image/png" --data-binary @slide-1.png

# 3. Create a draft post for one or more accounts
curl -X POST "$MARKAESTRO_URL/api/connect/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "New drop",
    "media": ["ast_111", "ast_222"],
    "social_accounts": ["prod_123#instagram:instagram:ig_123"]
  }'

/social-accountsから返される各アカウントには、そのproduct（ブランドを表すAPI上の名称。同じアカウントが複数のブランドに紐付くこともあります）がラベル付けされ、そのidにはproductId#destinationIdがエンコードされています、これをsocial_accountsにそのまま渡すと、リクエストはアカウントごとに1件の投稿としてファンアウトされます。各キーは1つのブランドに紐付いており、そのブランドのみを閲覧・投稿できます。Facebook、Instagram、TikTokの投稿はマニュアルファーストです、 下書きとして作成され、Markaestroの「投稿待ち」キューからワークスペースのオーナーがネイティブに公開します。プラットフォームのAPIを経由することはありません。LinkedIn、Threads、Pinterestは明示的な公開アクションの後、プログラムによって公開されます。投稿のステータスはdraft、processing、posted、failedのいずれかです。Facebook、Instagram、LinkedIn、TikTok、Threadsはそれぞれ専用の配信先を持ち、1つへの公開が他へファンアウトすることはありません。公開状態はGET /api/connect/v1/postsを通じて追跡できます。

高度な機能：完全版パブリックAPI

明示的な公開、非同期ジョブ実行、署名付きWebhook、バッチ作成、チャネルごとの設定を含む、完全な/api/public/v1サーフェスです。Connect APIでは不十分な場合にご利用ください。

MetaとTikTokはマニュアルファースト
Facebook、Instagram、TikTokの投稿はデフォルトで手動の「投稿待ち」キューに入ります、プラットフォームAPIの呼び出しはなく、ワークスペースのオーナーがネイティブに投稿して確認します。deliveryModeで投稿ごとにAPI公開を選択できます。
Instagramログインに対応
Facebookページが連携されていない場合でも、ブランドは独立したInstagramプロフェッショナルアカウントを利用できます。
TikTokは2つのオプトイン経路に対応
API公開はデフォルトで受信箱への引き渡しを使います。TikTokアプリが承認済みなら、プライバシーレベルとともにsettings.postModeをdirect_postに設定してDirect Postを要求できます。
設計上、非同期
すべての公開処理は実行IDを返します。同期的な完了を前提とせず、実行状況をポーリングするか、署名付きWebhookを購読してください。
ブランドと配信先
APIキーで利用可能なブランドと公開先を確認できます。ブランドはAPI上ではproductsと呼ばれます、パスとペイロードは後方互換性のためproducts/productIdを使用し、POSTボディはbrandIdをエイリアスとして受け付けます。
GET/api/public/v1/products

キーが持つブランドと、それぞれで現在利用可能なチャネルを一覧表示します。

GET/api/public/v1/products/:id/destinations

そのブランドの公開先を一覧表示します。独立したInstagramログイン、Facebookページ、Threads、LinkedInプロフィール／ページ、接続済みのTikTok配信先が含まれます。

メディア
投稿を作成する前に、画像や動画をMarkaestro管理下のストレージにアップロードします。
POST/api/public/v1/media/upload-sessions

ファイル名、Content-Type、正確なサイズから15分間有効な直接アップロードセッションを作成します。

PUT<uploadSession.uploadUrl>

返されたContent-Typeでストレージへ直接アップロードします。APIキーは送信しません。

POST/api/public/v1/media/upload-sessions/:id/finalize

種類とサイズを検証してメディアアセットを返します。完了済みセッションは安全に再試行できます。

POST/api/public/v1/media

互換用マルチパートアップロード。アセットIDとホスト先URLを返します。

投稿
Facebook、Instagram、LinkedIn、Threads、Pinterest、TikTokの投稿を作成、一覧表示、確認、公開、削除できます。
POST/api/public/v1/posts

ワークスペースに下書きを作成します。Facebook、Instagram、TikTokはデフォルトで手動投稿（deliveryMode manual_reminder）になります。deliveryMode direct_publishを渡すとAPI公開を選択できます。

GET/api/public/v1/posts

投稿を新しい順に一覧表示します。?status=scheduledで予約中の投稿を絞り込み、?productId=で特定のブランドに限定できます。ブランドに紐付いたキーは常に自身のブランドに限定されており、productIdを省略できます。

GET/api/public/v1/posts/:id

現在の投稿ステータス、配信モード、公開結果を返します。

POST/api/public/v1/posts/:id/publish

非同期の公開実行をキューに追加します。手動投稿はワークスペースの「投稿待ち」キューに入りネイティブ投稿を待ちます。LinkedIn、Threads、Pinterestは直接公開され、オプトインしたMeta投稿は公式APIを通じて、オプトインしたTikTok投稿は受信箱への引き渡しを使用します。

DELETE/api/public/v1/posts/:id

Markaestroから投稿を削除します。既存のposts.writeスコープを使用します。公開実行が進行中の場合は400 VALIDATION_POST_IS_PUBLISHINGを返します。公開済みの投稿を削除しても、プラットフォーム上の公開済みコピーは撤回されません。

実行とWebhook
ポーリングまたは署名付きWebhook配信で非同期処理を追跡します。
GET/api/public/v1/job-runs/:id

queued、running、succeeded、failedのいずれかを返します。

POST/api/public/v1/webhook-endpoints

Webhook配信先を登録します。ワークスペースごとに有効なエンドポイントは最大25件です。

GET/api/public/v1/webhook-endpoints

そのAPIキーのスコープで登録済みのWebhook配信先を一覧表示します。

DELETE/api/public/v1/webhook-endpoints/:id

Webhook配信先を無効化します。

1. プロダクトを一覧表示
このAPIキーが対象にできるプロダクトを確認します。
curl "$MARKAESTRO_URL/api/public/v1/products" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
2. 配信先を確認
投稿を作成する前に、プロダクトに紐付いたページやアカウントを確認します。LinkedInプロフィールと複数のページなど、プロダクトが複数の配信先を持つ場合は、返されたdestinationIdを使用してください。
curl "$MARKAESTRO_URL/api/public/v1/products/prod_123/destinations" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
3. メディアをアップロード
各投稿は、事前にアップロードされたメディアアセットを参照します。
# 1. Create a 15-minute upload session
UPLOAD=$(curl -s -X POST "$MARKAESTRO_URL/api/public/v1/media/upload-sessions" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"launch-1.jpg","contentType":"image/jpeg","sizeBytes":184320}')

# 2. PUT bytes directly to uploadSession.uploadUrl with its returned headers
curl -X PUT "<upload_url>" -H "Content-Type: image/jpeg" --data-binary @launch-1.jpg

# 3. Finalize; the response contains asset.id for mediaAssetIds
curl -X POST "$MARKAESTRO_URL/api/public/v1/media/upload-sessions/<session_id>/finalize" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
4. 投稿を作成
それらのアセットIDを使って下書きを作成します。Instagramはデフォルトで手動投稿になります。この投稿を公式API公開の対象にするには"deliveryMode": "direct_publish"を追加してください。
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-001" \
  -d '{
    "channel": "instagram",
    "caption": "Launch day carousel",
    "mediaAssetIds": ["ast_123", "ast_124"],
    "productId": "prod_123",
    "destinationId": "instagram:instagram:ig_123"
  }'
TikTokの例
TikTokの投稿はMarkaestroの下書きとして届き、デフォルトで「投稿待ち」キューからの手動投稿になります。deliveryMode: "platform_inbox"（またはdirect_publish）を使用すると、明示的な公開によって下書きがクリエイターのTikTok受信箱に送信されます。
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-tt-001" \
  -d '{
    "channel": "tiktok",
    "caption": "Spring drop teaser",
    "mediaAssetIds": ["ast_vid_123"],
    "productId": "prod_123",
    "destinationId": "tiktok:tiktok:tt_open_123"
  }'
5. 公開をキューに追加
公開処理は非同期の実行を作成します。手動投稿（Facebook/Instagram/TikTokのデフォルト）は「投稿待ち」キューに移動しpost.action_requiredが発火します。LinkedIn、Threads、Pinterest、オプトインしたMeta投稿は直接公開され、オプトインしたTikTok投稿は受信箱への引き渡しをキューに追加します。
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts/pst_123/publish" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Idempotency-Key: publish-001"
6. スケジュールを確認してキャンセル
ブランドの予約状況を一覧表示し、不要になったものを削除します。どちらも既存のキーがすでに持つスコープ、posts.readとposts.write、 を使用します。
# The key is already bound to one brand
curl "$MARKAESTRO_URL/api/public/v1/posts?status=scheduled&limit=100" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

# Cancel one
curl -X DELETE "$MARKAESTRO_URL/api/public/v1/posts/pst_123" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
Webhookペイロードの例
配信は、あなたのWebhookシークレットを使ってHMACで署名されます。
{
  "id": "evt_123",
  "type": "post.action_required",
  "createdAt": "2026-04-08T18:06:10.000Z",
  "workspaceId": "ws_123",
  "data": {
    "postId": "pst_123",
    "channel": "instagram",
    "status": "platform_action_required",
    "nextAction": "post_manually_from_reminder"
  }
}
チャネルごとの動作
パブリックAPIによって適用されるバリデーションと配信ルールです。

Facebook

テキストのみ、画像、または動画の投稿。1投稿につき最大10枚の画像または1本の動画。デフォルトは手動投稿、オプトインで直接公開。

Instagram

画像または動画を1つ以上、最大10項目。単一動画はリールとして公開されます。デフォルトは手動投稿、オプトインで直接公開。

TikTok

画像または動画が1点以上必要。最大35枚の画像または動画1本。既定は手動投稿。オプトインした投稿はクリエイターのTikTok受信トレイに送られるか、TikTokのpostMode direct_postでプロフィールに直接公開されます。

LinkedIn

テキスト、単一画像、単一動画、または最大20枚までのオーガニックな複数画像投稿。接続済みのプロフィールまたは管理ページを対象にできます。

X

テキスト、最大4枚の画像、GIF 1点、または動画1本。返信設定は投稿ごとに適用され、ワークスペースのXコスト予算を使い切ると公開はブロックされます。