GroundTruth

Execution OS

POST /api/execute

The execute endpoint is the control plane for AI agents. Instead of letting agents call external systems directly, they submit intents — structured descriptions of what they want to do. GroundTruth evaluates each intent against your policies, optionally verifies the content against your knowledge base, and decides whether to approve, block, or escalate the action for human review.

How it works

Agent sends an intent to POST /api/execute
If the intent has content, it is verified against your knowledge base
All enabled policies are evaluated against the intent
Decision: approve → execute via connector, block → reject, escalate → queue for human
Every intent is logged in the Execution Log for audit

Request Body

Field	Type	Required	Description
action	string	Yes	The action type, e.g. "send_email", "reply_ticket", "send_message", "send_webhook"
channel	string	No	Channel identifier, e.g. "slack", "whatsapp", "zendesk", "email"
params	object	No	Action-specific parameters (e.g. ticket_id, to, subject, body)
content	string	No	Text content to verify against your knowledge base before executing
context.agent	string	No	Agent identifier, e.g. "my-assistant", "crewai"
context.sessionId	string	No	Session or conversation ID for tracing
context.userId	string	No	Who the agent is acting on behalf of

Response

Field	Type	Description
executionId	string	Unique ID for this execution, e.g. exec_a1b2c3...
decision	string	"approved", "blocked", or "escalated"
riskScore	number	Content risk score 0-1 (only if content was verified)
matchedPolicies	string[]	Names of policies that matched this intent
result	object	Connector execution result (only if approved and connector exists)
safeRewrite	string	Corrected content if KB verification found issues
message	string	Human-readable message (only for escalated actions)

Examples

1. Simple action (no content verification)

Send a message via Slack. No content is verified — only policies are checked.

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_message",
    "channel": "slack",
    "params": {
      "to": "#customer-support",
      "text": "Ticket #1234 has been resolved"
    },
    "context": {
      "agent": "my-assistant",
      "sessionId": "sess_abc123"
    }
  }'

Response:

json

{
  "executionId": "exec_a1b2c3d4e5f6",
  "decision": "approved",
  "riskScore": 0,
  "matchedPolicies": [],
  "result": {
    "success": true,
    "note": "No connector — agent executes"
  }
}

2. Reply to a Zendesk ticket with content verification

The content field triggers KB verification. If your Zendesk integration is connected, the reply is sent automatically on approval.

curl

curl -X POST https://your-domain.com/api/execute \
  -H "Authorization: Bearer hg_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "reply_ticket",
    "channel": "zendesk",
    "params": {
      "ticket_id": "48291",
      "body": "Your refund of $150 has been processed and will appear in 3-5 business days."
    },
    "content": "Your refund of $150 has been processed and will appear in 3-5 business days.",
    "context": {
      "agent": "my-assistant",
      "userId": "user_jane"
    }
  }'

If content passes verification and no policies block it:

json

{
  "executionId": "exec_x7y8z9w0",
  "decision": "approved",
  "riskScore": 0.12,
  "matchedPolicies": [],
  "result": {
    "success": true,
    "data": { "ticketId": "48291", "auditId": "98765" }
  }
}

3. Blocked by policy

If you have a policy "Block high risk actions" with condition risk_score above 0.7, and the content fails verification:

json

{
  "executionId": "exec_blocked123",
  "decision": "blocked",
  "riskScore": 0.85,
  "matchedPolicies": ["Block high risk actions"]
}

4. Escalated for human review

If a policy escalates the action, it is queued in the Approvals page for a human to approve or reject.

json

{
  "executionId": "exec_escalated456",
  "decision": "escalated",
  "riskScore": 0.55,
  "matchedPolicies": ["Escalate external emails"],
  "message": "Action requires human approval"
}

5. Send an email

Uses the built-in Resend connector to send email. Requires RESEND_API_KEY to be configured.

curl

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" }
  }'

6. Fire a webhook

Send a POST to your org's configured webhook URL or a custom URL.

curl

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_webhook",
    "params": {
      "use_org_webhook": true,
      "payload": {
        "event": "ticket_resolved",
        "ticket_id": "48291",
        "resolution": "Refund issued"
      }
    },
    "context": { "agent": "my-assistant" }
  }'

Built-in Connectors

When an intent is approved, GroundTruth can automatically execute it via a built-in connector. If no connector matches the action, the intent is approved but not executed — the agent handles execution itself.

Action	Connector	Required Params
reply_ticket	Zendesk	ticket_id, body
send_email	Resend	to, subject, body
send_webhook	Webhook	url or use_org_webhook, payload

Any other action (e.g. send_message, browse_url, run_command) is still evaluated by policies and logged, but execution is left to the calling agent.

Execution Log

Every intent is logged in the Executions dashboard. You can also query them via API:

curl

# List recent executions
curl https://your-domain.com/api/executions \
  -H "Authorization: Bearer hg_sk_your_api_key"

# Get a specific execution
curl https://your-domain.com/api/executions/exec_a1b2c3d4e5f6 \
  -H "Authorization: Bearer hg_sk_your_api_key"