MarkaestroMarkaestro

Per agenti IA

Collega il tuo agente in un passaggio. Gestisce lui i tuoi canali social.

Markaestro è fatto per essere usato dal software. Un client MCP come Claude Code accede dal browser e riceve una chiave legata a un solo brand; qualsiasi altro agente ottiene la stessa chiave dalle Impostazioni. In entrambi i casi l'agente può scoprire su quali account può pubblicare, caricare media, scrivere e programmare post, pubblicarli e riferire cosa è davvero uscito, su Facebook, Instagram, TikTok, LinkedIn, Threads e Pinterest.

Nessun SDK da installare, nessuna credenziale di piattaforma da custodire. Il tuo team collega gli account una volta nella dashboard; da lì in poi l'agente parla con un'unica API a token bearer.

Progettata per l'autonomia, limitata di proposito

Perché una chiave API è tutta l'integrazione

La parte difficile di lasciare che un agente tocchi i social media non è l'HTTP. È assicurarsi che un modello confuso non possa pubblicare sul brand sbagliato, pubblicare due volte durante un tentativo ripetuto, o inviare qualcosa che nessuno ha letto. Queste garanzie sono nella superficie dell'API stessa, non nel tuo prompt.

Una chiave, un brand
Ogni chiave API è vincolata a un singolo brand quando la crei. Un agente che possiede quella chiave può solo vedere e pubblicare su quel brand, le richieste tra brand vengono rifiutate all'autenticazione, non per convenzione.
Scoperta, non id fissi
L'agente chiede su quali account può pubblicare e riceve indietro id opachi da ripassare direttamente. Nessun id di Pagina, nessuna esplorazione del Business Manager, nessun file di configurazione che si degrada quando una connessione viene ricollegata.
Scritture idempotenti
Invia un Idempotency-Key su qualsiasi creazione o pubblicazione. Una chiamata ripetuta entro 24 ore riproduce la risposta originale invece di creare un secondo post, il modo di fallimento più comune per gli agenti.
Una persona rimane nel processo
I post di Facebook, Instagram e TikTok sono manuali per prima cosa: il tuo agente li prepara, una persona li pubblica nativamente. Nulla esce senza supervisione a meno che tu non lo abiliti esplicitamente per quel post.

Client MCP

Accedi dal client. Niente da incollare.

Claude Code, Claude, Cursor, ChatGPT, Grok, Grok Bot, OpenClaw, Hermes e ogni altro client che parla il Model Context Protocol possono collegarsi al server MCP ospitato di Markaestro senza credenziali configurate. La prima chiamata a uno strumento apre il browser: accedi, scegli lo spazio di lavoro e il brand su cui l'agente può agire, controlla i permessi e premi Consenti. Il client riceve una chiave legata a quel brand e la rinnova da solo.

È OAuth 2.1 standard con PKCE e registrazione dinamica dei client, lo stesso meccanismo degli altri server MCP ospitati, quindi funziona senza alcun plugin specifico di Markaestro. Il server si trova su https://markaestro.com/api/public/v1/mcp ed espone trentuno strumenti sopra l'API pubblica: scoperta di brand e destinazioni, caricamento media, bozze e post programmati, pubblicazione con monitoraggio delle esecuzioni, operazioni in blocco, webhook e regole per canale.

Collega il tuo agente

Scegli il tuo agente. Tre passaggi e può pubblicare.

Ogni client qui sotto raggiunge lo stesso server MCP ospitato. La maggior parte accede tramite browser: la prima chiamata a uno strumento apre una pagina di consenso dove scegli lo spazio di lavoro e il brand su cui l'agente può agire, e il client riceve una chiave legata a quel brand. I client che non possono aprire un browser usano una chiave API dello spazio di lavoro. Stesso server, stessi permessi, stesso elenco nelle Impostazioni.

Claude Code

Il plugin installa la skill e il server ospitato insieme. Niente da configurare, niente da incollare.

Accesso o chiave APIDocumentazione Claude Code
01

