OPOperPilot
Ottieni chiave API
REST API v1 & Protocollo MCP • Standard 2026

Documentazione REST API v1 & Model Context Protocol (MCP)

Gestisci brand, genera contenuti AI, programma post su 15 piattaforme e integra OperPilot in Claude Desktop, Cursor AI o Make.com.

URL di base API di produzione:

https://app.operpilot.com/api/v1

Autenticazione (API Key)

Tutte le richieste richiedono una chiave API inviata nell'header Authorization come Bearer token. Crea le chiavi nella dashboard.

Limiti di frequenza (Rate Limits)

Il limite standard è di 60 richieste al minuto per chiave API. Il superamento restituisce il codice 429 Too Many Requests.

MCP Protocol

Model Context Protocol (MCP)

Collega OperPilot direttamente a Claude Desktop, Cursor AI o qualsiasi client MCP per consentire all'AI di usare 12 strumenti dedicati.

Configurazione in Claude Desktop

claude_desktop_config.json
{
  "mcpServers": {
    "operpilot": {
      "command": "node",
      "args": ["-e", "fetch('https://app.operpilot.com/operpilot-mcp.mjs').then(r=>r.text()).then(eval)"],
      "env": {
        "OPERPILOT_API_KEY": "op_live_YOUR_API_KEY"
      }
    }
  }
}

Configurazione in Cursor AI (.cursor/mcp.json)

.cursor/mcp.json
{
  "mcpServers": {
    "operpilot": {
      "command": "node",
      "args": ["-e", "fetch('https://app.operpilot.com/operpilot-mcp.mjs').then(r=>r.text()).then(eval)"],
      "env": {
        "OPERPILOT_API_KEY": "op_live_YOUR_API_KEY"
      }
    }
  }
}

12 Strumenti MCP OperPilot

Una volta integrato il server MCP, il tuo assistente AI accede istantaneamente a queste 12 funzioni con comandi in linguaggio naturale.

get_profile

MCP Tool

DNA del brand: profilo aziendale, settore, target, Brand Voice e linee guida visive — contesto per l'AI.

Prompt di esempio in Claude / Cursor:
“Recupera il profilo del mio brand e dimmi quale tono di voce dovrei adottare.”
Restituisce: Object: { name, description, industry, targetAudience, brandVoice, visualGuidelines, primaryColors, website }

connected_accounts

MCP Tool

Canali attivi: elenco dei profili collegati (tra 15 piattaforme) pronti per la pubblicazione immediata o programmata.

Prompt di esempio in Claude / Cursor:
“Quali profili social sono attualmente collegati al mio account OperPilot?”
Restituisce: Array of { id, platform, name, accountType, isConnected, avatarUrl }

generate_post

MCP Tool

Copywriter AI: genera post con hashtag in 7 lingue (PL, EN, DE, ES, FR, IT, UK) perfettamente allineati alla Brand Voice.

Prompt di esempio in Claude / Cursor:
“Scrivi un post per LinkedIn sui vantaggi dell'automazione dei social media.”
ParametroTipoRichiestoDescrizione
topicstringRichiestoTema o messaggio principale.
languagestringOpzionaleCodice lingua ('pl', 'en', 'de', 'es', 'fr', 'it', 'uk').
platformstringOpzionalePiattaforma di destinazione (es. 'linkedin').
tonestringOpzionaleTono (es. 'esperto', 'amichevole').
Restituisce: Object: { content, hashtags, suggestedPlatform, charCount }

generate_ideas

MCP Tool

Generatore di idee strategiche: propone nuovi spunti e format adatti al tuo settore.

Prompt di esempio in Claude / Cursor:
“Suggerisci 5 argomenti educativi per il mio settore per la prossima settimana.”
ParametroTipoRichiestoDescrizione
topicstringOpzionaleArgomento opzionale.
localestringOpzionaleLingua delle proposte.
Restituisce: Object: { ideas: Array<{ title, angle, targetFormat, hook }> }

translate_post

MCP Tool

Localizzazione multilingue: traduce e adatta i post per 7 mercati europei preservando la Brand Voice.

Prompt di esempio in Claude / Cursor:
“Traduci questo post in tedesco mantenendo un tono amichevole e informale.”
ParametroTipoRichiestoDescrizione
textstringRichiestoTesto originale da tradurre.
target_languagestringRichiestoLingua di destinazione ('pl', 'en', 'de', 'es', 'fr', 'it', 'uk').
Restituisce: Object: { translatedText, targetLanguage, notes }

create_post

