Riferimento API

L’API pubblica (/public/v1) è una superficie REST curata di 5 risorse — lead, contatti, conversazioni, appuntamenti e ticket — autenticata con una chiave API, disponibile nei piani Pro ed Enterprise.

Iniziare con l'APICrea la tua chiave e fai la tua prima chiamata in meno di 10 minuti.

AutenticazioneHeader X-API-Key, scope per risorsa e per azione.

La tua prima richiesta

GET /me non richiede alcun permesso proprio — solo una chiave valida di un tenant con piano idoneo — quindi è il modo più veloce per verificare che la tua chiave funzioni:

curl

curl https://api.aymaragents.com/public/v1/me \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA"

Python

import requests

res = requests.get(
    "https://api.aymaragents.com/public/v1/me",
    headers={"X-API-Key": "aa_TUA_CHIAVE_COMPLETA"},
)
res.raise_for_status()
print(res.json())

JavaScript

const res = await fetch("https://api.aymaragents.com/public/v1/me", {
  headers: { "X-API-Key": "aa_TUA_CHIAVE_COMPLETA" },
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
console.log(await res.json());

Guide

Piani e limitiQuale piano ti serve e quante richieste puoi fare.

ErroriFormato di errore e codici che l'API può restituire.

VersionamentoCome evolve /public/v1 senza rompere la tua integrazione.

Casi d'uso dell'APIScenari reali di integrazione.

Riferimento generato

EndpointOgni operazione di /public/v1, generata dalla stessa definizione OpenAPI usata dal server MCP.

Strumenti correlati

Server MCPCollega il tuo assistente IA alla stessa API.

llms.txtIndice di tutto il portale in testo semplice.

Domande frequenti

Che piano serve per usare l'API pubblica?

Pro o Enterprise. Con il piano Starter, qualsiasi chiamata a /public/v1/* risponde 403 PLAN_NOT_ELIGIBLE, anche se la chiave esiste e ha lo scope corretto. Vedi Piani e limiti.

Cosa succede se la mia chiave non ha esattamente lo scope richiesto da un endpoint?

Ricevi 403 PERMISSION_DENIED, anche con il resto dei suoi permessi intatti. Ogni risorsa ha due scope indipendenti — lettura e gestione. Vedi Autenticazione.

Come ruoto una chiave senza interrompere la mia integrazione?

Oggi non esiste un endpoint di rotazione atomica: crea una nuova chiave con gli stessi scope, aggiorna il segreto nella tua integrazione, poi revoca quella vecchia — c'è una breve finestra con entrambe attive.

Cosa restituisce l'API se chiedo una risorsa di un altro tenant?

404, esattamente come se la risorsa non esistesse — mai 403, che confermerebbe che il dato esiste su un altro account.

Quante richieste posso fare al minuto?

180/minuto e 50.000/giorno su Pro; 600/minuto e 200.000/giorno su Enterprise. La quota viene conteggiata per chiave, non per IP. Vedi Piani e limiti.

Posso cancellare un lead, un contatto o qualsiasi altra risorsa tramite l'API?

No — /public/v1 non ha nessun endpoint DELETE. Vedi Casi d'uso dell'API.

Cosa succede se invio un messaggio WhatsApp fuori dalla finestra di 24 ore?

Ricevi 409 WHATSAPP_SESSION_WINDOW_CLOSED — usa invece POST /conversations/start con un modello approvato. Vedi Errori.

Prossimo passo

Server MCPCollega Claude, Cursor o un altro assistente IA al tuo account.