MarkaestroMarkaestro

Sviluppatori

API pubblica di pubblicazione

Carica contenuti, crea post e pubblica su Facebook, Instagram, TikTok, LinkedIn, Threads e Pinterest, tutto limitato a un prodotto tramite una chiave API del workspace. Il modo consigliato per integrarsi è la Connect API, una superficie piccola e piatta /api/connect/v1 che la maggior parte degli strumenti di programmazione può utilizzare così com'è.

Hai bisogno di controllo completo, pubblicazione esplicita, polling delle esecuzioni, webhook firmati, batch, impostazioni per canale? L'API avanzata /api/public/v1 più in basso espone tutto questo. Entrambe condividono la stessa autenticazione, gli stessi prodotti e la stessa pipeline di pubblicazione; usa solo queste rotte pubbliche versionate (le rotte interne dell'app richiedono l'autenticazione utente Firebase e non fanno parte del contratto pubblico).

Facebook, Instagram e TikTok sono manual-first anche tramite API. Questi canali usano di default manual_reminder: Markaestro non chiama l'API della piattaforma e sposta il post nella coda 'Da Pubblicare'. Passa deliveryMode: "direct_publish" per usare l'API ufficiale. Su TikTok viene usato di default il trasferimento in casella in arrivo, salvo quando settings.postMode è direct_post. LinkedIn, Threads e Pinterest pubblicano programmaticamente di default.

I workspace possono avere più prodotti. Ogni chiave API è vincolata a un prodotto quando la crei, quindi le chiamate hanno come target quel prodotto automaticamente e le richieste per qualsiasi altro prodotto vengono rifiutate.

Stai costruendo un agente IA?

Inizia invece con la guida per agenti IA. Contiene schemi di strumenti pronti da copiare e incollare, una guida rapida per il system prompt, le regole di ripetizione e gestione degli errori di cui un agente ha bisogno, e una guida rapida in quattro comandi. Il tuo agente può anche leggere /llms.txt direttamente.

Specifica leggibile dalle macchine

Ogni endpoint, forma di richiesta e risposta e codice di errore, in OpenAPI 3.1. Generata dagli stessi schemi con cui l'API convalida, quindi non può descrivere un'API che non serviamo.

Connect API
Consigliato
Il modo predefinito per integrarsi: una superficie piatta in snake_case su /api/connect/v1 che la maggior parte degli strumenti di programmazione può utilizzare così com'è. Mappa la convenzione comune create-upload-url → PUT → post sullo stesso workspace, autenticazione, prodotti e pipeline di pubblicazione dell'API completa qui sotto. Imposta l'URL base del client su /api/connect e autenticati con una chiave API del workspace limitata al prodotto (ambiti posts.read, posts.write, media.write).
GET/api/connect/v1/social-accounts

Elenca le destinazioni Facebook, Instagram, TikTok e LinkedIn collegate come account piatti, ciascuno etichettato con il proprio prodotto così che i client possano raggruppare e distinguere. Ogni canale ha il proprio percorso dedicato, nessuna distribuzione tra canali.

GET/api/connect/v1/products

Elenca i brand (nome sul protocollo: products) con i loro account connessi annidati, un selettore che privilegia il brand.

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

Restituisce un URL PUT firmato, monouso e di breve durata, più un id del contenuto.

PUT<upload_url>

Carica i byte grezzi dell'immagine all'URL firmato. Nessuna chiave API necessaria, la firma autorizza.

POST/api/connect/v1/posts

Crea una bozza per ogni account selezionato. Imposta is_draft=false con scheduled_at per programmare la consegna; TikTok usa il trasferimento in casella in arrivo del creator.

GET/api/connect/v1/posts

Elenca i post del workspace con stato, didascalia e URL dei contenuti in formato piatto.

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