MCP Tool

Creazione post: crea un post in OperPilot, assegna i canali e imposta la data o pubblica all'istante.

Prompt di esempio in Claude / Cursor:
“Crea un post intitolato 'Lancio versione 2.0' e programmalo per domani alle 10:00 su Facebook e LinkedIn.”
ParametroTipoRichiestoDescrizione
titlestringRichiestoTitolo del post.
contentstringRichiestoTesto completo con hashtag.
platformsarrayOpzionaleElenco piattaforme.
scheduled_atstringOpzionaleData ISO. Vuoto = bozza.
publish_nowbooleanOpzionaleTrue per pubblicare subito.
Restituisce: Object: { id, title, status, scheduledAt, platforms }

list_posts

MCP Tool

Registro post: consulta le pubblicazioni filtrate per stato: draft, scheduled, published, failed.

Prompt di esempio in Claude / Cursor:
“Mostrami i prossimi 5 post programmati nel mio calendario.”
ParametroTipoRichiestoDescrizione
statusstringOpzionaleFiltro stato.
limitnumberOpzionaleLimite post (default 20).
Restituisce: Array of { id, title, content, status, scheduledAt, platforms, createdAt }

schedule_post

MCP Tool

Pianificatore: riprogramma o assegna data e ora a un post esistente.

Prompt di esempio in Claude / Cursor:
“Riprogramma il post ID 8f7e... a venerdì prossimo alle 18:00.”
ParametroTipoRichiestoDescrizione
post_idstringRichiestoID del post (UUID).
scheduled_atstringRichiestoNuova data ISO.
Restituisce: Object: { id, status: 'scheduled', scheduledAt }

publish_post

MCP Tool

Pubblicazione immediata: invia un post esistente per la trasmissione istantanea su tutti i canali.

Prompt di esempio in Claude / Cursor:
“Pubblica subito questo post su tutti i profili collegati.”
ParametroTipoRichiestoDescrizione
post_idstringRichiestoID del post (UUID).
Restituisce: Object: { id, status: 'published', publishedAt, results }

delete_post

MCP Tool

Eliminazione: cancella definitivamente il post e annulla le trasmissioni in coda.

Prompt di esempio in Claude / Cursor:
“Elimina la bozza con ID b4c1...”
ParametroTipoRichiestoDescrizione
post_idstringRichiestoID del post (UUID).
Restituisce: Object: { success: true, deletedId }

analytics

MCP Tool

Centro analisi: metriche aggregate di impressioni, interazioni, like e commenti suddivisi per piattaforma.

Prompt di esempio in Claude / Cursor:
“Quali sono le statistiche di reach e interazione degli ultimi 30 giorni?”
Restituisce: Object: { summary: { totalImpressions, totalEngagements, totalLikes }, platforms: { ... } }

list_brands

MCP Tool

Gestione brand: elenco dei brand/clienti nell'area di lavoro (piani Pro e Business).

Prompt di esempio in Claude / Cursor:
“Mostra tutti i brand configurati nel mio account OperPilot.”
Restituisce: Array of { id, name, industry, isDefault }
REST API

Riferimento REST API v1

Per integrazioni HTTP dirette con i tuoi backend, script di automazione o strumenti no-code (Make.com, n8n, Zapier).

Base URL:https://app.operpilot.com/api/v1
GET

/profile

Recupero profilo brand e Brand Voice

Restituisce le linee guida del brand: nome, settore, descrizione, target, stile comunicativo e palette cromatica.

curl -X GET "https://app.operpilot.com/api/v1/profile" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "profile": {
    "name": "Acme Software",
    "description": "Platforma automatyzacji AI dla e-commerce i marketingu B2B.",
    "industry": "Software / B2B SaaS",
    "targetAudience": "Właściciele sklepów internetowych, menedżerowie marketingu",
    "brandVoice": "Profesjonalny, oparty na faktach, technologiczny",
    "website": "https://example.com"
  }
}
GET

/channels

Elenco canali collegati

Restituisce i profili connessi tra i 15 canali social supportati.

curl -X GET "https://app.operpilot.com/api/v1/channels" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "channels": [
    {
      "id": "conn_91f8a2b3",
      "platform": "facebook",
      "name": "Acme Fanpage",
      "isConnected": true
    },
    {
      "id": "conn_44c21e7d",
      "platform": "linkedin",
      "name": "Acme Corporate",
      "isConnected": true
    }
  ]
}
GET

/posts

Elenco post e calendario

Restituisce le pubblicazioni con filtro per stato.

