Eine Agentic-API-Aktion aufrufen

Ein OAuth-Access-Token ausstellen, eine Aktion im öffentlichen Katalog finden und sie unter POST /api/v1/actions/<id> aufrufen.

4 SchrittecurlHTTP

Einsatz

Aufgabe

Ein maschineller Aufrufer, ein Agent oder ein Skript, soll eine Fähigkeit von Trustvice nutzen. Jede Fähigkeit ist eine registrierte Aktion mit fester ID, typisierter Eingabe und demselben Antwort-Umschlag, daher deckt eine Anfrageform alle ab.

Voraussetzungen

Bevor Sie starten

Konto: Ein Trustvice-Workspace
Zugangsart: Ein OAuth-Access-Token
Außerdem nötig: Ein registrierter OAuth-Client für Ihren Workspace (eine tvc_…-ID und ihr Secret)
curl

Der Code liest Geheimnisse aus Umgebungsvariablen. Halten Sie sie in Shell oder Secret-Store, nie in einer committeten Datei. Aktionsaufrufe senden außerdem X-Workspace-Id.

Anleitung

Schritte

Access-Token ausstellen

Tauschen Sie ID und Secret Ihres OAuth-Clients per client_credentials gegen ein Access-Token. Das Token gilt eine Stunde (expires_in: 3600) und trägt den Berechtigungsumfang des Clients. Exportieren Sie es als 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": "…" }

Die Aktion finden
Der öffentliche Katalog der registrierten Aktionen liegt unter GET /api/v1/actions, ohne Zugang. Aktions-IDs sind hierarchisch: <domain>.<noun>.<verb>. Die API-Referenz listet Eingabeschema und Berechtigungen jeder Aktion.
curl
```
curl -sS https://api.trustvice.com/api/v1/actions
```

Aufrufen

Senden Sie die Eingabe der Aktion als JSON an POST /api/v1/actions/<action-id>, mit Access-Token und Workspace-ID. Workspace-API-Schlüssel werden hier bewusst abgelehnt: Ein API-Schlüssel gewährt Workspace-Zugriff, keine Agenten-Absicht.

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

Den Umschlag lesen
Lesen Sie zuerst ok. Bei Erfolg steht die Ausgabe in data; bei einem Fehler trägt error einen maschinenlesbaren code und einen Satz für Menschen. Ein fachliches 404 oder 422 ist die Antwort des Produkts, kein Transportfehler.

Kopiert aus: /docs/actions

Beispielausgabe

Was zurückkommt

Jede Aktion antwortet im selben Umschlag: ok: true mit data oder ok: false mit error-Code und Meldung.

JSON

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

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

Nachweis

Worauf Sie sich verlassen können

Darauf können Sie sich verlassen

Ein falscher oder fehlender Zugang erhält ein sauberes 401 unauthenticated, nie eine halb authentifizierte Anfrage.
Eine fehlende Berechtigung liefert 403 permission_denied und nennt genau die benötigte Berechtigung.
Eine Aktion verhält sich über REST, MCP und die Agent-Skill-Transporte gleich.

Nicht annehmen

Dass ein erneuter Versuch sicher ist: Nur als idempotent markierte Aktionen akzeptieren einen Idempotency-Key-Header.
Dass jede Aktion beim ersten Aufruf läuft: Destruktive und abrechnungsrelevante Aktionen antworten zuerst mit 412 confirmation_required.

Jede Aussage oben stammt aus den auf dieser Seite verlinkten Trustvice-Docs. Wo eine Docs-Seite mehr sagt, ist sie maßgeblich.

Weiter geht's

Wie weiter

Dokumentation

Eine destruktive Aktion bestätigen

412 confirmation_required behandeln: ein Bestätigungstoken ausstellen und den Aufruf mit X-Trustvice-Confirmation wiederholen.

4 Schrittecurl · HTTP

MCP-Clients

Einen MCP-Client verbinden

Den Trustvice-MCP-Server unter https://mcp.trustvice.com/mcp in Claude Code, Cursor oder VS Code hinzufügen.

2 SchritteClaude Code · Cursor · VS Code

Einen Beleg prüfen

Einen Beleg im Browser prüfen

Einen signierten Trustvice-Beleg in /verify einfügen und seine Ed25519-Signatur im eigenen Browser prüfen.

3 Schritte

Newsletter

Neue Rezepte

Neue Rezepte per Mail

Eine kurze E-Mail, wenn wir neue Rezepte ergänzen. Sonst keine Mail, und Sie melden sich aus jeder Nachricht ab.

Starten Sie mit der Agentic API.

Ein POST-Endpunkt pro registrierter Aktion, mit gleichem Verhalten über REST und MCP. Die Docs listen jede Aktion mit Eingabe und Berechtigungen.

Docs zu Aktionen lesen API-Referenz öffnen Einen Beleg prüfen →

Eine Agentic-API-Aktion aufrufen

Ein OAuth-Access-Token ausstellen, eine Aktion im öffentlichen Katalog finden und sie unter POST /api/v1/actions/<id> aufrufen.

4 SchrittecurlHTTP

Einsatz

Aufgabe

