MarkaestroMarkaestro

개발자

퍼블릭 발행 API

미디어를 업로드하고, 게시물을 생성하고, Facebook, Instagram, TikTok, LinkedIn, Threads, Pinterest에 발행하세요. 모든 요청은 워크스페이스 API 키를 통해 특정 제품 범위로 한정됩니다. 권장하는 연동 방식은 Connect API입니다, 대부분의 예약 도구가 그대로 사용할 수 있는, 작고 평면적인 /api/connect/v1 인터페이스입니다.

명시적 발행, 작업 실행 폴링, 서명된 웹훅, 일괄 처리, 채널별 설정 등 완전한 제어가 필요하신가요? 아래쪽의 고급 /api/public/v1 API가 이 모든 것을 제공합니다. 두 API 모두 동일한 인증, 제품, 발행 파이프라인을 공유합니다. 반드시 버전이 명시된 이 퍼블릭 라우트만 사용하세요(내부 앱 라우트는 Firebase 사용자 인증이 필요하며 퍼블릭 계약의 일부가 아닙니다).

Facebook, Instagram, TikTok은 API에서도 수동 우선 방식입니다. 기본값은 manual_reminder이며, 플랫폼 API를 호출하지 않고 게시물을 '발행 대기' 큐로 이동합니다. 공식 API 발행을 선택하려면 deliveryMode: "direct_publish"를 전달합니다. TikTok은 기본적으로 받은함 전달을 사용하지만 settings.postMode가 direct_post이면 Direct Post를 요청합니다. LinkedIn, Threads, Pinterest는 기본적으로 프로그래매틱 방식으로 발행됩니다.

하나의 워크스페이스는 여러 개의 제품을 가질 수 있습니다. 각 API 키는 생성 시 하나의 제품에 바인딩되므로, 호출은 자동으로 해당 제품을 대상으로 하며 다른 제품에 대한 요청은 거부됩니다.

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

연결된 계정이 중첩된 형태로 브랜드(인터페이스상 명칭: 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(브랜드를 나타내는 인터페이스상 명칭이며, 동일한 계정이 여러 브랜드 아래에 나타날 수 있습니다)가 표시되며, 그 id에는 productId#destinationId가 인코딩되어 있습니다. 이를 social_accounts에 그대로 다시 전달하면 요청은 계정 수만큼 게시물로 확산됩니다. 각 키는 하나의 브랜드에 바인딩되어 있어, 해당 브랜드만 조회하고 게시할 수 있습니다. Facebook, Instagram, TikTok 게시물은 수동 우선 방식입니다, 초안으로 생성되며, 워크스페이스 소유자가 Markaestro의 '발행 대기' 큐에서 직접 게시합니다. 플랫폼 API를 통해 발행되는 일은 절대 없습니다. LinkedIn, Threads, Pinterest는 명시적인 발행 작업 이후 프로그래매틱 방식으로 발행됩니다. 게시물 상태는 draft, processing, posted, failed 중 하나입니다. Facebook, Instagram, LinkedIn, TikTok, Threads는 각각 고유한 전용 발행 대상을 가지며, 한 채널로의 발행이 다른 채널로 확산되는 일은 없습니다. 발행 상태는 GET /api/connect/v1/posts를 통해 추적할 수 있습니다.

고급: 전체 퍼블릭 API

명시적 발행, 비동기 작업 실행, 서명된 웹훅, 일괄 생성, 채널별 설정을 포함한 완전한 /api/public/v1 인터페이스입니다. Connect API로 충분하지 않을 때 사용하세요.

Meta와 TikTok은 수동 우선 방식
Facebook, Instagram, TikTok 게시물은 기본적으로 수동 '발행 대기' 큐로 들어갑니다, 플랫폼 API 호출 없이 워크스페이스 소유자가 직접 게시하고 확인합니다. deliveryMode로 게시물별 API 발행 여부를 선택할 수 있습니다.
Instagram 로그인 지원
Facebook 페이지가 연결되어 있지 않아도 브랜드는 독립된 Instagram 전문 계정을 노출할 수 있습니다.
TikTok은 두 가지 옵트인 경로 지원
API 발행은 기본적으로 받은함 전달을 사용합니다. TikTok 앱이 승인된 경우 개인정보 수준과 함께 settings.postMode를 direct_post로 설정해 Direct Post를 요청할 수 있습니다.
설계상 비동기
모든 발행 요청은 실행 ID를 반환합니다. 동기적으로 완료되었다고 가정하지 말고, 실행 상태를 폴링하거나 서명된 웹훅을 구독하세요.
브랜드 및 발행 대상
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

파일명, 콘텐츠 유형, 정확한 크기로 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을 반환합니다. 발행된 게시물을 삭제해도 플랫폼상의 게시된 콘텐츠는 회수되지 않습니다.

실행 및 웹훅
폴링 또는 서명된 웹훅 전달로 비동기 작업을 추적합니다.
GET/api/public/v1/job-runs/:id

queued, running, succeeded, failed 중 하나를 반환합니다.

POST/api/public/v1/webhook-endpoints

웹훅 대상을 등록합니다. 워크스페이스당 활성 엔드포인트는 최대 25개입니다.

GET/api/public/v1/webhook-endpoints

해당 API 키 권한 범위 내에 등록된 웹훅 대상을 나열합니다.

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

웹훅 대상을 비활성화합니다.

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"
웹훅 페이로드 예시
전달 내용은 여러분의 웹훅 시크릿을 사용해 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

텍스트 전용, 이미지, 또는 동영상 게시물. 게시물당 최대 10개 이미지 또는 동영상 1개. 기본적으로 수동 게시이며, 옵트인 시 직접 발행됩니다.

Instagram

최소 1개의 이미지 또는 동영상, 최대 10개 항목. 단일 동영상은 릴스로 발행됩니다. 기본적으로 수동 게시이며, 옵트인 시 직접 발행됩니다.

TikTok

이미지 또는 동영상이 최소 1개 필요. 최대 35장의 이미지 또는 동영상 1개. 기본은 수동 게시. 허용된 게시물은 크리에이터의 TikTok 받은편지함으로 가거나, TikTok postMode direct_post로 프로필에 바로 게시됩니다.

LinkedIn

텍스트, 단일 이미지, 단일 동영상, 또는 최대 20장까지의 오가닉 다중 이미지 게시물. 연결된 프로필 또는 관리 중인 페이지를 대상으로 지정할 수 있습니다.

X

텍스트, 최대 4장의 이미지, GIF 1개 또는 동영상 1개. 답글 설정은 게시물별로 적용되며, 워크스페이스의 X 비용 예산이 소진되면 게시가 차단됩니다.