Llamar a una acción de la Agentic API
Emite un token de acceso OAuth, busca una acción en el catálogo público y llámala en POST /api/v1/actions/<id>.
Caso de usoLa tarea
Quieres que un llamador automático, un agente o un script, use una capacidad de Trustvice. Cada capacidad es una acción registrada con un id estable, una entrada tipada y el mismo sobre de respuesta, así que una sola forma de petición sirve para todas.
Antes de empezar
- Credencial
- Necesitarás
- Un cliente OAuth registrado para tu workspace (un id
tvc_…y su secreto) curl
- Un cliente OAuth registrado para tu workspace (un id
El código lee los secretos de variables de entorno. Guárdalos en tu shell o en tu gestor de secretos, nunca en un archivo que subas. Las llamadas a acciones también envían X-Workspace-Id.
Pasos
Emite un token de acceso
Cambia el id y el secreto de tu cliente OAuth por un token de acceso con
client_credentials. El token dura una hora (expires_in: 3600) y lleva el alcance de permisos del cliente. Expórtalo comoTRUSTVICE_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": "…" }Busca la acción
El catálogo público de acciones registradas se sirve en
GET /api/v1/actions, sin credencial. Los ids de acción son jerárquicos:<domain>.<noun>.<verb>. La referencia de la API lista el esquema de entrada y los permisos de cada acción.curlcurl -sS https://api.trustvice.com/api/v1/actionsLlámala
Envía la entrada de la acción como JSON a
POST /api/v1/actions/<action-id>, con el token de acceso y el id de tu workspace. Las claves API de workspace se rechazan aquí a propósito: una clave API da acceso al workspace, no intención de 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… }Lee el sobre
Lee primero
ok. Si todo va bien, la salida está endata; si falla,errortrae uncodelegible por máquina y una frase para personas. Un404o422de dominio es el producto respondiendo, no un error de transporte.
Copiado de: /docs/actions
Qué se devuelve
Todas las acciones responden con el mismo sobre: ok: true con data, o ok: false con un código y un mensaje en error.
{ "ok": true, "data": { …action output… } }
{ "ok": false, "error": { "code": "not_found", "message": "No such export in this workspace." } }En qué puedes confiar
Puedes confiar en
- Una credencial incorrecta o ausente recibe un
401 unauthenticatedlimpio, nunca una petición a medio autenticar. - Si falta un permiso, se devuelve
403 permission_deniedcon el permiso exacto que se requería. - Una acción se comporta igual por REST, MCP y los transportes de agent skills.
No des por hecho
- Que reintentar sea seguro: solo las acciones marcadas como idempotentes aceptan la cabecera
Idempotency-Key. - Que toda acción se ejecute a la primera: las acciones destructivas y de facturación responden antes con
412 confirmation_required.
Todo lo anterior procede de las docs de Trustvice enlazadas en esta página. Donde una página de las docs dice más, esa es la referencia.
Después
Recetas afines
Confirmar una acción destructiva
Gestiona 412 confirmation_required: emite un token de confirmación y repite la llamada con X-Trustvice-Confirmation.
Conectar un cliente MCP
Añade el servidor MCP de Trustvice en https://mcp.trustvice.com/mcp a Claude Code, Cursor o VS Code.
Verificar un recibo en el navegador
Pega un recibo firmado de Trustvice en /verify y comprueba su firma Ed25519 en tu propio navegador.
Recetas por email
Un email breve cuando añadimos recetas. Ningún otro correo, y puedes darte de baja desde cualquier mensaje.
Empieza con la Agentic API.
Un endpoint POST por cada acción registrada, con el mismo comportamiento por REST y por MCP. Las docs listan cada acción con su entrada y sus permisos.
