---
title: "Invoke"
method: POST
path: "/v1/protect/invoke"
tags: ["protect"]
---

# Invoke

`POST /v1/protect/invoke`

## Request body

- ProtectRequest — Protect request schema with custom OpenAPI title.
  - `prioritized_rulesets` Ruleset[] — Rulesets to be applied to the payload.
    - `rules` Rule[] — List of rules to evaluate. Atleast 1 rule is required.
      - `metric` string, required — Name of the metric.
      - `operator` 'gt' | 'lt' | 'gte' | 'lte' | 'eq' | 'neq' | 'contains' | 'all' | 'any' | 'empty' | 'not_empty', required
      - `target_value` union, required — Value to compare with for this metric (right hand side).
        - string
        - number
        - integer
        - unknown[]
          - unknown
    - `action` union — Action to take if all the rules are met.
      - OverrideAction
        - `type` 'OVERRIDE'
        - `subscriptions` SubscriptionConfig[] — List of subscriptions to send a notification to when this action is applied and the ruleset status matches any of the configured statuses.
          - `statuses` ExecutionStatus[] — List of statuses that will cause a notification to be sent to the configured URL.
          - `url` string, uri, required — URL to send the event to. This can be a webhook URL, a message queue URL, an event bus or a custom endpoint that can receive an HTTP POST request.
        - `choices` string[], required — List of choices to override the response with. If there are multiple choices, one will be chosen at random when applying this action.
      - PassthroughAction
        - `type` 'PASSTHROUGH'
        - `subscriptions` SubscriptionConfig[] — List of subscriptions to send a notification to when this action is applied and the ruleset status matches any of the configured statuses.
          - `statuses` ExecutionStatus[] — List of statuses that will cause a notification to be sent to the configured URL.
          - `url` string, uri, required — URL to send the event to. This can be a webhook URL, a message queue URL, an event bus or a custom endpoint that can receive an HTTP POST request.
    - `description` string, nullable — Description of the ruleset.
  - `payload` Payload, required
    - `input` string, nullable — Input text to be processed.
    - `output` string, nullable — Output text to be processed.
  - `project_name` string, nullable — Project name.
  - `project_id` string, uuid4, nullable — Project ID.
  - `stage_name` string, nullable — Stage name.
  - `stage_id` string, uuid4, nullable — Stage ID.
  - `stage_version` integer, nullable — Stage version to use for the request, if it's a central stage with a previously registered version.
  - `timeout` number — Optional timeout for the guardrail execution in seconds. This is not the timeout for the request. If not set, a default timeout of 5 minutes will be used.
  - `metadata` object, nullable — Optional additional metadata. This will be echoed back in the response.
  - `headers` object, nullable — Optional additional HTTP headers that should be included in the response.

## Response `200`

Successful Response

- union
  - ProtectResponse — Protect response schema with custom OpenAPI title.
    - `status` string — Status of the request after processing the rules.
    - `text` string, required — Text from the request after processing the rules.
    - `trace_metadata` TraceMetadata, required
      - `id` string, uuid4 — Unique identifier for the request.
      - `received_at` integer — Time the request was received by the server in nanoseconds.
      - `response_at` integer — Time the response was sent by the server in nanoseconds.
      - `execution_time` number — Execution time for the request (in seconds).
  - InvokeResponse
    - `status` string — Status of the execution.
    - `api_version` string
    - `text` string, required — Text from the request after processing the rules.
    - `trace_metadata` TraceMetadata, required
      - `id` string, uuid4 — Unique identifier for the request.
      - `received_at` integer — Time the request was received by the server in nanoseconds.
      - `response_at` integer — Time the response was sent by the server in nanoseconds.
      - `execution_time` number — Execution time for the request (in seconds).
    - `stage_metadata` StageMetadata, required
      - `project_id` string, uuid4, required
      - `stage_id` string, uuid4, required
      - `stage_name` string, required
      - `stage_version` integer, required
      - `stage_type` 'local' | 'central', required
    - `ruleset_results` RulesetResult[] — Results of the rule execution.
      - `status` string — Status of the execution.
      - `rules` Rule[] — List of rules to evaluate. Atleast 1 rule is required.
        - `metric` string, required — Name of the metric.
        - `operator` 'gt' | 'lt' | 'gte' | 'lte' | 'eq' | 'neq' | 'contains' | 'all' | 'any' | 'empty' | 'not_empty', required
        - `target_value` union, required — Value to compare with for this metric (right hand side).
          - string
          - number
          - integer
          - unknown[]
            - unknown
      - `action` union — Action to take if all the rules are met.
        - OverrideAction
          - `type` 'OVERRIDE'
          - `subscriptions` SubscriptionConfig[] — List of subscriptions to send a notification to when this action is applied and the ruleset status matches any of the configured statuses.
            - `statuses` ExecutionStatus[] — List of statuses that will cause a notification to be sent to the configured URL.
            - `url` string, uri, required — URL to send the event to. This can be a webhook URL, a message queue URL, an event bus or a custom endpoint that can receive an HTTP POST request.
          - `choices` string[], required — List of choices to override the response with. If there are multiple choices, one will be chosen at random when applying this action.
        - PassthroughAction
          - `type` 'PASSTHROUGH'
          - `subscriptions` SubscriptionConfig[] — List of subscriptions to send a notification to when this action is applied and the ruleset status matches any of the configured statuses.
            - `statuses` ExecutionStatus[] — List of statuses that will cause a notification to be sent to the configured URL.
            - `url` string, uri, required — URL to send the event to. This can be a webhook URL, a message queue URL, an event bus or a custom endpoint that can receive an HTTP POST request.
      - `description` string, nullable — Description of the ruleset.
      - `rule_results` RuleResult[] — Results of the rule execution.
        - `status` string — Status of the execution.
        - `metric` string, required — Name of the metric.
        - `operator` 'gt' | 'lt' | 'gte' | 'lte' | 'eq' | 'neq' | 'contains' | 'all' | 'any' | 'empty' | 'not_empty', required
        - `target_value` union, required — Value to compare with for this metric (right hand side).
          - string
          - number
          - integer
          - unknown[]
            - unknown
        - `value` unknown
        - `execution_time` number, nullable — Execution time for the rule in seconds.
    - `metric_results` object — Results of the metric computation.
    - `action_result` ActionResult, required
      - `type` 'OVERRIDE' | 'PASSTHROUGH', required
      - `value` string, required — Value of the action that was taken.
    - `metadata` object, nullable — Optional additional metadata. This being echoed back from the request.
    - `headers` object, nullable — Optional additional HTTP headers that should be included in the response.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/galileo/apis/galileo-api-server.md) · [All operations](https://skmtc.net/galileo/apis/galileo-api-server/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/galileo/galileo-api-server/versions/933e8c8e6366/schema)