Appeler une action de l’Agentic API
Obtenez un jeton d’accès OAuth, trouvez une action dans le catalogue public et appelez-la sur POST /api/v1/actions/<id>.
Cas d'usageLa tâche
Vous voulez qu’un appelant automatique, agent ou script, utilise une capacité de Trustvice. Chaque capacité est une action enregistrée avec un identifiant stable, une entrée typée et la même enveloppe de réponse : une seule forme de requête les couvre toutes.
Avant de commencer
- Compte
- Un workspace Trustvice
- Identifiant
- Requis aussi
- Un client OAuth enregistré pour votre workspace (un identifiant
tvc_…et son secret) curl
- Un client OAuth enregistré pour votre workspace (un identifiant
Le code lit les secrets dans des variables d’environnement. Gardez-les dans votre shell ou votre coffre à secrets, jamais dans un fichier que vous committez. Les appels d’action envoient aussi X-Workspace-Id.
Étapes
Obtenir un jeton d’accès
Échangez l’identifiant et le secret de votre client OAuth contre un jeton d’accès avec
client_credentials. Le jeton vit une heure (expires_in: 3600) et porte le périmètre de permissions du client. Exportez-le sousTRUSTVICE_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": "…" }Trouver l’action
Le catalogue public des actions enregistrées est servi sur
GET /api/v1/actions, sans identifiant. Les identifiants d’action sont hiérarchiques :<domain>.<noun>.<verb>. La référence de l’API liste le schéma d’entrée et les permissions de chaque action.curlcurl -sS https://api.trustvice.com/api/v1/actionsL’appeler
Envoyez l’entrée de l’action en JSON à
POST /api/v1/actions/<action-id>, avec le jeton d’accès et l’identifiant de votre workspace. Les clés API de workspace sont refusées ici à dessein : une clé API donne accès au workspace, pas une intention d’agent.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… }Lire l’enveloppe
Lisez d’abord
ok. En cas de succès, la sortie est dansdata; en cas d’échec,errorporte uncodelisible par machine et une phrase pour les humains. Un404ou422métier est la réponse du produit, pas une erreur de transport.
Copié de: /docs/actions
Ce qui revient
Chaque action répond dans la même enveloppe : ok: true avec data, ou ok: false avec un code et un message dans error.
{ "ok": true, "data": { …action output… } }
{ "ok": false, "error": { "code": "not_found", "message": "No such export in this workspace." } }Ce sur quoi vous pouvez compter
Vous pouvez compter sur
- Un identifiant erroné ou absent reçoit un
401 unauthenticatednet, jamais une requête à moitié authentifiée. - Une permission manquante renvoie
403 permission_denieden nommant la permission exacte requise. - Une action se comporte de la même façon en REST, en MCP et via les transports d’agent skills.
Ne supposez pas
- Qu’une nouvelle tentative soit sûre : seules les actions marquées idempotentes acceptent l’en-tête
Idempotency-Key. - Que toute action s’exécute au premier appel : les actions destructives et de facturation répondent d’abord
412 confirmation_required.
Chaque affirmation ci-dessus vient des docs Trustvice liées sur cette page. Quand une page des docs en dit plus, c’est elle qui fait référence.
Et ensuite
Recettes liées
Confirmer une action destructive
Traitez 412 confirmation_required : obtenez un jeton de confirmation et rejouez l’appel avec X-Trustvice-Confirmation.
Connecter un client MCP
Ajoutez le serveur MCP de Trustvice sur https://mcp.trustvice.com/mcp à Claude Code, Cursor ou VS Code.
Vérifier un reçu dans le navigateur
Collez un reçu signé Trustvice dans /verify et vérifiez sa signature Ed25519 dans votre propre navigateur.
Les recettes par e-mail
Un court e-mail quand nous ajoutons des recettes. Rien d’autre, et désabonnement possible depuis chaque message.
Commencez par l’Agentic API.
Un endpoint POST par action enregistrée, avec le même comportement en REST et en MCP. Les docs listent chaque action avec son entrée et ses permissions.
