REST API
Un contratto HTTP per integrare Prosopo dal tuo backend. Tutti i percorsi sono relativi all’origine pubblica del servizio.
Autenticazione
Usa Authorization: Bearer vtk_… sul server. Crea e revoca le chiavi nello Studio → Sviluppo. La configurazione completa restituita dalle scritture contiene istruzioni private: non inoltrarla al browser. Le letture del catalogo restituiscono solo campi pubblici.
Crea una sessione
Il token dura circa un’ora ed è monouso per il WebSocket. Non riserva uno slot di concorrenza. origin deve corrispondere a una delle origini della chiave. end_user è un’etichetta opzionale, fino a 120 caratteri.
curl "$PROSOPO_BASE_URL/api/v1/sessions" \
-H "Authorization: Bearer $PROSOPO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"persona_id":"ID_PERSONA","origin":"https://app.example"}'Endpoint disponibili
Le liste sono racchiuse in { data: [...] }. PUT sostituisce la configurazione della persona: conserva nel tuo backend il payload completo usato per crearla. Le sessioni elencate sono solo quelle attive sul processo corrente; lo storico e le registrazioni non sono disponibili.
| Metodo e percorso | Risultato |
|---|---|
| POST /api/v1/sessions | 201 · token, scadenza, persona pubblica, media_token, URL WebSocket |
| GET /api/v1/sessions/concurrency | active_sessions, max_sessions, available (indicativo) |
| GET /api/v1/sessions | Sessioni attive visibili alla chiave |
| GET /api/v1/sessions/{id} | Dettagli della sessione attiva |
| POST /api/v1/sessions/{id}/stop | Richiede arresto e rilascio dello slot |
| GET /api/v1/personas | Catalogo pubblico dell’account |
| GET /api/v1/personas/{id} | Persona pubblica |
| POST /api/v1/personas | Crea configurazione persona |
| PUT /api/v1/personas/{id} | Sostituisce configurazione persona |
| GET /api/v1/openapi.json | Schema OpenAPI della superficie REST v1 |
Configura una persona
Puoi impostare nome, avatar_id, voice, model, system_prompt, greeting, language, director_notes, interruptible, knowledge, tools ed embed. Avatar e voce devono essere disponibili nel tuo account. Leggi lo schema OpenAPI per limiti e campi annidati.
{
"name": "Assistente",
"system_prompt": "Aiuta i visitatori con risposte concise.",
"greeting": "Ciao, come posso aiutarti?",
"language": "it",
"interruptible": true,
"embed": { "public_enabled": false }
}Errori HTTP
Gli errori contengono detail (stringa o lista di errori di validazione). Gestisci gli stati prima di leggere il risultato.
| Stato | Significato |
|---|---|
| 400 / 422 | Origine mancante o payload non valido |
| 401 | Chiave mancante, non valida o revocata |
| 402 | Crediti insufficienti |
| 403 | Origine non autorizzata |
| 404 | Risorsa assente o di un altro account |
| 503 | Configurazione server incompleta |