ParametroTipoRichiestoDescrizione
statusstring (query)OpzionaleFiltro stato.
limitnumber (query)OpzionaleLimite (max 50).
curl -X GET "https://app.operpilot.com/api/v1/posts" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "posts": [
    {
      "id": "c7a84e12-4215-4ff1-a8bc-19b841e42109",
      "title": "Nowości w ofercie",
      "status": "scheduled",
      "scheduledAt": "2026-10-25T14:00:00.000Z",
      "platforms": ["facebook", "linkedin"]
    }
  ]
}
POST

/posts

Creazione nuovo post

Crea un post, associa i canali e lo programma o pubblica all'istante.

ParametroTipoRichiestoDescrizione
titlestringRichiestoTitolo del post.
contentstringRichiestoTesto con hashtag.
platformsarrayOpzionalePiattaforme di destinazione.
scheduled_atstringOpzionaleData ISO programmata.
publish_nowbooleanOpzionaleTrue per invio immediato.
curl -X POST "https://app.operpilot.com/api/v1/posts" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Nowy post z API",
    "content": "Właśnie publikujemy ten wpis automatycznie przez OperPilot REST API v1 🚀",
    "platforms": ["facebook", "linkedin"],
    "publish_now": true
  }'
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "success": true,
  "post": {
    "id": "c7a84e12-4215-4ff1-a8bc-19b841e42109",
    "title": "Nowy post z API",
    "status": "scheduled",
    "scheduledAt": "2026-10-25T14:00:00.000Z",
    "platforms": ["facebook", "linkedin"]
  }
}
GET

/posts/:id

Dettagli e stato di pubblicazione

Restituisce i dettagli del post con gli ID di pubblicazione esterna.

ParametroTipoRichiestoDescrizione
idstring (path)RichiestoID del post (UUID).
curl -X GET "https://app.operpilot.com/api/v1/posts/c7a84e12-4215-4ff1-a8bc-19b841e42109" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "post": {
    "id": "c7a84e12-4215-4ff1-a8bc-19b841e42109",
    "title": "Jak automatyzacja oszczędza czas?",
    "status": "published",
    "targets": [
      { "platform": "facebook", "status": "published", "remotePostId": "fb_123456" },
      { "platform": "linkedin", "status": "published", "remotePostId": "urn:li:share:789" }
    ]
  }
}
PATCH

/posts/:id

Aggiornamento o riprogrammazione post

Consente di modificare testo, titolo o la data programmata.

ParametroTipoRichiestoDescrizione
idstring (path)RichiestoID del post (UUID).
titlestringOpzionaleNuovo titolo.
contentstringOpzionaleNuovo testo.
scheduled_atstringOpzionaleNuova data ISO.
curl -X PATCH "https://app.operpilot.com/api/v1/posts/c7a84e12-4215-4ff1-a8bc-19b841e42109" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_at": "2026-10-25T16:00:00.000Z"
  }'
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "success": true,
  "post": {
    "id": "c7a84e12-4215-4ff1-a8bc-19b841e42109",
    "status": "scheduled",
    "scheduledAt": "2026-10-25T16:00:00.000Z"
  }
}
DELETE

/posts/:id

Eliminazione post

Cancella definitivamente il post e annulla i task in coda.

ParametroTipoRichiestoDescrizione
idstring (path)RichiestoID del post (UUID).
curl -X DELETE "https://app.operpilot.com/api/v1/posts/c7a84e12-4215-4ff1-a8bc-19b841e42109" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY"
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "success": true,
  "message": "Post został pomyślnie usunięty."
}
GET

/analytics

Statistiche e analisi delle pubblicazioni

Fornisce riepilogo di visualizzazioni, interazioni, like e commenti per canale.

curl -X GET "https://app.operpilot.com/api/v1/analytics" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "analytics": {
    "totalImpressions": 24500,
    "totalEngagements": 1820,
    "totalLikes": 1240,
    "totalComments": 185,
    "totalShares": 95,
    "byPlatform": {
      "facebook": { "impressions": 12000, "engagements": 920 },
      "linkedin": { "impressions": 8500, "engagements": 650 },
      "instagram": { "impressions": 4000, "engagements": 250 }
    }
  }
}
GET

/brands

Elenco brand nell'area di lavoro

Restituisce tutti i brand configurati nell'account (piani Pro e Business).

curl -X GET "https://app.operpilot.com/api/v1/brands" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Accept: application/json"
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "brands": [
    {
      "id": "brand_01a",
      "name": "Acme Software",
      "industry": "IT & Automation",
      "isDefault": true
    }
  ]
}
AI Engine

