Risorse
SwiftXEO mette a disposizione un'API REST per workspace, un server MCP con OAuth e webhook in entrata firmati. Tutte le superfici di scrittura sono in modalità di sola proposta; l'approvazione resta sempre in capo a persone autenticate.
Collega Claude, ChatGPT, Cursor o i tuoi sistemi al Business DNA approvato, agli obiettivi e alle lezioni attive. Invia evidenze e proposte attraverso la stessa revisione umana prevista per tutto il resto.
La regola cardine
Un agente collegato tramite API o MCP legge il contesto approvato autorizzato dalle sue credenziali: Business DNA, lezioni attive, obiettivi, cronologia delle revisioni. Può segnalare elementi rilevanti e proporre una lezione utile. Ciò che non può fare è stabilire autonomamente che la propria conclusione sia corretta.
Nessun permesso, tool o payload di webhook può approvare o attivare un apprendimento. Ciò avviene solo all'interno di SwiftXEO, ad opera di una persona autorizzata, secondo le regole di revisione stabilite. L'attivazione di una lezione richiede nello specifico un ruolo di admin o workspace owner.
Principi della Piattaforma Aperta
Accesso vincolato alle credenziali
Il workspace viene derivato dalla chiave. Non può essere selezionato o sovrascritto da un parametro di richiesta.
Leggere il contesto approvato
Business DNA, lezioni attive, obiettivi e tracciabilità — lo stesso archivio che il prodotto mostra a una persona.
Proporre, mai approvare
Le scritture esterne rimangono in attesa di approvazione. Nessun ambito di permesso può raggiungere la rotta di autorizzazione.
Acquisizione di riscontri firmati
I payload dei webhook vengono verificati tramite HMAC e archiviati come contesto connesso per la revisione — mai eseguiti direttamente.
Non verificato per impostazione predefinita
Il materiale esterno viene contrassegnato come non verificato al momento dell'acquisizione. La promozione a contenuto approvato è sempre una decisione umana.
Proiettato, non grezzo
Le risposte sono proiezioni basate su un elenco di autorizzazioni (allowlist). Gli identificativi interni restano all'interno; i revisori appaiono come etichette di ruolo, non con i propri nomi.
Autenticazione
Crea una chiave API del workspace in Impostazioni → Infrastruttura → Accesso Piattaforma Aperta (richiede il ruolo di amministratore del workspace). Il secret viene mostrato solo una volta; viene memorizzato solo il relativo hash. Gli ambiti di lettura sono inclusi dal piano Growth; gli ambiti di scrittura richiedono il piano Execution e vengono verificati al momento dell'uso, in modo che qualsiasi modifica al piano abbia effetto immediato alla richiesta successiva.
Authorization: Bearer sxk_live_k_xxxxxxxx_...
Snapshot del Business DNA, lezioni attive, obiettivi e tracciabilità
Ricerca nel workspace tra argomenti, keyword, campagne, brief e concorrenti
Proposta di apprendimenti — inserita sempre come IN ATTESA nella coda di revisione umana
Invio di dati di riscontro, segnali o documenti come contesto connesso
Generazione di contenuti revisionata — scala crediti dal workspace
Growth = utilizzo delle direttive approvate · Execution = contributo al workflow regolamentato
API REST v1
Ogni risposta utilizza lo stesso formato — { data, meta? } in caso di successo, { error: { code, message } } in caso contrario. Le letture sono limitate a 60 richieste al minuto per workspace, le scritture a 20. La generazione scala i crediti del workspace prima della chiamata al modello.
Snapshot del Business DNA approvato — restituito tramite una proiezione con allowlist delimitata
Lezioni approvate da un essere umano (attive), filtrabili per tipologia
Obiettivi di crescita aperti
Evidenze, storico delle revisioni e approvazione umana per una determinata entità
Proponi un apprendimento — IN ATTESA fino all'approvazione umana
Invio di contesto connesso per la revisione
Generazione di contenuti revisionata, soggetta a crediti. Passa persist: true per salvare il risultato come bozza con indicazione della provenienza del provider/task; altrimenti viene restituito solo il testo
Per attività esterne più complesse, SwiftXEO può assegnare un incarico circoscritto legato a un obiettivo, acquisire il lavoro risultante e collegare le osservazioni successive allo stesso archivio.
Compila un'assegnazione di contesto limitato per un obiettivo autorizzato — la struttura circoscritta su cui opera un agent esterno
Invia il lavoro completato per un incarico — bozza, evidenza o lezione proposta — che viene posto in attesa di revisione umana. Il collegamento tra incarico e risultato viene validato lato server; ID di incarico non validi o inventati vengono rifiutati
Invia un'osservazione qualitativa o metrica rispetto al risultato di un obiettivo, in modo idempotente e soggetto a revisione umana
curl https://www.swiftxeo.com/api/v1/context/dna \
-H "Authorization: Bearer sxk_live_k_xxxxxxxxxxxx_..."
curl -X POST https://www.swiftxeo.com/api/v1/learnings/propose \
-H "Authorization: Bearer sxk_live_k_xxxxxxxxxxxx_..." \
-H "Content-Type: application/json" \
-d '{
"kind": "content_learnings",
"category": "overclaim",
"lesson": "Avoid absolute performance claims without evidence.",
"evidenceNote": "Three campaign replies flagged the launch copy as overstated."
}'Server MCP
L'endpoint /api/mcp gestisce HTTP stateless con supporto allo streaming. I client hosted attualmente testati includono Claude (web, desktop, mobile) e ChatGPT, che si collegano tramite OAuth: incolla l'URL, effettua l'accesso, seleziona un workspace e approva l'accesso. I client basati su file di configurazione come Claude Code e Cursor utilizzano una chiave di workspace statica.
L'elenco degli strumenti è filtrato in base agli scope della connessione: gli strumenti di lettura restituiscono il contesto approvato, quelli di scrittura avanzano solo proposte. Intenzionalmente non esiste alcun strumento di approvazione, attivazione o autorizzazione per nessun livello di scope.
Claude Code, Cursor e altri client basati su file di configurazione
claude mcp add swiftxeo \ https://www.swiftxeo.com/api/mcp \ --transport http \ --header "Authorization: Bearer sxk_live_k_xxxxxxxxxxxx_..."
Claude web, Desktop, mobile e ChatGPT
Aggiungi connettore personalizzato URL: https://www.swiftxeo.com/api/mcp → Accedi a SwiftXEO, seleziona un workspace, approva l'accesso. Nessuna chiave da incollare — questa connessione utilizza OAuth.
Strumenti disponibili
Gli aggiornamenti delle bozze rimangono semplici modifiche alla bozza. Una revisione esterna non può approvare, autorizzare, bloccare o pubblicare l'artefatto, e una bozza revisionata deve superare una nuova revisione prima di poter procedere.
Perimetro
Una chiave API o una connessione MCP/OAuth garantisce un accesso in entrata limitato alle API REST e agli strumenti di SwiftXEO — niente di più. Non registra chi effettua la chiamata come collaboratore nell'Agent Room e non concede mai la visibilità delle @menzioni all'interno dell'Agent Room di un workspace.
Gli assistenti di Agent Room costituiscono un gruppo dedicato e predefinito: Claude, OpenAI, Gemini, l'Advisor e il Verifier di SwiftXEO. Ciascuno segue regole di routing e accesso specifiche che nessuna credenziale esterna può estendere o aggirare.
Il protocollo Local Connector è correlato ma separato. Associa un ambiente di esecuzione locale, come un Mac che esegue task di Agent Room, a un proprio ciclo di credenziali, concessioni e revoche, distinto sia dalle chiavi API che dalle connessioni MCP.
Webhook in entrata
Crea una sorgente in entrata in Impostazioni → Infrastruttura → Sorgenti in entrata per ricevere un endpoint dedicato alla sorgente e un segreto di firma. Ogni payload viene verificato con HMAC-SHA256 sul corpo grezzo prima di essere registrato come contesto collegato — materiale destinato alla revisione umana, mai una verità autonoma. Il fallimento della verifica rifiuta la richiesta prima che qualsiasi dato venga analizzato o archiviato.
Il piano Growth include una sorgente attiva; Execution ne consente multiple.
POST /api/hooks/{workspaceId}/{sourceId}
X-Signature: sha256=<hmac of raw body>
{
"kind": "signal",
"title": "CRM: deal closed",
"body": "Acme signed the annual
plan after the Q3 campaign."
}Domande
No. Nessun permesso API, tool MCP o webhook può contrassegnare una proposta come approvata o accedere al percorso di approvazione. I sistemi esterni possono leggere il contesto approvato, aggiungere evidenze e proporre apprendimenti. Ogni proposta rimane in attesa e l'attivazione di una lezione richiede l'intervento di un admin o dell'owner del workspace autenticato.
Due tipi di credenziali sullo stesso header bearer: una chiave API del workspace statica per i client basati su file di configurazione, o un token di accesso OAuth per i client hosted come Claude e ChatGPT. In entrambi i casi, il workspace viene derivato dalla credenziale — mai dagli argomenti dello strumento.
Il piano Growth include le operazioni di lettura: Business DNA, obiettivi, lezioni attive, tracciabilità e ricerca nel workspace, oltre a una sorgente webhook in entrata. Il piano Execution aggiunge la scrittura: proposta di apprendimenti, invio di evidenze, generazione di contenuti revisionata e sorgenti multiple in entrata.
Solo le etichette dei ruoli. Le risposte destinate all'esterno vengono filtrate attraverso un livello di oscuramento: le identità di revisori e autori diventano "Amministratore del workspace", e gli identificativi interni vengono rimossi prima che qualsiasi dato lasci il workspace.
La documentazione tecnica completa è disponibile nella guida per sviluppatori. La pagina Open Platform illustra il modello di revisione applicato da questi endpoint.