Prima di iniziare

  • Sei proprietario o amministratore dello spazio di lavoro con email verificata, in uno spazio con piano attivo e almeno un brand.
  • Claude Code è installato e connesso al tuo account Anthropic.
03

Accedi

  1. Chiedi a Claude qualcosa su Markaestro, oppure esegui /mcp e scegli markaestro.
  2. Il browser apre la pagina di consenso. Scegli spazio di lavoro e brand, controlla i permessi, fai clic su Consenti.
  3. Per cambiare brand in seguito, esegui di nuovo /mcp, esci e accedi con l'altro brand.
Preferisci l'accesso. Usa una chiave solo se il client non può aprire un browser.
04

Verifica

  • Chiedi all'agente di chiamare list_products. Deve rispondere con l'unico brand autorizzato e i suoi canali collegati.
  • La connessione compare in Impostazioni, API con il badge Agente collegato, l'ultimo utilizzo e il volume di richieste. Puoi revocarla lì in qualsiasi momento.
Apri Impostazioni, API
02

Aggiungi il server

  1. Esegui i due comandi del plugin in un terminale, oppure aggiungi solo il server con il terzo comando.
Bash
# 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/mcp

Cosa succede quando il client si collega

Cinque passaggi, tutti gestiti dal client e dal browser. Tu vedi solo la pagina di consenso.

01Sfida
POST /api/public/v1/mcp → 401 + WWW-Authenticate

Il client chiama l'endpoint MCP senza credenziali. Markaestro risponde 401 con un header WWW-Authenticate che indica il documento di metadati della risorsa protetta. È quell'header a dire al client che è disponibile un accesso.

02Discovery
GET /.well-known/oauth-protected-resource · /.well-known/oauth-authorization-server

Il client legge due documenti pubblici: quale server di autorizzazione protegge l'endpoint e dove si trovano i suoi endpoint di registrazione, autorizzazione e token. Entrambi sono serviti su markaestro.com e memorizzabili in cache.

03Registrazione
POST /api/public/v1/oauth/register

Il client si registra con un nome e il suo indirizzo di ritorno. Sono accettati indirizzi loopback, ritorni https e schemi di app native; l'http semplice verso un host reale è rifiutato. Non serve alcun id client precondiviso.

04Consenso
GET /oauth/authorize (browser)

Il browser apre la pagina di consenso. Un proprietario o amministratore dello spazio di lavoro con email verificata sceglie spazio e brand, regola i permessi e premi Consenti. Markaestro rimanda il browser al client con un codice monouso.

05Token di accesso
POST /api/public/v1/oauth/token

Il client scambia il codice più il suo verificatore PKCE con un token di accesso e un token di refresh. Il token di accesso è una normale chiave API dello spazio di lavoro, legata al brand scelto. Scade dopo 30 giorni; un refresh ne ruota il segreto e lo estende di altri 30.

Il token è una vera chiave API

Scope, vincolo al brand, limiti di frequenza, controlli dell'abbonamento, idempotenza e revoca seguono lo stesso codice di una chiave creata a mano. Non c'è un secondo modello di permessi da capire.

Elencato e revocabile nelle Impostazioni

Un agente collegato compare in Impostazioni, API con il badge Agente collegato, l'ultimo utilizzo e il volume di richieste. Revocalo lì e la chiamata successiva del client fallisce; il client può anche revocare il proprio token quando lo scolleghi.

Una connessione, un brand

Ogni connessione è legata a esattamente un brand, scelto al consenso. Per far lavorare un agente su un secondo brand, collegalo di nuovo e scegli quel brand. Un client non può mai raggiungere un brand che non gli è stato concesso.

Codici e token di refresh monouso

I codici di autorizzazione durano dieci minuti e vengono consumati in modo atomico, quindi un codice riutilizzato fallisce. I token di refresh ruotano a ogni uso e sono salvati come hash. Le registrazioni dei client inattivi scadono dopo 180 giorni.