Ogni account da /social-accounts è etichettato con il proprio product, il nome sul protocollo per un brand (lo stesso account può apparire sotto più brand), e il suo id codifica productId#destinationId, passalo indietro testualmente in social_accounts, e la richiesta si propaga in un post per account. Ogni chiave è vincolata a un brand, quindi vede e pubblica solo su quel brand. I post di Facebook, Instagram e TikTok sono manuali per prima cosa, creati come bozze e pubblicati nativamente dal proprietario del workspace dalla coda 'Da Pubblicare' di Markaestro, mai tramite l'API della piattaforma. LinkedIn, Threads e Pinterest pubblicano programmaticamente dopo un'azione di pubblicazione esplicita. Lo stato del post è uno tra draft, processing, posted, o failed. Facebook, Instagram, LinkedIn, TikTok e Threads sono ciascuno una propria destinazione dedicata, pubblicare su uno non si propaga mai su un altro. Tieni traccia dello stato di pubblicazione tramite GET /api/connect/v1/posts.

Avanzato: API Pubblica completa

La superficie completa /api/public/v1, pubblicazione esplicita, esecuzioni asincrone, webhook firmati, creazione in batch e impostazioni per canale. Usala quando la Connect API non è sufficiente.

Meta e TikTok sono manuali per prima cosa
I post di Facebook, Instagram e TikTok usano di default la coda manuale 'Da Pubblicare', nessuna chiamata all'API della piattaforma, il proprietario del workspace pubblica nativamente e conferma. Opta per la pubblicazione tramite API per singolo post con deliveryMode.
Login Instagram supportato
I brand possono esporre account professionali Instagram indipendenti anche quando non è collegata nessuna Pagina Facebook.
TikTok supporta due percorsi opt-in
La pubblicazione API usa di default la casella in arrivo. Imposta settings.postMode su direct_post con un livello di privacy per richiedere Direct Post se l'app TikTok è approvata.
Asincrono per design
Ogni pubblicazione restituisce un id di esecuzione. Interroga le esecuzioni o iscriviti ai webhook firmati invece di presumere un completamento sincrono.
Brand e destinazioni
Scopri i brand e le destinazioni di pubblicazione disponibili per la chiave API. I brand sono chiamati products nel formato del protocollo, i percorsi e i payload usano products/productId per retrocompatibilità, e i corpi POST accettano anche brandId come alias.
GET/api/public/v1/products

Elenca i brand della chiave più i canali attualmente disponibili per ciascuno.

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

Elenca le destinazioni di pubblicazione per quel brand, inclusi Login Instagram indipendente, Pagina Facebook, Threads, Profilo/Pagina LinkedIn e destinazioni TikTok connesse.

Contenuti
Carica immagini o video nell'archiviazione gestita da Markaestro prima di creare i post.
POST/api/public/v1/media/upload-sessions

Crea una sessione di caricamento diretto di 15 minuti con nome, tipo e dimensione esatta.

PUT<uploadSession.uploadUrl>

Carica i byte direttamente nello storage con il Content-Type restituito, senza chiave API.

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

Verifica tipo e dimensione e restituisce l'asset multimediale; le sessioni completate sono ritentabili.

POST/api/public/v1/media

Caricamento multipart di compatibilità. Restituisce un id dell'asset e l'URL ospitato.

Post
Crea, elenca, ispeziona, pubblica ed elimina post per Facebook, Instagram, LinkedIn, Threads, Pinterest e TikTok.
POST/api/public/v1/posts

Crea una bozza nel workspace. Facebook, Instagram e TikTok usano di default la pubblicazione manuale (deliveryMode manual_reminder); passa deliveryMode direct_publish per optare per la pubblicazione via API.

GET/api/public/v1/posts

Elenca i post, dal più recente. Filtra con ?status=scheduled per vedere cosa è in coda, e ?productId= per limitare a un brand. Una chiave vincolata a un brand è sempre limitata al proprio brand e può omettere productId.

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

Restituisce lo stato attuale del post, la modalità di consegna e i risultati della pubblicazione.

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

