Chamar uma ação da Agentic API

Emita um token de acesso OAuth, encontre uma ação no catálogo público e chame-a em POST /api/v1/actions/<id>.

4 passoscurlHTTP

Caso de uso

A tarefa

Você quer que um chamador automático, um agente ou um script, use uma capacidade da Trustvice. Cada capacidade é uma ação registrada com um id estável, uma entrada tipada e o mesmo envelope de resposta, então um só formato de requisição serve para todas.

Pré-requisitos

Antes de começar

Conta: Um workspace da Trustvice
Credencial: Um token de acesso OAuth
Também precisa: Um cliente OAuth registrado para o seu workspace (um id tvc_… e o seu segredo)
curl

O código lê os segredos de variáveis de ambiente. Guarde-os no shell ou no cofre de segredos, nunca num arquivo que vai para commit. As chamadas de ação também enviam X-Workspace-Id.

Passo a passo

Passos

Emita um token de acesso

Troque o id e o segredo do seu cliente OAuth por um token de acesso com client_credentials. O token dura uma hora (expires_in: 3600) e carrega o escopo de permissões do cliente. Exporte-o como 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": "…" }

Encontre a ação
O catálogo público de ações registradas fica em GET /api/v1/actions, sem credencial. Os ids de ação são hierárquicos: <domain>.<noun>.<verb>. A referência da API lista o esquema de entrada e as permissões de cada ação.
curl
```
curl -sS https://api.trustvice.com/api/v1/actions
```

Chame

Envie a entrada da ação como JSON para POST /api/v1/actions/<action-id>, com o token de acesso e o id do seu workspace. Chaves de API de workspace são recusadas aqui de propósito: uma chave de API dá acesso ao workspace, não intenção 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… }

Leia o envelope
Leia ok primeiro. Em caso de sucesso, a saída está em data; em caso de falha, error traz um code legível por máquina e uma frase para pessoas. Um 404 ou 422 de domínio é o produto respondendo, não um erro de transporte.

Copiado de: /docs/actions

Saída de exemplo

O que é devolvido

Toda ação responde no mesmo envelope: ok: true com data, ou ok: false com código e mensagem em error.

JSON

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

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

Evidências

Em que você pode confiar

Você pode confiar em

Uma credencial errada ou ausente recebe um 401 unauthenticated limpo, nunca uma requisição meio autenticada.
Uma permissão ausente retorna 403 permission_denied, com o nome exato da permissão exigida.
Uma ação se comporta igual via REST, MCP e os transportes de agent skills.

Não presuma

Que repetir seja seguro: só ações marcadas como idempotentes aceitam o cabeçalho Idempotency-Key.
Que toda ação rode na primeira chamada: ações destrutivas e de cobrança respondem antes com 412 confirmation_required.

Cada afirmação acima vem das docs da Trustvice linkadas nesta página. Onde uma página das docs diz mais, ela é a referência.

Continue

A seguir

Documentação

Receitas ligadas

Confirmações e agentes

Confirmar uma ação destrutiva

Trate 412 confirmation_required: emita um token de confirmação e repita a chamada com X-Trustvice-Confirmation.

4 passoscurl · HTTP

Clientes MCP

Conectar um cliente MCP

Adicione o servidor MCP da Trustvice em https://mcp.trustvice.com/mcp ao Claude Code, Cursor ou VS Code.

2 passosClaude Code · Cursor · VS Code

Verificar um recibo

Verificar um recibo no navegador

Cole um recibo assinado da Trustvice em /verify e confira a assinatura Ed25519 no seu próprio navegador.

3 passos

Newsletter

Novas receitas

Receitas por e-mail

Um e-mail curto quando somamos receitas. Nenhum outro e-mail, e você cancela por qualquer mensagem.

Comece pela Agentic API.

Um endpoint POST por ação registrada, com o mesmo comportamento via REST e MCP. As docs listam cada ação com sua entrada e permissões.

Ler as docs de ações Abrir a referência da API Verificar um recibo →

Chamar uma ação da Agentic API

Emita um token de acesso OAuth, encontre uma ação no catálogo público e chame-a em POST /api/v1/actions/<id>.

4 passoscurlHTTP

Caso de uso

