GroundTruth

Code Examples

Copy-paste examples for the GroundTruth API. Toggle between languages using the tabs.

Execute an Agent Action

Submit an intent to /api/execute — the core Execution OS endpoint. GroundTruth evaluates policies, verifies content against your knowledge base, and returns approved, blocked, or escalated.

curl -X POST https://your-domain.com/api/execute \
  -H "Authorization: Bearer hg_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send_email",
    "channel": "email",
    "params": {
      "to": "customer@example.com",
      "subject": "Your order has shipped",
      "body": "Hi Jane, your order #5678 has shipped and will arrive in 2-3 days."
    },
    "content": "Your order #5678 has shipped and will arrive in 2-3 days.",
    "context": {
      "agent": "my-assistant",
      "sessionId": "sess_abc123"
    }
  }'

Verify an AI Response

Use /api/check for standalone fact-checking — when you only need to verify content without routing an action. Returns a risk score, claim-level verdicts, and a safe rewrite.

curl -X POST https://your-domain.com/api/check \
  -H "Authorization: Bearer hg_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is your return policy?",
    "answer": "You can return items within 60 days for a full refund."
  }'

Ingest a Document

Add a document to your knowledge base via /api/documents. Documents are used by both the Execute API and the Verify API for content verification.

curl -X POST https://your-domain.com/api/documents \
  -H "Authorization: Bearer hg_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Return Policy",
    "content": "Items can be returned within 30 days for a full refund...",
    "source": "paste"
  }'

Code Examples

Execute an Agent Action

Verify an AI Response

Ingest a Document

Other ways to add documents