Using the Safety Gate via HTTP (No n8n Required)

[← Back to Docs](/docs)

This page is the primary reference for integrating AI Safety Gate into any app.

All examples use the production base URL:

https://aisafegate.com

Observability & health

• Health endpoints for uptime checks:

- GET https://aisafegate.com/api/health/app

- GET https://aisafegate.com/api/health/safety-gate

• If the API is unavailable or returns an error, integrations must fail closed (do not execute).

API reference (copy/paste)

`POST https://aisafegate.com/api/validate`

**Purpose**

Validate AI output (and its context) before you execute a real-world action.

**Action contract enforcement (deterministic)**

action_type is not free-form. The only authoritative source for allowed action_type values is PUBLIC_ACTION_CATALOG (via listAllowedActionTypes(action_kind)).

If action_type is not allowed for the given action_kind, the validator returns a deterministic BLOCK with this exact reason format:

BLOCK: Unknown action_type for action_kind {action_kind}. Supported action_type values: {comma-separated list}.

**Request (curl)**

curl -X POST "https://aisafegate.com/api/validate" \
  -H "Authorization: Bearer REPLACE_ME" \
  -H "Content-Type: application/json" \
  -d '{
    "action_kind": "messaging.send",
    "action_type": "send",
    "ai_output": {
      "to": "user_789",
      "channel": "email",
      "subject": "Refund confirmation",
      "body": "Your refund has been processed."
    },
    "context": {
      "workflow": "send_refund_confirmation",
      "workflowName": "Send Refund Confirmation",
      "system_instructions": "Send only to the intended recipient. Do not include secrets.",
      "user_input": "Send a refund confirmation email to user_789.",

**Responses (examples)**

PASS:

{
  "status": "PASS"
}

WARN (requires approval polling):

{
  "status": "WARN",
  "decision_id": "dec_123",
  "approval_token": "appr_abc"
}

BLOCK:

{
  "status": "BLOCK"
}

**What to do next**

• If PASS, execution is allowed.
• If WARN, you must pause and poll approval (see below). Do not execute unless you receive { "approved": true }.
• If BLOCK, do not execute the downstream action.
• If the API request fails, fail closed (treat as not approved / do not execute).

`GET https://aisafegate.com/api/decisions/{decision_id}/approval`

**Purpose**

Check whether a WARN decision has been approved.

**Request (curl)**

Approval polling supports either:

• The approval_token from the WARN response (via X-Approval-Token or Authorization: Bearer), or
• Your API key (via Authorization: Bearer)

# Option A (recommended): provide approval token as a header
curl "https://aisafegate.com/api/decisions/dec_123/approval" \
  -H "X-Approval-Token: appr_abc"

# Option B: provide approval token as the Bearer token
curl "https://aisafegate.com/api/decisions/dec_123/approval" \
  -H "Authorization: Bearer appr_abc"

# Option C: provide your API key as the Bearer token
curl "https://aisafegate.com/api/decisions/dec_123/approval" \
  -H "Authorization: Bearer REPLACE_ME"

**Response (example)**

Approved:

{
  "approved": true
}

Not approved yet:

{
  "approved": false
}

**What to do next**

• If { "approved": true }, execution is allowed.
• If { "approved": false }, keep waiting (or stop on your timeout). Timeout is not approval.
• If this request fails, treat it as { "approved": false } (fail closed).

1) Minimal Working Example (Node.js)

If you copy this example and replace the API key, it will work.

// Node.js 18+
// 1) Replace with your API key
const API_KEY = "REPLACE_ME";

const BASE_URL = "https://aisafegate.com";

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function validate(ai_output) {
  const res = await fetch(`${BASE_URL}/api/validate`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_KEY}`,
    },
    body: JSON.stringify({
      action_kind: "messaging.send",
      action_type: "send",

2) WARN Approval Handling (mandatory)

When you receive WARN:

• Your app must **pause** the downstream action.
• Your app must **resume** only after polling returns { "approved": true }.
• A timeout is **not** approval.
• Errors must **fail closed** (do not continue).

Polling endpoint:

GET https://aisafegate.com/api/decisions/{decision_id}/approval

Polling auth:

• X-Approval-Token: <approval_token>
• Authorization: Bearer <approval_token>
• Authorization: Bearer <API_KEY>

3) Execution Safety Rules

• Never assume approval.
• Never auto-approve.
• Never skip polling for WARN.
• Never continue on error.
• If validation fails, stop.