Endpoint: Gateway Execute

Execute a prompt through the Veriprompt gateway with provider routing, policy enforcement, and optional telemetry instrumentation.

Endpoint

POST /api/gateway/execute

Request Body

{
  prompt: string; // Required
  systemPrompt?: string;
  messages?: Array<{ role: "user" | "assistant" | "system"; content: string }>;
  variables?: Record<string, unknown>;
  providerType?: "OPENAI" | "ANTHROPIC" | "GOOGLE" | "DEEPSEEK" | "CUSTOM";
  model?: string;
  maxTokens?: number;
  temperature?: number; // 0..2
  metadata?: Record<string, unknown>;

  // Routing
  policyId?: string;
  policy?: unknown;
  providerGroupId?: string;
  rotation?: "ROUND_ROBIN" | "SEQUENTIAL" | "RANDOM";
  customGatewayId?: string;

  // Client credential mode
  useClientCredentials?: boolean;
  clientProvider?: {
    type: "OPENAI" | "ANTHROPIC" | "GOOGLE" | "DEEPSEEK" | "CUSTOM";
    apiKey: string;
    model?: string;
    endpoint?: string;
  };

  // Attachments
  attachments?: Array<{
    type: "text" | "url" | "file";
    content?: string;
    url?: string;
    fileId?: string;
    fileName?: string;
    mimeType?: string;
    fileSize?: number;
  }>;

  // Prompt reference execution
  resolveReferences?: boolean;

  // Provider session affinity
  session_id?: string;
  session_ttl?: number;
  force_rotate?: boolean;

  // Runtime telemetry controls
  telemetry?: {
    mode?: "off" | "sampled" | "full";
    sampleRate?: number; // 0..1
    force?: boolean;
    enabled?: boolean;
  };

  // Optional PII sanitization
  sanitization?: {
    enabled?: boolean;
    trigger?: "prompt" | "api" | "user_action";
    profiles?: string[];
  };
}

Task hints for task-aware routing

Two optional request fields tell the gateway what a request is about. They only matter when the effective routing policy has task-aware routing enabled and the company's package includes it; otherwise they are ignored for ranking.

Field	Type	Description
metadata.taskCodes	string[] or comma-separated string	Task codes or aliases, for example ["coding", "debugging"]. Treated as explicitly stated (full confidence): no classification request is made
specializations	string[] (max 20)	The existing soft preference for models tagged with these specializations. Also used as the stated task when metadata.taskCodes is absent. A term that is not in the platform vocabulary returns 400

Order of precedence when several sources exist: stated codes, then the stored prompt's pinned task or category (metadata.promptId), then the execution profile, then detection from the request text. Detection through the gateway classifier only runs when the policy's classifier is gateway, the earlier sources are empty and pattern matching is not confident. It is billed to your company as a short request with purpose task-classification and never recurses.

{
  "prompt": "Review this diff and list bugs: ...",
  "policyId": "YOUR_POLICY_ID",
  "metadata": { "taskCodes": ["coding", "debugging"] }
}

The response format is unchanged. To see which model each task would favour before you send, use the simulation or the routing advisory.

PII Sanitization

• sanitization.enabled: true requests pre-provider sanitization for this execution.
• sanitization.trigger identifies the source of the request.
• The effective routing policy decides whether sanitization is disabled, automatic, or manual.
• In manual mode, the trigger must be allowed by the policy.
• The company package must include allowPiiSanitization; otherwise the gateway returns 403 SANITIZATION_FEATURE_UNAVAILABLE.

Telemetry Behavior

• Wrapper injection only happens when telemetry instrumentation is enabled at runtime.
• Instrumentation mode resolves from:
  • telemetry.mode
  • metadata.telemetryMode
  • agentic metadata hint (metadata.agent, metadata.chainId, metadata.chainExecutionId)
• telemetry.force: true forces instrumentation regardless of sampling.
• If response includes ##TEL{...}TEL##, the gateway strips that block from result.content before returning to the client.

Example Request

curl https://app.veriprompt.tech/api/gateway/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  -d '{
    "prompt": "Summarize the incident and propose next actions.",
    "providerGroupId": "grp_ops_primary",
    "sanitization": {
      "enabled": true,
      "trigger": "api",
      "profiles": ["personal_information", "corporate_confidential"]
    },
    "telemetry": { "mode": "sampled", "sampleRate": 0.1 },
    "metadata": {
      "projectId": "proj_123",
      "promptId": "prompt_incident_summary",
      "chainId": "chain_incident_triage"
    }
  }'

Success Response

{
  "success": true,
  "executionId": "cm1...",
  "result": {
    "content": "Incident summary...",
    "contentType": "text/plain; charset=utf-8",
    "encoding": "utf-8",
    "metadata": null
  },
  "usage": {
    "promptTokens": 732,
    "completionTokens": 281,
    "totalTokens": 1013
  },
  "provider": {
    "name": "openai",
    "type": "OPENAI",
    "model": "gpt-4o-mini"
  },
  "metadata": {
    "executedAt": "2026-02-10T18:12:01.223Z",
    "providerExecMs": 936,
    "finishReason": "stop",
    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
    "spanId": "53dd8f1b4f76e6f2",
    "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-53dd8f1b4f76e6f2-01",
    "telemetryMode": "sampled",
    "telemetryWrapped": true,
    "telemetryTraceId": "f9a01c2d",
    "geoRuleSource": "PROJECT",
    "geoRulesApplied": true,
    "sanitization": {
      "applied": true,
      "mode": "manual",
      "trigger": "api",
      "reason": "manual_request_accepted",
      "profiles": ["personal_information", "corporate_confidential"],
      "sessionToken": "stk_...",
      "detectionSummary": {
        "total_entities_found": 4,
        "by_category": {
          "PERSON": 1,
          "EMAIL_ADDRESS": 1,
          "ORGANIZATION": 2
        }
      }
    }
  }
}

Policy Compliance Fields

When a company-level routing policy exists, every execution (including internal service calls via executePrompt()) is checked for compliance. The response includes:

Field	Type	Description
policyChecked	boolean	Whether a routing policy was evaluated
policyName	string	Name of the evaluated policy (if any)

Policy Violation Response

When a provider violates the company's routing policy (geo restrictions, provider deny list, or model deny list), the gateway returns:

{
  "success": false,
  "error": "[Policy Violation] \"prompt-optimizer\" cannot use provider deepseek/deepseek-chat: Provider country CN is denied. Your company routing policy \"EU-Only Compliance\" restricts this provider. To enable this function, add a compliant provider via BYOK credentials (Settings → Credentials) or ask your admin to update the service configuration (Admin → Service Config).",
  "provider": "deepseek",
  "model": "deepseek-chat",
  "policyChecked": true,
  "policyName": "EU-Only Compliance"
}

Error Responses

• 400 invalid payload
• 401 unauthorized
• 403 policy/geofence block (includes routing policy violations for internal services)
• 403 sanitization feature unavailable for current subscription
• 404 missing user/company or missing custom gateway
• 429 concurrency guardrail
• 500 provider execution failure

OTLP Trace Export

If OTLP is configured, this endpoint emits server spans in OTLP HTTP JSON format.

• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTLP_HTTP_TRACES_ENDPOINT
• OTEL_EXPORTER_OTLP_ENDPOINT (auto-appends /v1/traces)
• OTEL_EXPORTER_OTLP_HEADERS
• OTEL_SERVICE_NAME
• OTEL_SERVICE_NAMESPACE

Related docs

• Prompt Chaining & Execution Modes
• AI Gateway Feature
• Routing Advisory