Sviluppatori

Pensato anche per chi sviluppa.

Programma storie, post e reel di Instagram dal tuo codice e leggi i loro risultati. Usa la REST API, il server MCP per gli assistenti IA e i nostri strumenti open source, tutto con una sola chiave API.

API v1

Guida rapida

Crea una chiave API nella pagina Sviluppatori dell’app. Poi elenca i tuoi account Instagram collegati. Questa chiamata funziona con tutti i piani.

GET /v1/connections
curl https://storylink.pro/api/v1/connections \
  -H "Authorization: Bearer sl_live_…"

# → 200 OK
# { "data": [{ "id": "cnx_…", "platform": "instagram", "username": "…", "status": "active" }] }
REST · JSONSpecifica OpenAPIPacchetto npm

Autenticazione

Invia la chiave in ogni richiesta nell’header Authorization: Bearer sl_live_…. Funziona anche l’header X-Storylink-Api-Key.

  • Free: leggi i dati del mese corrente.
  • Pro: leggi tutto lo storico.
  • Business: puoi anche creare e programmare contenuti, con una chiave che ha «Consenti la creazione e la programmazione di contenuti». Lo scegli quando crei la chiave e non puoi cambiarlo in seguito.

Puoi limitare una chiave a uno spazio di lavoro. Una chiave senza spazio di lavoro legge tutti gli spazi di lavoro del tuo account e scrive in quello più vecchio.

POST /v1/stories, /v1/posts e /v1/reels accettano un header Idempotency-Key di massimo 255 caratteri. Per 24 ore, un nuovo tentativo con la stessa chiave e lo stesso body riceve di nuovo la prima risposta e non crea nulla di nuovo.

Tieni le chiavi sul tuo server. Non inserire mai una chiave in un browser o in un’app mobile. Se una chiave viene esposta, revocala nella pagina Sviluppatori.

Endpoint

L’URL di base è https://storylink.pro/api/v1. Richieste e risposte sono in JSON.

Storie

  • POST/storiesProgramma
  • GET/storiesElenca
  • GET/stories/{id}Ottieni uno
  • PATCH/stories/{id}Aggiorna
  • DELETE/stories/{id}Annulla
  • POST/stories/{id}/retry-publishRiprova una pubblicazione non riuscita
  • GET/stories/{id}/insightsInsights

Post

  • POST/postsProgramma
  • GET/postsElenca
  • GET/posts/{id}Ottieni uno
  • PATCH/posts/{id}Aggiorna
  • DELETE/posts/{id}Annulla
  • POST/posts/{id}/retry-publishRiprova una pubblicazione non riuscita
  • GET/posts/{id}/insightsInsights

Reel

  • POST/reelsProgramma
  • GET/reelsElenca
  • GET/reels/{id}Ottieni uno
  • PATCH/reels/{id}Aggiorna
  • DELETE/reels/{id}Annulla
  • POST/reels/{id}/retry-fb-cross-postRiprova la pubblicazione incrociata su Facebook
  • GET/reels/{id}/insightsInsights

Media

  • POST/media/uploadsCrea un caricamento

Connessioni

  • GET/connectionsElenca account
  • GET/connections/{id}Ottieni un account
  • GET/connections/{id}/followersStorico follower

La specifica OpenAPI contiene tutti gli schemi di richiesta e risposta.

Errori

Una richiesta non riuscita restituisce un oggetto error con code, message e docs_url. Il docs_url rimanda al codice in questo elenco.

