Uso automatizzato

In passato aprire un account Hushscript richiedeva una persona, almeno una volta. Non è più tutta la storia. Un flusso basato sul pagamento anticipato permette a un agente di aprire il proprio account, finanziarlo e gestirlo, senza alcun titolare umano in nessun punto del processo. /developers e /mcp documentano le due interfacce che questo account usa in seguito; questa pagina è la guida per ottenerne uno.

Registrazione

POST /v1/agent/accounts avvia una registrazione headless. Non esiste ancora nessun account, nessun cookie e nessun token: solo un acquisto in sospeso.

curl -X POST https://api.hushscript.com/v1/agent/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "ops@example-agent.dev",
    "pack_id": "300min",
    "accept_terms_version": "2026-08-01",
    "agent": {
      "name": "research-crawler",
      "platform": "langgraph",
      "contact_url": "https://example-agent.dev/bots/research-crawler"
    }
  }'

{
  "signup_id": "hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061",
  "claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6",
  "pack": "300min",
  "amount": 599,
  "currency": "usd",
  "expires_at": 1789112400
}

contact_email serve solo per ricevute e avvisi, mai per l’accesso. pack_id è uno tra 45min, 300min, 900min, 1800min, 6000min; non inviare mai tu stesso amount o currency, entrambi sono derivati dal pacchetto lato server. Solo i due pacchetti più piccoli, 45min e 300min, possono essere acquistati in fase di registrazione. Un pack_id più grande viene rifiutato, e il rifiuto include details.allowed_packs, che elenca cosa questo account può acquistare in questo momento, così chi chiama può riprovare senza indovinare. Il resto della scala si sblocca con l’anzianità, non con il volume: vedi Cosa può acquistare un account nuovo più sotto. accept_terms_version deve corrispondere esattamente alla versione delle policy attuale del server, altrimenti la chiamata fallisce con policy_version_stale, che indica il valore attuale nel corpo della risposta. Un suggerimento opzionale data_region viene rispettato solo se concorda con la regione già implicata dalla tua posizione di rete. Un dry_run: true opzionale convalida tutto senza creare una sessione Stripe e senza addebiti; il suo signup_id ha il prefisso dry_ e non può mai essere reclamato.

claim_secret viene mostrato esattamente una volta, in questa risposta. Hushscript ne conserva solo l’hash. Perderlo prima della chiamata di reclamo significa perdere la registrazione: non esiste un percorso di recupero per un claim secret, e il pagamento trattenuto in garanzia viene rimborsato dalla scansione periodica descritta più sotto, non restituito tramite una ricerca.

Completa il pagamento nel tuo browser

checkout_url è una pagina di Stripe Checkout ospitata. È l’unico passaggio dell’intero flusso che richiede un browser, e non deve necessariamente essere il browser di una persona: un agente può pilotarlo con la propria automazione (compilare i campi della carta, inviare, seguire il redirect). Hushscript non vede mai i dati della carta in nessuno dei due casi; li vede Stripe. La finestra per completarlo e poi reclamare è di 30 minuti, il valore expires_at visto sopra.

Una registrazione che viene pagata ma non viene mai reclamata viene rimborsata automaticamente da una scansione oraria, circa un’ora dopo la chiusura di quella finestra di 30 minuti. Il rimborso è totale, perché i minuti vengono accreditati sul saldo solo al momento del reclamo, quindi una registrazione mai reclamata non ne ha mai avuti da consumare.

Reclama l’account

POST /v1/agent/accounts/{signup_id}/claim trasforma una registrazione pagata e non reclamata in un account vero, con un’unica chiamata.

curl -X POST https://api.hushscript.com/v1/agent/accounts/hsr1:eu:4c3a1f9e7b2d4e6f8a0c1b2d3e4f5061/claim \
  -H "Content-Type: application/json" \
  -d '{"claim_secret": "cs_9f3d2a1b7e6c4f5a8b9d0e1f2a3b4c5d"}'

{
  "user_id": "usr_7d1a2b3c4d5e6f708192a3b4c5d6e7f8",
  "pat": "hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "balance_seconds": 18000
}

Il reclamo è a uso singolo. Crea esattamente un account, con dietro un’identità di accesso sintetica e non risolvibile, concede il pacchetto pagato esattamente una volta anche se la richiesta viene ripetuta, e genera esattamente un PAT: il valore pat mostrato sopra, anch’esso mostrato una sola volta.

Un secret sbagliato, un signup_id sconosciuto, una registrazione già reclamata, una rimborsata e una scaduta rispondono tutte con lo stesso errore agent_claim_invalid. Non c’è modo per chi chiama di distinguerle dalla risposta, di proposito. Solo una volta che il secret stesso risulta valido entra in gioco lo stato del pagamento: una Checkout Session non ancora liquidata risponde invece con wrong_state.

Il balance_seconds mostrato sopra è l’intero saldo iniziale. Gli account agente non ricevono alcun bonus di benvenuto né minuti gratuiti dalla verifica della carta come invece accade per il primo account di una persona; partono solo dal pacchetto che hanno pagato. È una scelta deliberata, non una lacuna: l’account era già stato pagato prima ancora di esistere.

