Chiamare un’azione dell’Agentic API

Ottieni un token di accesso OAuth, trova un’azione nel catalogo pubblico e chiamala su POST /api/v1/actions/<id>.

4 passicurlHTTP

Caso d'uso

Il compito

Vuoi che un chiamante automatico, un agente o uno script, usi una funzionalità di Trustvice. Ogni funzionalità è un’azione registrata con un id stabile, un input tipizzato e la stessa busta di risposta, quindi un’unica forma di richiesta vale per tutte.

Prerequisiti

Prima di iniziare

Account: Un workspace Trustvice
Credenziale: Un token di accesso OAuth
Ti serve anche: Un client OAuth registrato per il tuo workspace (un id tvc_… e il suo segreto)
curl

Il codice legge i segreti da variabili d’ambiente. Tienili nella shell o nel gestore di segreti, mai in un file che finisce in un commit. Le chiamate alle azioni inviano anche X-Workspace-Id.

Passo passo

Passi

Ottieni un token di accesso

Scambia id e segreto del tuo client OAuth con un token di accesso tramite client_credentials. Il token vale un’ora (expires_in: 3600) e porta l’ambito di permessi del client. Esportalo come TRUSTVICE_TOKEN.

curl -sS -X POST https://api.trustvice.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"tvc_…\",\"client_secret\":\"$TRUSTVICE_CLIENT_SECRET\"}"

POST /api/v1/oauth/token
{ "grant_type": "client_credentials",
  "client_id": "tvc_…", "client_secret": "…" }

Trova l’azione
Il catalogo pubblico delle azioni registrate è servito su GET /api/v1/actions, senza credenziali. Gli id delle azioni sono gerarchici: <domain>.<noun>.<verb>. Il riferimento API elenca schema di input e permessi di ogni azione.
curl
```
curl -sS https://api.trustvice.com/api/v1/actions
```

Chiamala

Invia l’input dell’azione come JSON a POST /api/v1/actions/<action-id>, con il token di accesso e l’id del tuo workspace. Le chiavi API di workspace qui vengono rifiutate di proposito: una chiave API dà accesso al workspace, non un’intenzione di agente.

curl -sS -X POST https://api.trustvice.com/api/v1/actions/<action-id> \
  -H "Authorization: Bearer $TRUSTVICE_TOKEN" \
  -H "X-Workspace-Id: ws_…" \
  -H "Content-Type: application/json" \
  -d '{ … }'

POST /api/v1/actions/<action-id>
Authorization: Bearer <oauth-access-token>
X-Workspace-Id: ws_…
Content-Type: application/json

{ …input fields… }

Leggi la busta
Leggi prima ok. In caso di successo l’output è in data; in caso di errore error porta un code leggibile dalla macchina e una frase per le persone. Un 404 o 422 di dominio è il prodotto che risponde, non un errore di trasporto.

Copiato da: /docs/actions

Esempio output

Cosa ritorna

Ogni azione risponde con la stessa busta: ok: true con data, oppure ok: false con codice e messaggio in error.

JSON

{ "ok": true, "data": { …action output… } }

{ "ok": false, "error": { "code": "not_found", "message": "No such export in this workspace." } }

Prove

Su cosa puoi contare

Puoi contare su

Una credenziale sbagliata o assente riceve un 401 unauthenticated netto, mai una richiesta autenticata a metà.
Un permesso mancante restituisce 403 permission_denied con il nome esatto del permesso richiesto.
Un’azione si comporta allo stesso modo via REST, MCP e i trasporti delle agent skill.

Non dare per scontato

Che riprovare sia sicuro: solo le azioni marcate come idempotenti accettano l’header Idempotency-Key.
Che ogni azione parta alla prima chiamata: le azioni distruttive e di fatturazione rispondono prima 412 confirmation_required.

Ogni affermazione qui sopra viene dalle docs di Trustvice collegate in questa pagina. Dove una pagina delle docs dice di più, fa testo quella.

Continua

Prosegui

Documentazione

Ricette correlate

Conferme e agenti

Confermare un’azione distruttiva

Gestisci 412 confirmation_required: ottieni un token di conferma e ripeti la chiamata con X-Trustvice-Confirmation.

4 passicurl · HTTP

Client MCP

Collegare un client MCP

Aggiungi il server MCP di Trustvice su https://mcp.trustvice.com/mcp a Claude Code, Cursor o VS Code.

2 passiClaude Code · Cursor · VS Code

Verifica ricevuta

Verificare una ricevuta nel browser

Incolla una ricevuta firmata Trustvice in /verify e controlla la sua firma Ed25519 nel tuo browser.

3 passi

Newsletter

Nuove ricette

Nuove ricette via email

Una breve email quando aggiungiamo ricette. Nessun’altra posta, e ti disiscrivi da ogni messaggio.

Inizia dall’Agentic API.

Un endpoint POST per ogni azione registrata, con lo stesso comportamento via REST e MCP. Le docs elencano ogni azione con input e permessi.

Leggi le docs sulle azioni Apri il riferimento API Verifica ricevuta →

Chiamare un’azione dell’Agentic API

Ottieni un token di accesso OAuth, trova un’azione nel catalogo pubblico e chiamala su POST /api/v1/actions/<id>.

4 passicurlHTTP

