Vai al contenuto
Riferimento / Prosopo Developers

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
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 percorsoRisultato
POST /api/v1/sessions201 · token, scadenza, persona pubblica, media_token, URL WebSocket
GET /api/v1/sessions/concurrencyactive_sessions, max_sessions, available (indicativo)
GET /api/v1/sessionsSessioni attive visibili alla chiave
GET /api/v1/sessions/{id}Dettagli della sessione attiva
POST /api/v1/sessions/{id}/stopRichiede arresto e rilascio dello slot
GET /api/v1/personasCatalogo pubblico dell’account
GET /api/v1/personas/{id}Persona pubblica
POST /api/v1/personasCrea configurazione persona
PUT /api/v1/personas/{id}Sostituisce configurazione persona
GET /api/v1/openapi.jsonSchema 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.

JSON
{
  "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.

StatoSignificato
400 / 422Origine mancante o payload non valido
401Chiave mancante, non valida o revocata
402Crediti insufficienti
403Origine non autorizzata
404Risorsa assente o di un altro account
503Configurazione server incompleta
Apri lo schema OpenAPI