Punti di accesso

Per chi costruisce un client MCP o verifica il flusso. Tutto è individuabile dai due documenti well-known; niente di questo va configurato a mano.

Riferimento
# 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 …" }

Il ciclo dell'agente

Cinque chiamate, dall'inizio alla fine

Ogni automazione Markaestro è una variazione di questo ciclo. I passaggi da uno a tre sono la Connect API, la superficie piatta su cui la maggior parte degli agenti dovrebbe puntare. I passaggi quattro e cinque raggiungono l'API completa /api/public/v1 per la pubblicazione esplicita e il tracciamento delle esecuzioni.

01Scoprire
GET /api/connect/v1/social-accounts

Restituisce ogni account connesso e pubblicabile per il brand della chiave, ciascuno con una piattaforma, un nome utente e un id opaco. Chiamalo all'inizio di ogni esecuzione, le connessioni cambiano.

02Caricare contenuti
POST /api/connect/v1/media/create-upload-url → PUT

Genera un URL firmato, monouso e di breve durata, poi fai PUT dei byte grezzi verso di esso. Ricevi indietro un id del contenuto. Immagini fino a 10 MB; l'API completa accetta anche video fino a 250 MB.

03Creare una bozza o programmare
POST /api/connect/v1/posts

Passa la didascalia, gli id dei contenuti e gli id degli account testualmente. Lascialo come bozza per la revisione, oppure invia is_draft false con scheduled_at per metterlo sul calendario.

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

Mette in coda un'esecuzione asincrona. LinkedIn, Threads e Pinterest escono tramite l'API ufficiale. Facebook, Instagram e TikTok finiscono nella coda 'Da Pubblicare' del workspace affinché una persona pubblichi nativamente.

05Riferire i risultati
GET /api/public/v1/job-runs/:id · webhooks

Interroga l'id dell'esecuzione, oppure registra un endpoint webhook e lascia che Markaestro ti invii post.published, post.action_required e post.failed. Non presumere mai che una pubblicazione sia terminata in modo sincrono.

Guida Rapida

Un'integrazione funzionante in quattro comandi

Prima, genera la chiave: apri Impostazioni → API, scegli il brand a cui può accedere, seleziona gli ambiti di cui ha bisogno e, facoltativamente, imposta una scadenza. La chiave viene mostrata una sola volta, inseriscila direttamente nell'archivio segreti del tuo agente. La creazione di chiavi richiede un amministratore o proprietario con email verificata.

1. Scoprire gli account
La prima chiamata in ogni esecuzione. Le connessioni cambiano; gli id non dovrebbero mai essere incorporati in un prompt.
Bash
# 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"
Risposta
{
  "data": [
    {
      "id": "prod_123#instagram:instagram:ig_123",
      "product_id": "prod_123",
      "product": "Northwind Coffee",
      "platform": "instagram",
      "username": "northwindcoffee"
    }
  ]
}
2. Caricare i contenuti
Due passaggi: genera un URL firmato e monouso, poi fai PUT dei byte. L'URL scade dopo 15 minuti e non richiede alcuna intestazione di autenticazione propria.
Bash
# 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.png
3. Programmalo, poi osservalo
La creazione è bozza per prima cosa di default. Invia is_draft: false con un timestamp scheduled_at per mettere invece il post sul calendario.
Bash
# 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"

Pronto all'uso

Definizioni degli strumenti e guida per l'agente

Due cose da copiare. La prima è un set di schemi di strumenti che copre l'intero ciclo di pubblicazione, scritto in JSON Schema, così funziona come definizioni di strumenti Claude, funzioni OpenAI, o la forma di input per un server MCP che ospiti tu. La seconda è la guida operativa che impedisce a un modello di fare qualcosa di inaspettato con essi.