Caso d'uso

Il compito

Prerequisiti

Prima di iniziare

Account: Un workspace Trustvice
Credenziale: Un token di accesso OAuth
Ti serve anche: Un client OAuth registrato per il tuo workspace (un id tvc_… e il suo segreto)
curl

Il codice legge i segreti da variabili d’ambiente. Tienili nella shell o nel gestore di segreti, mai in un file che finisce in un commit. Le chiamate alle azioni inviano anche X-Workspace-Id.

Passo passo

Passi

Ottieni un token di accesso

curl -sS -X POST https://api.trustvice.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"tvc_…\",\"client_secret\":\"$TRUSTVICE_CLIENT_SECRET\"}"

POST /api/v1/oauth/token
{ "grant_type": "client_credentials",
  "client_id": "tvc_…", "client_secret": "…" }

Trova l’azione
Il catalogo pubblico delle azioni registrate è servito su GET /api/v1/actions, senza credenziali. Gli id delle azioni sono gerarchici: <domain>.<noun>.<verb>. Il riferimento API elenca schema di input e permessi di ogni azione.
curl
```
curl -sS https://api.trustvice.com/api/v1/actions
```

Chiamala

curl -sS -X POST https://api.trustvice.com/api/v1/actions/<action-id> \
  -H "Authorization: Bearer $TRUSTVICE_TOKEN" \
  -H "X-Workspace-Id: ws_…" \
  -H "Content-Type: application/json" \
  -d '{ … }'

POST /api/v1/actions/<action-id>
Authorization: Bearer <oauth-access-token>
X-Workspace-Id: ws_…
Content-Type: application/json

{ …input fields… }

Leggi la busta
Leggi prima ok. In caso di successo l’output è in data; in caso di errore error porta un code leggibile dalla macchina e una frase per le persone. Un 404 o 422 di dominio è il prodotto che risponde, non un errore di trasporto.

Copiato da: /docs/actions

Esempio output

Cosa ritorna

Ogni azione risponde con la stessa busta: ok: true con data, oppure ok: false con codice e messaggio in error.

JSON

{ "ok": true, "data": { …action output… } }

{ "ok": false, "error": { "code": "not_found", "message": "No such export in this workspace." } }

Prove

Su cosa puoi contare

Puoi contare su

Una credenziale sbagliata o assente riceve un 401 unauthenticated netto, mai una richiesta autenticata a metà.
Un permesso mancante restituisce 403 permission_denied con il nome esatto del permesso richiesto.
Un’azione si comporta allo stesso modo via REST, MCP e i trasporti delle agent skill.

Non dare per scontato

Che riprovare sia sicuro: solo le azioni marcate come idempotenti accettano l’header Idempotency-Key.
Che ogni azione parta alla prima chiamata: le azioni distruttive e di fatturazione rispondono prima 412 confirmation_required.

Ogni affermazione qui sopra viene dalle docs di Trustvice collegate in questa pagina. Dove una pagina delle docs dice di più, fa testo quella.

Continua

Prosegui

Documentazione

Ricette correlate

Conferme e agenti

Confermare un’azione distruttiva

Gestisci 412 confirmation_required: ottieni un token di conferma e ripeti la chiamata con X-Trustvice-Confirmation.

4 passicurl · HTTP

Client MCP

Collegare un client MCP

Aggiungi il server MCP di Trustvice su https://mcp.trustvice.com/mcp a Claude Code, Cursor o VS Code.

2 passiClaude Code · Cursor · VS Code

Verifica ricevuta

Verificare una ricevuta nel browser

Incolla una ricevuta firmata Trustvice in /verify e controlla la sua firma Ed25519 nel tuo browser.

3 passi

Newsletter

Nuove ricette

Nuove ricette via email

Una breve email quando aggiungiamo ricette. Nessun’altra posta, e ti disiscrivi da ogni messaggio.

Inizia dall’Agentic API.

Un endpoint POST per ogni azione registrata, con lo stesso comportamento via REST e MCP. Le docs elencano ogni azione con input e permessi.

Leggi le docs sulle azioni Apri il riferimento API Verifica ricevuta →

Chiamare un’azione dell’Agentic API

Il compito

Prima di iniziare

Passi

Ottieni un token di accesso

Trova l’azione

Chiamala

Leggi la busta

Cosa ritorna

Su cosa puoi contare

✓Puoi contare su

×Non dare per scontato

Prosegui

Documentazione

Ricette correlate

Confermare un’azione distruttiva

Collegare un client MCP

Verificare una ricevuta nel browser

Nuove ricette via email

Inizia dall’Agentic API.

Dichiara le regole. Fai controllare ogni esecuzione.

Chiamare un’azione dell’Agentic API

Il compito

Prima di iniziare

Passi

Ottieni un token di accesso

Trova l’azione

Chiamala

Leggi la busta

Cosa ritorna

Su cosa puoi contare

✓Puoi contare su

×Non dare per scontato

Prosegui

Documentazione

Ricette correlate

Confermare un’azione distruttiva

Collegare un client MCP

Verificare una ricevuta nel browser

Nuove ricette via email

Inizia dall’Agentic API.

Dichiara le regole. Fai controllare ogni esecuzione.

Puoi contare su

Non dare per scontato

Puoi contare su

Non dare per scontato