MarkaestroMarkaestro

Ontwikkelaars

Publieke publicatie-API

Upload media, maak posts aan en publiceer naar Facebook, Instagram, TikTok, LinkedIn, Threads en Pinterest, alles beperkt tot één product via een workspace-API-sleutel. De aanbevolen manier om te integreren is de Connect API, een kleine, platte /api/connect/v1-interface die de meeste planningstools zo kunnen gebruiken.

Heb je volledige controle nodig, expliciete publicatie, job-run polling, ondertekende webhooks, batch, instellingen per kanaal? De geavanceerde /api/public/v1-API verderop biedt dit allemaal. Beide delen dezelfde authenticatie, producten en publicatiepijplijn; gebruik alleen deze geversieerde publieke routes (interne app-routes vereisen Firebase-gebruikersauthenticatie en maken geen deel uit van het publieke contract).

Facebook, Instagram en TikTok zijn manual-first, ook via de API. Deze kanalen gebruiken standaard manual_reminder: Markaestro roept de platform-API niet aan en zet de post in de 'Te Plaatsen'-wachtrij. Geef deliveryMode: "direct_publish" mee voor officiële API-publicatie. TikTok gebruikt standaard overdracht naar de inbox, behalve wanneer settings.postMode direct_post is. LinkedIn, Threads en Pinterest publiceren standaard programmatisch.

Workspaces kunnen meerdere producten hebben. Elke API-sleutel wordt bij het aanmaken gekoppeld aan één product, zodat aanroepen automatisch dat product als doel hebben en verzoeken voor een ander product worden geweigerd.

Bouw je een AI-agent?

Begin in plaats daarvan met de AI-agentgids. Deze bevat kant-en-klare toolschema's, een system-prompt-samenvatting, de retry- en foutafhandelingsregels die een agent nodig heeft, en een snelstartgids met vier commando's. Je agent kan ook rechtstreeks /llms.txt lezen.

Machineleesbare specificatie

Elk endpoint, elke request- en responsvorm en elke foutcode, als OpenAPI 3.1. Gegenereerd uit dezelfde schema's waartegen de API valideert, dus hij kan geen API beschrijven die we niet aanbieden.

Connect API
Aanbevolen
De standaardmanier om te integreren: een platte, snake_case-interface op /api/connect/v1 die de meeste planningstools zo kunnen gebruiken. Het mapt de gangbare create-upload-url → PUT → post-conventie op dezelfde workspace, authenticatie, producten en publicatiepijplijn als de volledige API hieronder. Stel de basis-URL van de client in op /api/connect en authenticeer met een productgebonden workspace-API-sleutel (scopes posts.read, posts.write, media.write).
GET/api/connect/v1/social-accounts

Toont gekoppelde Facebook-, Instagram-, TikTok- en LinkedIn-bestemmingen als platte accounts, elk gelabeld met het product zodat clients kunnen groeperen en onderscheiden. Elk kanaal heeft zijn eigen pad, geen fan-out over kanalen.

GET/api/connect/v1/products

Toont merken (interfacenaam: products) met hun verbonden accounts genest, een selector die merken voorop stelt.

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

Retourneert een kortstondige, eenmalig bruikbare ondertekende PUT-URL plus een media-id.

PUT<upload_url>

Upload de ruwe afbeeldingsbytes naar de ondertekende URL. Geen API-sleutel nodig, de handtekening autoriseert dit.

POST/api/connect/v1/posts

Maakt een concept aan per geselecteerd account. Stel is_draft=false in samen met scheduled_at om levering in te plannen; TikTok gebruikt de overdracht naar de inbox van de maker.

GET/api/connect/v1/posts

Toont workspaceposts met platte status, onderschrift en media-URL's.

# 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"]
  }'