Motore AI in 7 lingue (Generazione, Idee, Traduzione)

Endpoint nativi per il copywriting e la localizzazione per 15 canali social rispettando il Brand Voice del marchio.

Lingue supportate di pubblicazione e localizzazione:
PL (pl) EN (en) DE (de) ES (es) FR (fr) IT (it) UK (uk)
POST

/ai/generate

Generazione post con AI (7 lingue)

Genera post allineati alla Brand Voice in una delle 7 lingue (PL, EN, DE, ES, FR, IT, UK) comprensivi di hashtag.

ParametroTipoRichiestoDescrizione
topicstringRichiestoArgomento o messaggio chiave.
languagestringOpzionaleCodice lingua ('pl', 'en', 'de', 'es', 'fr', 'it', 'uk').
platformstringOpzionalePiattaforma target.
tonestringOpzionaleTono.
curl -X POST "https://app.operpilot.com/api/v1/ai/generate" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Wprowadzenie automatyzacji social media w firmie",
    "language": "it",
    "platform": "linkedin",
    "tone": "expert"
  }'
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "content": "Czy wiesz, że regularność w publikacji to klucz do algorytmów social media? 🚀\n\nOto 3 kroki, jak zautomatyzować publikacje bez utraty jakości...",
  "hashtags": ["#marketing", "#automatyzacja", "#socialmedia", "#productivity"],
  "language": "pl",
  "characterCount": 420
}
POST

/ai/ideas

Generatore di idee e concept strategici

Offre una serie di proposte di post, ganci e formati adatti al tuo pubblico.

ParametroTipoRichiestoDescrizione
topicstringOpzionaleFocus tematico.
localestringOpzionaleLingua delle idee.
curl -X POST "https://app.operpilot.com/api/v1/ai/ideas" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Marketing tips",
    "locale": "it"
  }'
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "ideas": [
    {
      "title": "5 błędów w planowaniu postów, które obcinają zasięg",
      "angle": "Post edukacyjny / checklista",
      "targetFormat": "Karuzela lub wątek",
      "hook": "Robisz to co tydzień? Algorytmy tego nie lubią..."
    }
  ]
}
POST

/ai/translate

Traduzione e adattamento culturale del post

Traduce i post in 7 lingue considerando espressioni idiomatiche e Brand Voice.

ParametroTipoRichiestoDescrizione
textstringRichiestoTesto da tradurre.
target_languagestringRichiestoLingua target ('pl', 'en', 'de', 'es', 'fr', 'it', 'uk').
curl -X POST "https://app.operpilot.com/api/v1/ai/translate" \
  -H "Authorization: Bearer op_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Nasz nowy produkt jest już dostępny w sprzedaży!",
    "target_language": "de"
  }'
Risposta di esempio (HTTP 200 OK):
200 OK • JSON
{
  "translatedText": "Did you know that consistency is the #1 factor in social media reach? 🚀\n\nHere are 3 ways to automate your schedule while keeping human touch...",
  "targetLanguage": "en"
}

Codici di errore e limiti di richiesta

OperPilot segue i codici di stato HTTP standard con messaggi di errore JSON descrittivi.

Codice HTTPNomeSignificato e risoluzione
200 OKSuccessRichiesta completata con successo.
201 CreatedCreatedRisorsa creata con successo.
400 Bad RequestInvalid RequestParametri obbligatori mancanti o non validi.
401 UnauthorizedUnauthorizedChiave API mancante o non valida nell'header Authorization.
403 ForbiddenForbiddenChiave revocata o privilegi insufficienti.
404 Not FoundNot FoundRisorsa o post non trovato.
429 Too Many RequestsRate LimitedLimite di richieste superato (60 req/min). Riprova tra poco.
500 Internal ErrorServer ErrorErrore interno del server. Contatta kontakt@operpilot.com.

Automazione No-Code (Make.com, Zapier, n8n)

Integra facilmente OperPilot nei tuoi scenari Make.com o Zapier tramite modulo HTTP standard:

Passaggi di configurazione in Make.com:

  1. Aggiungi il modulo HTTP -> Make a request.
  2. Imposta l'URL: https://app.operpilot.com/api/v1/posts e Method: POST.
  3. Aggiungi gli Headers: Authorization = Bearer op_live_TUA_CHIAVE e Content-Type = application/json.
  4. Seleziona Raw -> JSON Body e passa i campi title, content, platforms e publish_now.