Schemi degli strumenti
Sei strumenti: elenca account, carica contenuti, crea, pubblica, elenca, elimina. Collega ciascuno all'endpoint corrispondente qui sopra.
tools.json
[
  {
    "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"]
    }
  }
]
Guida per l'agente
Incollala nel tuo system prompt. Codifica i comportamenti che separano un agente di pubblicazione affidabile da uno che pubblica due volte e dichiara vittoria troppo presto.
System prompt
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.

Il tuo agente può anche recuperare questo contenuto da solo: curl https://markaestro.com/llms.txt restituisce una guida in testo semplice dell'intera API, endpoint, regole e gestione degli errori, abbastanza piccola da stare nel contesto.

Ricette

I quattro workflow che gli agenti eseguono davvero

Pubblica e conferma
Crea una bozza, pubblicala esplicitamente, poi interroga l'esecuzione. L'unico modo onesto per dire all'operatore che un post è uscito.
Bash
# 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"
Verifica e annulla la coda
Elenca cosa è programmato, mostralo a una persona, elimina ciò che rifiuta. Entrambe le chiamate usano ambiti che una chiave esistente già possiede.
Bash
# 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" }
Riempi una settimana in una chiamata
La creazione in batch accetta fino a 25 post e restituisce risultati per singolo elemento, così un elemento malformato non compromette l'intera esecuzione.
Bash
# 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 }
Ricevi una chiamata invece di fare polling
Gli agenti di lunga durata dovrebbero registrare un webhook e mettersi in pausa. Le consegne sono firmate con HMAC usando un segreto mostrato una sola volta alla creazione.
Bash
# 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.

Salvaguardie

Cosa l'agente può e non può fare

L'autonomia è utile solo se il raggio d'azione è limitato. Le impostazioni predefinite di Markaestro presumono che chi chiama sia software che potrebbe sbagliare.

Facebook, Instagram e TikTok sono manuali per prima cosa

I post che il tuo agente crea per questi canali usano di default manual_reminder: Markaestro non chiama mai l'API della piattaforma per loro. La pubblicazione sposta il post nella coda 'Da Pubblicare' del workspace, dove una persona scarica i contenuti, pubblica nativamente e conferma, così il post appare esattamente come se fosse stato fatto a mano, e una persona vede ognuno di essi prima che esista pubblicamente. Un agente può optare per la pubblicazione via API ufficiale di un singolo post con deliveryMode: "direct_publish", e su TikTok questo significa il trasferimento in casella in arrivo del creator, mai un post pubblico senza supervisione. LinkedIn, Threads e Pinterest pubblicano programmaticamente solo quando il tuo agente lo richiede esplicitamente.

Limita gli ambiti della chiave

Scegli solo gli ambiti di cui l'agente ha bisogno: products.read, media.write, posts.read, posts.write, posts.publish, job_runs.read, webhooks.manage. Un agente di ricerca che legge solo il calendario riceve posts.read e nient'altro.

Imposta una scadenza

Le chiavi possono essere create con una scadenza. Una chiave scaduta si comporta esattamente come una revocata, così una chiave che fuoriesce dall'ambiente di un agente smette di funzionare da sola.

Ruota e revoca

Ruota una chiave sul posto o revocala completamente da Impostazioni → API. Ogni chiave mostra l'ora dell'ultimo utilizzo e il volume di richieste, così un agente che diventa silenzioso, o incontrollato, è visibile.

I limiti di frequenza sono applicati

60 richieste al minuto per endpoint e 240 al minuto per chiave. Ogni risposta porta X-RateLimit-Limit, -Remaining e -Reset; un 429 porta Retry-After. Rispettalo invece di insistere.

Markaestro non scrive mai per te

Non esiste alcun passaggio di generazione. La didascalia proviene dal tuo agente, i contenuti provengono dalla tua libreria o dalla pipeline del tuo agente. Markaestro sono le mani, non la voce.

Le eliminazioni sono lato Markaestro

Eliminare un post programmato lo annulla prima che venga pubblicato. Eliminare un post pubblicato ferma solo il tracciamento di Markaestro, il post in diretta resta attivo finché qualcuno non lo rimuove sulla piattaforma.

