Call an Agentic API action
Mint an OAuth access token, find an action in the public catalogue and call it at POST /api/v1/actions/<id>.
Use caseThe job
You want a machine caller, an agent or a script, to use one Trustvice capability. Every capability is a registered action with a stable id, a typed input and the same response envelope, so one request shape covers all of them.
Before you start
- Account
- A Trustvice workspace
- Credential
- You also need
- A registered OAuth client for your workspace (a
tvc_…id and its secret) curl
- A registered OAuth client for your workspace (a
The code reads secrets from environment variables. Keep them in your shell or your secret store, never in a file you commit. Action calls also send X-Workspace-Id.
Steps
Mint an access token
Exchange your OAuth client's id and secret for an access token with
client_credentials. The token lives for one hour (expires_in: 3600) and carries the client's permission scope. Export it asTRUSTVICE_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": "…" }Find the action
The public catalogue of registered actions is served at
GET /api/v1/actions, without a credential. Action ids are hierarchical:<domain>.<noun>.<verb>. The API reference lists every action's input schema and permissions.curlcurl -sS https://api.trustvice.com/api/v1/actionsCall it
Send the action's input as JSON to
POST /api/v1/actions/<action-id>, with the access token and your workspace id. Workspace API keys are rejected here by design: an API key grants workspace access, not agent intent.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… }Read the envelope
Read
okfirst. On success the output is indata; on failureerrorcarries a machine-readablecodeand a human sentence. A domain404or422is the product answering, not a transport error.
Copied from: /docs/actions
What comes back
Every action answers in the same envelope: ok: true with data, or ok: false with an error code and message.
{ "ok": true, "data": { …action output… } }
{ "ok": false, "error": { "code": "not_found", "message": "No such export in this workspace." } }What you can rely on
You can rely on
- A wrong or missing credential gets a clean
401 unauthenticated, never a half-authenticated request. - A missing permission returns
403 permission_denied, naming the exact permission that was required. - An action behaves the same over REST, MCP and the agent-skill transports.
Do not assume
- That a retry is safe: only actions marked idempotent accept an
Idempotency-Keyheader. - That every action runs on the first call: destructive and billing actions answer
412 confirmation_requiredfirst.
Every statement above comes from the Trustvice docs linked on this page. Where a docs page says more, it is the reference.
Next steps
Related recipes
Confirm a destructive action
Handle 412 confirmation_required: mint a confirmation token and replay the call with X-Trustvice-Confirmation.
Connect an MCP client
Add the Trustvice MCP server at https://mcp.trustvice.com/mcp to Claude Code, Cursor or VS Code.
Verify a receipt in the browser
Paste a Trustvice signed receipt into /verify and check its Ed25519 signature in your own browser.
New recipes by email
One short email when we add recipes to the cookbook. No other mail, and you can unsubscribe from any message.
Start with the Agentic API.
One POST endpoint per registered action, with the same behaviour over REST and MCP. The docs list every action with its input and permissions.