Elk account uit /social-accounts is gelabeld met zijn product, de interfacenaam voor een merk (hetzelfde account kan onder meerdere merken voorkomen), en de id codeert productId#destinationId, geef deze letterlijk terug in social_accounts, en het verzoek waaiert uit naar één post per account. Elke sleutel is aan één merk gebonden, dus ziet en post alleen naar dat merk. Posts op Facebook, Instagram en TikTok zijn manual-first, aangemaakt als concept en native gepubliceerd door de workspace-eigenaar vanuit de 'Te Plaatsen'-wachtrij van Markaestro, nooit via de API van het platform. LinkedIn, Threads en Pinterest publiceren programmatisch na een expliciete publicatiehandeling. Poststatus is één van draft, processing, posted of failed. Facebook, Instagram, LinkedIn, TikTok en Threads zijn elk hun eigen toegewijde bestemming, publiceren naar één kanaal waaiert nooit uit naar een ander. Volg de publicatiestatus via GET /api/connect/v1/posts.

Geavanceerd: volledige Publieke API

De volledige /api/public/v1-interface, expliciete publicatie, asynchrone jobruns, ondertekende webhooks, batchaanmaak en instellingen per kanaal. Gebruik dit wanneer de Connect API niet volstaat.

Meta en TikTok zijn manual-first
Posts op Facebook, Instagram en TikTok gaan standaard naar de handmatige 'Te Plaatsen'-wachtrij, geen platform-API-aanroep, de workspace-eigenaar plaatst native en bevestigt. Kies per post voor API-publicatie met deliveryMode.
Instagram-login ondersteund
Merken kunnen zelfstandige zakelijke Instagram-accounts weergeven, zelfs als er geen Facebook-pagina is gekoppeld.
TikTok ondersteunt twee opt-inpaden
API-publicatie gebruikt standaard de inbox. Stel settings.postMode in op direct_post met een privacyniveau om Direct Post te vragen wanneer je TikTok-app is goedgekeurd.
Asynchroon van opzet
Elke publicatie retourneert een run-id. Peil de runs of abonneer je op ondertekende webhooks in plaats van synchrone voltooiing aan te nemen.
Merken en bestemmingen
Ontdek de merken en publicatiebestemmingen die beschikbaar zijn voor de API-sleutel. Merken heten products in de interfacenaamgeving, paden en payloads gebruiken products/productId voor achterwaartse compatibiliteit, en POST-berichten accepteren ook brandId als alias.
GET/api/public/v1/products

Toont de merken van de sleutel plus de kanalen die momenteel voor elk beschikbaar zijn.

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

Toont de publicatiebestemmingen voor dat merk, inclusief zelfstandige Instagram-login, Facebook-pagina, Threads, LinkedIn-profiel/pagina en verbonden TikTok-bestemmingen.

Media
Upload afbeeldingen of video's naar door Markaestro beheerde opslag voordat je posts aanmaakt.
POST/api/public/v1/media/upload-sessions

Maakt een directe uploadsessie van 15 minuten met bestandsnaam, contenttype en exacte grootte.

PUT<uploadSession.uploadUrl>

Uploadt bytes rechtstreeks naar opslag met het teruggegeven Content-Type; stuur geen API-sleutel.

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

Controleert type en grootte en retourneert het media-asset; voltooide sessies kunnen veilig opnieuw worden geprobeerd.

POST/api/public/v1/media

Compatibele multipart-upload. Retourneert een asset-id en gehoste URL.

Posts
Maak posts aan, toon ze, inspecteer ze, publiceer en verwijder ze voor Facebook, Instagram, LinkedIn, Threads, Pinterest en TikTok.
POST/api/public/v1/posts

Maakt een concept aan in de workspace. Facebook, Instagram en TikTok gebruiken standaard handmatig plaatsen (deliveryMode manual_reminder); geef deliveryMode direct_publish mee om te kiezen voor API-publicatie voor een post.

GET/api/public/v1/posts

Toont posts, nieuwste eerst. Filter met ?status=scheduled om te zien wat in de wachtrij staat, en ?productId= om te beperken tot één merk. Een merkgebonden sleutel is altijd beperkt tot zijn eigen merk en kan productId weglaten.

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

Retourneert de huidige poststatus, leveringsmodus en publicatieresultaten.

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

Plaatst een asynchrone publicatierun in de wachtrij. Handmatige posts komen in de 'Te Plaatsen'-wachtrij van de workspace terecht voor native plaatsing; LinkedIn, Threads en Pinterest publiceren direct; aangemelde Meta-posts publiceren via de officiële API, en aangemelde TikTok-posts gebruiken de overdracht naar de inbox.

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