Acquista altri minuti

Da qui in poi l’account si comporta come qualsiasi altro, sulla stessa superficie /v1/ che /developers documenta per intero.

curl -X POST https://api.hushscript.com/v1/billing/purchase \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "pack": "300min",
    "quick_payment_method_id": "pm_1PqR2sT3uV4wX5yZ",
    "idempotency_key": "purchase-2026-09-11-01"
  }'

{
  "balance_seconds": 36000
}

Questo richiede lo scope billing, già concesso dalla risposta di reclamo mostrata sopra, e condivide un limite più stretto di 60 richieste al minuto per account con la rotta di salvataggio della carta, prima della chiamata a Stripe che entrambe effettuano.

Cosa può acquistare un account nuovo

La dimensione dei pacchetti si sblocca in base all’anzianità dei pagamenti liquidati, non in base a quanto spende un account. Un acquisto conta per il livello successivo solo una volta trascorsi 7 giorni dalla propria data di pagamento, quindi un account appena creato non può raggiungere i pacchetti più grandi acquistando in fretta.

Un acquisto rifiutato indica l’insieme attuale in details.allowed_packs invece di fallire alla cieca. La chiamata di registrazione applica la prima riga di quella tabella, motivo per cui la guida qui sopra acquista 300min e non qualcosa di più grande. Indipendentemente dalla scala, un limite di consumo mobile su 24 ore limita quanto velocemente può essere speso il saldo che non ha ancora superato in anzianità la finestra di contestazione.

Trascrivi

Caricare e trascrivere seguono lo stesso flusso multipart di qualsiasi altro account.

curl -X POST https://api.hushscript.com/v1/uploads \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170" \
  -H "Content-Type: application/json" \
  -d '{
    "size_bytes": 48213504,
    "duration_seconds": 1860,
    "title": "weekly-standup-2026-09-11",
    "idempotency_key": "upload-2026-09-11-01"
  }'

{
  "job_id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "part_urls": [
    { "n": 1, "url": "https://r2.hushscript.com/uploads/job_3a2b1c0d.../part-1?X-Amz-Signature=..." }
  ]
}

Esegui PUT di ogni parte sul suo URL prefirmato, poi esegui POST su /complete dello stesso job con n ed etag di ogni parte inviata in questo modo. Poi interroga periodicamente il job:

curl https://api.hushscript.com/v1/jobs/job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "job_3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d",
  "state": "done",
  "transcript_id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180"
}

curl https://api.hushscript.com/v1/transcripts/trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180 \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "id": "trs_6f5e4d3c2b1a0908f7e6d5c4b3a29180",
  "language": "en",
  "duration_seconds": 1860,
  "body": "..."
}

Ruota la credenziale

Un account macchina non ha password né una casella email utilizzabile, quindi non esiste un percorso di “password dimenticata” se un PAT trapela o deve semplicemente essere sostituito. La rotazione è quel percorso.

curl -X POST https://api.hushscript.com/v1/agent/credentials/rotate \
  -H "Authorization: Bearer hsr1:eu:pat.k3n2j1.8f7e6d5c4b3a29180716253443526170"

{
  "pat": "hsr1:eu:pat.p9q8r7.1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "pat_id": "p9q8r7",
  "scopes": [
    "transcripts:read",
    "transcripts:write",
    "transcribe",
    "account:read",
    "export",
    "billing",
    "pat:rotate"
  ],
  "expires_at": null
}

La chiamata non richiede un corpo. Genera atomicamente un successore e revoca il token che ha autenticato la richiesta, così il vecchio PAT fallisce già alla chiamata successiva effettuata con esso. Il successore mantiene gli scope, il permesso di fatturazione, il nome, l’etichetta client e la policy di scadenza del predecessore. Questa rotta tocca solo il token di chi chiama: non può elencare, generare o revocare nessun’altra credenziale sull’account. È l’unico percorso di recupero delle credenziali che un account macchina possiede, quindi ruota prima che il vecchio token venga scartato, non dopo.

Errori

Questi quattro sono specifici degli account agente e non vengono mai raggiunti da un account umano:

Una volta che il claim secret risulta valido, una Checkout Session non pagata risponde con wrong_state (4001) invece che con agent_claim_invalid. Il catalogo completo è il documento OpenAPI.

Limiti

Le chiamate sono limitate a 1.200 al minuto. Per un account agente quel budget appartiene all’account, non al singolo token: ogni credenziale nella catena di rotazione attinge dallo stesso budget, quindi ruotare un PAT non assegna al successore un’allocazione nuova. Le due scritture di fatturazione, salvare una carta e acquistare un pacchetto, condividono un limite più stretto di 60 al minuto per account, prima della chiamata a Stripe che entrambe effettuano. Il limite di acquisto di 24 ore visto sopra viene conteggiato allo stesso modo, per account e non per credenziale.

Per saperne di più

Questa pagina copre il ciclo di vita dell’account: aprirlo, finanziarlo e mantenerne viva la credenziale. Per tutto quello che l’account può fare in seguito, vedi la REST API, incluso il documento OpenAPI completo, oppure il server MCP per lo stesso account tramite strumenti invece che HTTP grezzo.