A tarefa

Pré-requisitos

Antes de começar

Conta: Um workspace da Trustvice
Credencial: Um token de acesso OAuth
Também precisa: Um cliente OAuth registrado para o seu workspace (um id tvc_… e o seu segredo)
curl

O código lê os segredos de variáveis de ambiente. Guarde-os no shell ou no cofre de segredos, nunca num arquivo que vai para commit. As chamadas de ação também enviam X-Workspace-Id.

Passo a passo

Passos

Emita um token de acesso

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": "…" }

Encontre a ação
O catálogo público de ações registradas fica em GET /api/v1/actions, sem credencial. Os ids de ação são hierárquicos: <domain>.<noun>.<verb>. A referência da API lista o esquema de entrada e as permissões de cada ação.
curl
```
curl -sS https://api.trustvice.com/api/v1/actions
```

Chame

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… }

Leia o envelope
Leia ok primeiro. Em caso de sucesso, a saída está em data; em caso de falha, error traz um code legível por máquina e uma frase para pessoas. Um 404 ou 422 de domínio é o produto respondendo, não um erro de transporte.

Copiado de: /docs/actions

Saída de exemplo

O que é devolvido

Toda ação responde no mesmo envelope: ok: true com data, ou ok: false com código e mensagem em error.

JSON

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

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

Evidências

Em que você pode confiar

Você pode confiar em

Uma credencial errada ou ausente recebe um 401 unauthenticated limpo, nunca uma requisição meio autenticada.
Uma permissão ausente retorna 403 permission_denied, com o nome exato da permissão exigida.
Uma ação se comporta igual via REST, MCP e os transportes de agent skills.

Não presuma

Que repetir seja seguro: só ações marcadas como idempotentes aceitam o cabeçalho Idempotency-Key.
Que toda ação rode na primeira chamada: ações destrutivas e de cobrança respondem antes com 412 confirmation_required.

Cada afirmação acima vem das docs da Trustvice linkadas nesta página. Onde uma página das docs diz mais, ela é a referência.

Continue

A seguir

Documentação

Receitas ligadas

Confirmações e agentes

Confirmar uma ação destrutiva

Trate 412 confirmation_required: emita um token de confirmação e repita a chamada com X-Trustvice-Confirmation.

4 passoscurl · HTTP

Clientes MCP

Conectar um cliente MCP

Adicione o servidor MCP da Trustvice em https://mcp.trustvice.com/mcp ao Claude Code, Cursor ou VS Code.

2 passosClaude Code · Cursor · VS Code

Verificar um recibo

Verificar um recibo no navegador

Cole um recibo assinado da Trustvice em /verify e confira a assinatura Ed25519 no seu próprio navegador.

3 passos

Newsletter

Novas receitas

Receitas por e-mail

Um e-mail curto quando somamos receitas. Nenhum outro e-mail, e você cancela por qualquer mensagem.

Comece pela Agentic API.

Um endpoint POST por ação registrada, com o mesmo comportamento via REST e MCP. As docs listam cada ação com sua entrada e permissões.

Ler as docs de ações Abrir a referência da API Verificar um recibo →

Chamar uma ação da Agentic API

A tarefa

Antes de começar

Passos

Emita um token de acesso

Encontre a ação

Chame

Leia o envelope

O que é devolvido

Em que você pode confiar

✓Você pode confiar em

×Não presuma

A seguir

Documentação

Receitas ligadas

Confirmar uma ação destrutiva

Conectar um cliente MCP

Verificar um recibo no navegador

Receitas por e-mail

Comece pela Agentic API.

Declare as regras. Deixe cada execução ser verificada.

Chamar uma ação da Agentic API

A tarefa

Antes de começar

Passos

Emita um token de acesso

Encontre a ação

Chame

Leia o envelope

O que é devolvido

Em que você pode confiar

✓Você pode confiar em

×Não presuma

A seguir

Documentação

Receitas ligadas

Confirmar uma ação destrutiva

Conectar um cliente MCP

Verificar um recibo no navegador

Receitas por e-mail

Comece pela Agentic API.

Declare as regras. Deixe cada execução ser verificada.

Você pode confiar em

Não presuma

Você pode confiar em

Não presuma