Voraussetzungen

Bevor Sie starten

Konto: Ein Trustvice-Workspace
Zugangsart: Ein OAuth-Access-Token
Außerdem nötig: Ein registrierter OAuth-Client für Ihren Workspace (eine tvc_…-ID und ihr Secret)
curl

Der Code liest Geheimnisse aus Umgebungsvariablen. Halten Sie sie in Shell oder Secret-Store, nie in einer committeten Datei. Aktionsaufrufe senden außerdem X-Workspace-Id.

Anleitung

Schritte

Access-Token ausstellen

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

Die Aktion finden
Der öffentliche Katalog der registrierten Aktionen liegt unter GET /api/v1/actions, ohne Zugang. Aktions-IDs sind hierarchisch: <domain>.<noun>.<verb>. Die API-Referenz listet Eingabeschema und Berechtigungen jeder Aktion.
curl
```
curl -sS https://api.trustvice.com/api/v1/actions
```

Aufrufen

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

Den Umschlag lesen
Lesen Sie zuerst ok. Bei Erfolg steht die Ausgabe in data; bei einem Fehler trägt error einen maschinenlesbaren code und einen Satz für Menschen. Ein fachliches 404 oder 422 ist die Antwort des Produkts, kein Transportfehler.

Kopiert aus: /docs/actions

Beispielausgabe

Was zurückkommt

Jede Aktion antwortet im selben Umschlag: ok: true mit data oder ok: false mit error-Code und Meldung.

JSON

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

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

Nachweis

Worauf Sie sich verlassen können

Darauf können Sie sich verlassen

Ein falscher oder fehlender Zugang erhält ein sauberes 401 unauthenticated, nie eine halb authentifizierte Anfrage.
Eine fehlende Berechtigung liefert 403 permission_denied und nennt genau die benötigte Berechtigung.
Eine Aktion verhält sich über REST, MCP und die Agent-Skill-Transporte gleich.

Nicht annehmen

Dass ein erneuter Versuch sicher ist: Nur als idempotent markierte Aktionen akzeptieren einen Idempotency-Key-Header.
Dass jede Aktion beim ersten Aufruf läuft: Destruktive und abrechnungsrelevante Aktionen antworten zuerst mit 412 confirmation_required.

Jede Aussage oben stammt aus den auf dieser Seite verlinkten Trustvice-Docs. Wo eine Docs-Seite mehr sagt, ist sie maßgeblich.

Weiter geht's

Wie weiter

Dokumentation

Eine destruktive Aktion bestätigen

412 confirmation_required behandeln: ein Bestätigungstoken ausstellen und den Aufruf mit X-Trustvice-Confirmation wiederholen.

4 Schrittecurl · HTTP

MCP-Clients

Einen MCP-Client verbinden

Den Trustvice-MCP-Server unter https://mcp.trustvice.com/mcp in Claude Code, Cursor oder VS Code hinzufügen.

2 SchritteClaude Code · Cursor · VS Code

Einen Beleg prüfen

Einen Beleg im Browser prüfen

Einen signierten Trustvice-Beleg in /verify einfügen und seine Ed25519-Signatur im eigenen Browser prüfen.

3 Schritte

Newsletter

Neue Rezepte

Neue Rezepte per Mail

Eine kurze E-Mail, wenn wir neue Rezepte ergänzen. Sonst keine Mail, und Sie melden sich aus jeder Nachricht ab.

Starten Sie mit der Agentic API.

Ein POST-Endpunkt pro registrierter Aktion, mit gleichem Verhalten über REST und MCP. Die Docs listen jede Aktion mit Eingabe und Berechtigungen.

Docs zu Aktionen lesen API-Referenz öffnen Einen Beleg prüfen →

Eine Agentic-API-Aktion aufrufen

Aufgabe

Bevor Sie starten

Schritte

Access-Token ausstellen

Die Aktion finden

Aufrufen

Den Umschlag lesen

Was zurückkommt

Worauf Sie sich verlassen können

✓Darauf können Sie sich verlassen

×Nicht annehmen

Wie weiter

Dokumentation

Verwandte Rezepte

Eine destruktive Aktion bestätigen

Einen MCP-Client verbinden

Einen Beleg im Browser prüfen

Neue Rezepte per Mail

Starten Sie mit der Agentic API.

Regeln festlegen. Jeden Lauf prüfen lassen.

Eine Agentic-API-Aktion aufrufen

Aufgabe

Bevor Sie starten

Schritte

Access-Token ausstellen

Die Aktion finden

Aufrufen

Den Umschlag lesen

Was zurückkommt

Worauf Sie sich verlassen können

✓Darauf können Sie sich verlassen

×Nicht annehmen

Wie weiter

Dokumentation

Verwandte Rezepte

Eine destruktive Aktion bestätigen

Einen MCP-Client verbinden

Einen Beleg im Browser prüfen

Neue Rezepte per Mail

Starten Sie mit der Agentic API.

Regeln festlegen. Jeden Lauf prüfen lassen.

Darauf können Sie sich verlassen

Nicht annehmen

Darauf können Sie sich verlassen

Nicht annehmen