Skip to main content
The API surface is the enforcement path for backends and batch jobs that cannot be placed behind a proxy but still want TrustGate policy evaluation on the critical path. The caller sends the content to a TrustGate API engine, asks “is this allowed? and if you need to change it, how?”, and then continues — or aborts — based on the decision. Unlike Gateway, Browser, and Endpoint — which are inline on the wire — the API surface is caller-driven. There is no proxy, no extension, no local hook: the backend is responsible for calling TrustGate at the right moment, interpreting the verdict, and honoring it.

​
When to use it

Pick the API surface when the workload fits one of these shapes:
  • Backend jobs that already know what prompt they are about to send to an LLM and can pay the cost of one extra HTTP round trip.
  • Batch processing over documents, transcripts, or datasets — score each item against the policy catalog before storing or passing it downstream.
  • Internal tools that call LLMs but live in a network where a proxy cannot be inserted, or where the team owning the tool prefers explicit calls to implicit interception.
  • Second-opinion checks — you already have another surface in the path, and you want the backend to call the API for an extra policy evaluation on a specific step.
For any workload that can be routed through a gateway, prefer the Gateway surface — it enforces inline without requiring code changes in the caller.

​
Creating an API engine

The API surface is provisioned as an Integration in the platform — the same pattern as the Gateway. Each integration creates an API engine with its own compute, endpoint, and API keys.
  1. Go to Integrations → Add Integration.
  2. Pick API from the provider catalog.
  3. Fill the form:
    • Integration Name — any label you’ll recognise later (for example prod-actions, batch-eu).
    • Deployment Type — choose one:
      • Serverless — an instantly-ready engine for learning and development.
      • Dedicated — a scalable production engine with effortless deployment.
    • Tags (optional) — comma-separated labels usable later for policy scoping.
  4. Save & Close.
You can create several API engines — for example one per region, per environment, or per tenant. Each engine is selectable under Where → API when writing a policy.

​
API keys

API keys are scoped to the engine, not to the workspace. Each integration issues its own set of keys from the integration’s detail page, and a key is only accepted by the engine that created it. This is the same model the Gateway uses, and it gives you:
  • Per-engine revocation — rotating keys for one environment doesn’t affect the others.
  • Per-engine audit — every event is unambiguously attributable to the engine it came from.
  • Per-engine quotas — rate limits and usage caps are applied independently.
Keys are created under the engine’s API Keys tab on the integration page and used as Authorization: Bearer … on every call.

​
How to integrate

The API surface is a single call your backend makes before (and optionally after) it calls the upstream LLM. The integration is code-only.

​
1. Collect the engine coordinates

From the API integration’s page, copy two values:
  • Endpoint — the engine’s base URL (the Actions API is exposed under it).
  • API key — generated under the engine’s API Keys tab.

​
2. Wrap the LLM call

The canonical integration shape is a three-step wrapper around the upstream LLM call:
  1. Call TrustGate with the request content.
  2. If the decision is block, stop. If mask, use the returned payload instead of the original. Otherwise continue.
  3. (Optional) Call TrustGate again with the response for a second-pass check before handing the result back to the user.
A minimal request / response pair looks like this: 
POST {ENGINE_URL}/v1/actions/execute
Authorization: Bearer {ENGINE_API_KEY}
Content-Type: application/json

{
  "application": "customer-support-bot",
  "use_case": "customer-support",
  "user": "[email protected]",
  "stage": "request",
  "payload": {
    "messages": [ { "role": "user", "content": "..." } ]
  },
  "metadata": { "tenant": "acme", "channel": "web" }
}

{
  "decision": "mask",
  "reason": "PII detected and redacted",
  "policy_ids": ["pol_01HXXX"],
  "evidence": [ { "detector": "pii", "entity": "EMAIL", "span": [12, 34] } ],
  "payload": {
    "messages": [ { "role": "user", "content": "... redacted ..." } ]
  }
}
The same endpoint handles the response stage — pass stage: "response" and the model output in payload.

​
3. Honor the decision

The caller is contractually responsible for acting on decision:
  • allow / log → call the upstream with the original payload.
  • mask → call the upstream with the returned payload.
  • block → do not call the upstream; surface the reason to the user or fail the job.
TrustGate logs the decision and the signed payload regardless of what the caller does, so non-compliance is auditable.

​
4. Batch and parallel calls

For batch jobs, the same endpoint accepts arrays and is safe to call concurrently. Rate limits and quotas are enforced per engine API key — see the Actions API reference for current limits.

​
5. Verify

After integrating, every call shows up in Runtime → Logs with the application, use_case, and user you passed, correlated with the engine it came through. For the full reference — endpoints, payload shapes, streaming, idempotency, and language-specific SDKs — see the Actions API section.

​
What it sees

Whatever the caller sends. Typical payloads include:
  • Prompts — the user message, system prompt, and conversation history before the LLM call.
  • Responses — the model output after the LLM call (for a second pass on the response).
  • Documents — uploaded files, extracted text, OCR output.
  • Tool-call payloads — tools[] and tool_calls if the backend wants per-step governance.
  • Arbitrary context — user identity, use case name, tenant, custom tags.
The API only sees what the caller sends. A field that is not included cannot be evaluated.

​
How enforcement works

The three action verbs translate into contract behavior the caller must honor:
ActionAPI behaviorWhat the caller must do
LogReturns decision: "log" (or "allow") with evidence.Proceed with the original payload; the event is already recorded server-side.
MaskReturns decision: "mask" and a rewritten payload.Use the returned payload instead of the original for the upstream LLM call.
BlockReturns decision: "block" with a reason.Do not call the upstream. Surface the reason to the user or fail the job.
Enforcement is a contract: TrustGate cannot physically stop a backend that ignores the verdict. In practice this is mitigated with two controls:
  • The decision and its payload signature are logged, so non-compliance is auditable.
  • For regulated workloads, policy authors use the Gateway or Endpoint surface instead, where enforcement is inline.

​
Available filters

When authoring a policy with Where → API, Add filter offers:
FilterNarrows by
EnginesSpecific API integrations (for example prod-actions, batch-eu).
TagsAny tag attached to an engine at creation time.
Use CasesBusiness-level groupings shared across surfaces.
Filters combine with AND. Omitting every filter applies the policy to all traffic on every API engine in the workspace. For per-tenant or per-workflow scoping beyond this, pass the relevant metadata in the API call and use it inside the When conditions.

​
Best for

  • Backend integrations and batch jobs that can’t be put behind a proxy.
  • Workflows where explicit policy checks in code are preferred over transparent interception.
  • Pairing with other surfaces as a second-line or step-level check.
  • Policies — the Where / When / Then model that runs behind the API.
  • Gateway surface — inline alternative when the workload can be proxied.
  • Developers reference — the Actions API endpoints, request and response shapes, and authentication.