unauthorized
La richiesta non ha una chiave API.
invalid_api_key
La chiave API non è valida.
api_key_revoked
La chiave API è stata revocata.
api_key_expired
La chiave API è scaduta.
plan_not_entitled
Il tuo piano non include questa richiesta. Le scritture richiedono Business e i dati precedenti a questo mese richiedono Pro.
rate_limited
Troppe richieste. Attendi i secondi indicati nell’header Retry-After.
validation_failed
Un parametro manca o non è valido. Il campo param indica quale.
media_not_ready
Un caricamento di media non è ancora completo.
connection_not_eligible
La connessione non può farlo. Ad esempio, un reel senza connessione Instagram non può riprovare la pubblicazione incrociata su Facebook.
not_found
Non esiste nulla con questo id, oppure la tua chiave non può vederlo.
story_not_in_scheduled_state
Lo stato della storia non lo consente. Puoi aggiornare o annullare solo una storia programmata e riprovare solo una non riuscita.
post_not_in_scheduled_state
Lo stato del post non lo consente. Puoi aggiornare o annullare solo un post programmato e riprovare solo uno non riuscito.
reel_not_in_scheduled_state
Lo stato del reel non lo consente. Puoi aggiornare o annullare solo un reel programmato e riprovare solo uno non riuscito.
workspace_read_only
L’account Instagram dello spazio di lavoro è scollegato. Le letture funzionano ancora, le scritture no. Ricollega l’account nell’app.
workspace_suspended
Storylink ha sospeso questo spazio di lavoro. Contattaci.
idempotency_key_reuse_with_different_body
Hai già inviato questo Idempotency-Key con un body diverso.
idempotency_request_in_progress
Una richiesta con questo Idempotency-Key è ancora in corso.
meta_api_error
Meta ha restituito un errore. Il campo message contiene i dettagli.
meta_unavailable
L’API di Meta è temporaneamente non disponibile. Riprova più tardi.
storage_cap_exceeded
Lo spazio di archiviazione dei media è pieno.
internal_error
Qualcosa non ha funzionato da parte nostra. Riprova o contattaci.

Server MCP

Storylink gestisce un server Model Context Protocol su https://storylink.pro/mcp. Collega Claude o un altro client MCP con la tua chiave API. Poi chiedi delle visualizzazioni, della copertura e delle risposte alle tue storie, su tutti i tuoi account.

Una chiave di sola lettura ha 15 strumenti. Una chiave che può scrivere ne ha 28.

claude mcp add --transport http storylink https://storylink.pro/mcp \
  --header "Authorization: Bearer sl_live_…"

Il codice sorgente è in storylink-mcp. Per report Instagram pronti all’uso, aggiungi storylink-skills.

Poi chiedi, ad esempio: «Perché le visualizzazioni delle mie storie sono calate la settimana scorsa?»

Limiti di frequenza

  • 60 richieste al minuto per ogni chiave. Il server MCP usa lo stesso limite.
  • Oltre il limite, l’API restituisce 429 rate_limited con un header Retry-After.
  • I media che carichi contano nello spazio di archiviazione del tuo piano.
  • Valgono anche i limiti di pubblicazione di Instagram.

Open source

Questi progetti sono pubblici su github.com/storylinkpro, con licenza MIT. Issue e pull request sono benvenute.

instagram-stories-apiUn client per la Instagram Graph API e una CLI per Node.js e TypeScript. Legge storie, post, reel e i loro insights, senza dipendenze.TypeScript · MITstorylink-mcpIl server MCP che collega Claude e altri assistenti IA alle tue analisi Instagram su Storylink.JavaScript · MITstorylink-skillsSkill di Claude per Storylink: report Instagram, analisi dei cali e cosa sta funzionando.MIT
CLI e libreria
npx @storylinkpro/instagram-stories-api stories

import { createClient } from "@storylinkpro/instagram-stories-api";

const ig = createClient({
  accessToken: process.env.INSTAGRAM_ACCESS_TOKEN,
  igUserId: process.env.INSTAGRAM_USER_ID,
});
for (const story of await ig.stories()) {
  const { views, reach, replies } = await ig.storyInsights(story.id);
}

Storylink non è affiliata a Meta Platforms, Inc.

Supporto

Stai creando qualcosa?

Apri una issue su GitHub o scrivici.

GitHubhello@storylink.pro