Gestione degli errori

Insegnagli quali errori vale la pena ripetere

Ogni risposta di errore è JSON con un codice error stabile e un requestId. Fai in modo che il tuo agente citi il requestId quando segnala un fallimento, è ciò di cui il supporto ha bisogno per tracciare la chiamata.

StatoCodiceCosa dovrebbe fare l'agente
401UNAUTHENTICATEDLa chiave è mancante, revocata, o scaduta. Fermati e chiedi a una persona una nuova chiave, ripetere il tentativo non aiuterà.
403FORBIDDENLa chiave manca dell'ambito per questa chiamata. Segnala quale chiamata è fallita; gli ambiti si cambiano in Impostazioni → API.
403API_KEY_NOT_BOUND_TO_PRODUCTUna chiave emessa prima del vincolo al brand. Richiedi una chiave sostitutiva.
400VALIDATION_*Il payload ha violato una regola del canale (contenuti mancanti, modalità di consegna errata, scheduled_at sbagliato). Correggi la richiesta; non ripeterla senza modifiche.
400VALIDATION_IDEMPOTENCY_KEY_REUSEDLo stesso Idempotency-Key è stato inviato con un corpo diverso. Genera una nuova chiave per ogni richiesta distinta.
400VALIDATION_POST_IS_PUBLISHINGTentativo di eliminare un post mentre un'esecuzione di pubblicazione è in corso. Attendi che l'esecuzione si stabilizzi, poi elimina.
409VALIDATION_POST_ALREADY_PUBLISHINGUn'esecuzione di pubblicazione per questo post è già in coda. Non pubblicare di nuovo, interroga invece l'esecuzione esistente.
402SUBSCRIPTION_REQUIREDNessun piano attivo è associato a questo workspace. Chiedi a un proprietario di controllare la fatturazione nelle Impostazioni.
402QUOTA_EXCEEDED_MEDIA_UPLOADSIl workspace ha raggiunto la sua quota mensile di caricamento. Smetti di caricare e segnalalo, i contenuti esistenti continuano a essere pubblicati.
404NOT_FOUNDL'id è fuori dal brand di questa chiave. Risposto come 404 invece di 403 così le chiavi non possono sondare id che non possiedono.
429RATE_LIMITEDAttendi i secondi indicati da Retry-After, poi ripeti la stessa richiesta con lo stesso Idempotency-Key.

Usa il tuo stack preferito

Se può fare una richiesta HTTPS, può pubblicare

Non esiste una libreria client Markaestro da adottare né un framework da standardizzare. Bearer token, JSON in ingresso, JSON in uscita.

Claude e il Claude Agent SDK

Aggiungi le definizioni degli strumenti qui sopra alla tua lista di strumenti. Le forme JSON Schema sono già nel formato di utilizzo strumenti di Claude.

Function calling di OpenAI

Gli stessi schemi si mappano uno a uno sulle definizioni di funzione, rinomina input_schema in parameters.

Client MCP

Claude Code, Claude, Cursor, ChatGPT, Grok, Grok Bot, OpenClaw, Hermes: aggiungi l'URL del server ospitato e accedi dal browser. Per i client solo stdio, npx -y @markaestro/mcp esegue gli stessi trentuno strumenti in locale.

n8n, Make, Zapier

Ogni endpoint è una semplice richiesta HTTP con un bearer token. Nessun SDK, nessuna cerimonia di firma, nessuna danza OAuth per l'agente.

LangChain e LlamaIndex

Strumenti REST standard. Il caricamento contenuti in due passaggi è l'unico flusso con chiamate multiple, ed è due righe.

Un cron job e curl

Non ogni agente ha bisogno di un framework. La guida rapida qui sopra è un'integrazione completa e funzionante in quattro comandi.

Dai al tuo agente qualcosa di reale da fare

Collega i tuoi canali, poi il tuo agente: accedi da un client MCP oppure crea una chiave legata a un brand. Ognuna delle due è l'intera integrazione.