Verwijdert de post uit Markaestro. Gebruikt de bestaande posts.write-scope. Retourneert 400 VALIDATION_POST_IS_PUBLISHING terwijl een publicatierun bezig is. Het verwijderen van een gepubliceerde post trekt de live kopie op het platform niet terug.

Runs en Webhooks
Volg asynchroon werk via polling of ondertekende webhook-levering.
GET/api/public/v1/job-runs/:id

Retourneert queued, running, succeeded of failed.

POST/api/public/v1/webhook-endpoints

Registreert een webhook-bestemming, tot 25 actieve endpoints per workspace.

GET/api/public/v1/webhook-endpoints

Toont geregistreerde webhook-bestemmingen voor die API-sleutelscope.

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

Schakelt een webhook-bestemming uit.

1. Toon producten
Ontdek welke producten deze API-sleutel als doel kan hebben.
curl "$MARKAESTRO_URL/api/public/v1/products" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
2. Inspecteer bestemmingen
Bekijk de gekoppelde pagina's en accounts voor een product voordat je de post aanmaakt. Gebruik de geretourneerde destinationId wanneer een product meerdere bestemmingen heeft, zoals een LinkedIn-profiel plus pagina's.
curl "$MARKAESTRO_URL/api/public/v1/products/prod_123/destinations" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
3. Upload media
Elke post verwijst naar eerder geüploade media-assets.
# 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. Maak een post aan
Maak een concept aan met die asset-id's. Instagram gebruikt standaard handmatig plaatsen; voeg "deliveryMode": "direct_publish" toe om deze post te laten kiezen voor publicatie via de officiële API.
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-voorbeeld
TikTok-posts komen aan als Markaestro-concepten en gebruiken standaard handmatig plaatsen vanuit de 'Te Plaatsen'-wachtrij. Met deliveryMode: "platform_inbox" (of direct_publish) stuurt een expliciete publicatie het concept in plaats daarvan naar de inbox van de maker.
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. Plaats publicatie in wachtrij
Publicatie creëert een asynchrone run. Handmatige posts (de standaard voor Facebook/Instagram/TikTok) gaan naar de 'Te Plaatsen'-wachtrij en activeren post.action_required; LinkedIn, Threads, Pinterest en aangemelde Meta-posts publiceren direct; aangemelde TikTok-posts plaatsen de overdracht naar de inbox in de wachtrij.
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts/pst_123/publish" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Idempotency-Key: publish-001"
6. Bekijk de planning en annuleer
Toon wat er in de wachtrij staat voor een merk, verwijder vervolgens alles wat je niet meer wilt publiceren. Beide gebruiken scopes die bestaande sleutels al hebben: posts.read en 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"
Voorbeeld van webhook-payload
Leveringen worden ondertekend met HMAC met je webhook-geheim.
{
  "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"
  }
}
Kanaalgedrag
Validatie- en leveringsregels die door de publieke API worden afgedwongen.

Facebook

Posts met alleen tekst, afbeelding of video. Tot 10 afbeeldingen of 1 video per post. Standaard handmatig plaatsen; directe publicatie bij aanmelding.

Instagram

Minstens één afbeelding of video, tot 10 items. Een enkele video wordt gepubliceerd als Reel. Standaard handmatig plaatsen; directe publicatie bij aanmelding.

TikTok

Minstens één afbeelding of video. Tot 35 afbeeldingen of 1 video. Standaard handmatig plaatsen; vrijgegeven posts gaan naar de TikTok-inbox van de maker, of rechtstreeks naar het profiel met TikTok postMode direct_post.

LinkedIn

Tekst, enkele afbeelding, enkele video, of organische posts met meerdere afbeeldingen tot 20 afbeeldingen. Richt je op het verbonden Profiel of een beheerde Pagina.

X

Tekst, tot vier afbeeldingen, één GIF of één video. Antwoordinstellingen gelden per post en publiceren wordt geblokkeerd zodra het X-kostenbudget van de workspace op is.