Mette in coda un'esecuzione di pubblicazione asincrona. I post manuali finiscono nella coda 'Da Pubblicare' del workspace per la pubblicazione nativa; LinkedIn, Threads e Pinterest pubblicano direttamente; i post Meta con opt-in pubblicano tramite l'API ufficiale, e i post TikTok con opt-in usano il trasferimento in casella in arrivo.

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

Elimina il post da Markaestro. Usa l'ambito posts.write esistente. Restituisce 400 VALIDATION_POST_IS_PUBLISHING mentre un'esecuzione di pubblicazione è in corso. Eliminare un post pubblicato non ritira la copia in diretta sulla piattaforma.

Esecuzioni e Webhook
Tieni traccia del lavoro asincrono con polling o consegna webhook firmata.
GET/api/public/v1/job-runs/:id

Restituisce queued, running, succeeded, o failed.

POST/api/public/v1/webhook-endpoints

Registra una destinazione webhook, fino a 25 endpoint attivi per workspace.

GET/api/public/v1/webhook-endpoints

Elenca le destinazioni webhook registrate per l'ambito di quella chiave API.

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

Disabilita una destinazione webhook.

1. Elenca i prodotti
Scopri a quali prodotti può puntare questa chiave API.
curl "$MARKAESTRO_URL/api/public/v1/products" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
2. Ispeziona le destinazioni
Vedi le pagine e gli account collegati a un prodotto prima di creare il post. Usa il destinationId restituito quando un prodotto ha più destinazioni, come un Profilo LinkedIn più Pagine.
curl "$MARKAESTRO_URL/api/public/v1/products/prod_123/destinations" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
3. Carica i contenuti
Ogni post fa riferimento ad asset multimediali caricati in precedenza.
# 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. Crea un post
Crea una bozza usando quegli id di asset. Instagram usa di default la pubblicazione manuale; aggiungi "deliveryMode": "direct_publish" per optare per la pubblicazione via API ufficiale su questo post.
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"
  }'
Esempio TikTok
I post TikTok arrivano come bozze Markaestro e usano di default la pubblicazione manuale dalla coda 'Da Pubblicare'. Con deliveryMode: "platform_inbox" (o direct_publish), una pubblicazione esplicita invia invece la bozza alla casella in arrivo del creator.
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. Metti in coda la pubblicazione
La pubblicazione crea un'esecuzione asincrona. I post manuali (il default di Facebook/Instagram/TikTok) si spostano nella coda 'Da Pubblicare' e attivano post.action_required; LinkedIn, Threads, Pinterest e i post Meta con opt-in pubblicano direttamente; i post TikTok con opt-in mettono in coda il trasferimento in casella in arrivo.
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts/pst_123/publish" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Idempotency-Key: publish-001"
6. Rivedi la programmazione e annulla
Elenca cosa è in coda per un brand, poi elimina tutto ciò che non vuoi più pubblicare. Entrambi usano ambiti che le chiavi esistenti già possiedono: posts.read e 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"
Esempio di payload webhook
Le consegne sono firmate con HMAC usando il tuo segreto webhook.
{
  "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"
  }
}
Comportamento per canale
Regole di validazione e consegna applicate dall'API pubblica.

Facebook

Post di solo testo, immagine o video. Fino a 10 immagini o 1 video per post. Pubblicazione manuale di default; pubblicazione diretta con opt-in.

Instagram

Almeno un'immagine o un video, fino a 10 elementi. Un singolo video viene pubblicato come Reel. Pubblicazione manuale di default; pubblicazione diretta con opt-in.

TikTok

Almeno un'immagine o un video. Fino a 35 immagini o 1 video. Pubblicazione manuale per impostazione predefinita; i post abilitati vanno nella inbox TikTok del creator, oppure direttamente sul profilo con postMode direct_post di TikTok.

LinkedIn

Testo, immagine singola, video singolo, o post organici con più immagini fino a 20 immagini. Scegli come destinatario il Profilo connesso o una Pagina gestita.

X

Testo, fino a quattro immagini, una GIF o un video. I controlli sulle risposte si applicano per post e la pubblicazione viene bloccata quando il budget di costo X del workspace è esaurito.