Complete API

The "Complete" API accepts the Risky Response from the Destination App, processes it with your Policies and Guardrails then forwards the Safe Response to the Custom App that made the request.

Field Descriptions

Input Fields

Field: request_id Type: string

Example: "f0078d68-0100-0000-0000-00007845779e"

Description: UUID received from the input call

Field: conversation_id Type: string

Example: "f0078d68-0100-0000-0000-00007845779e"

Description: UUID received from the input call

Field: text Type: string Example: “Here are a few ways to find good talent...”

Description: The response text from the Destination App, to be processed by your response policies and guardrails.

Field: title Type: string Example: “Talent Search”.

Description: Name of the conversation to display in the console.

Field: provider_name Type: string Example: “openai”

Description: The model provider name, as displayed in the console

Field: model_name Type: string Example: “gpt-4o”

Description: The model name, as displayed in the console.

Object: user

Field: email Type: string Example: “you@yourco.com”

Description: User's email address. Used for matching users in Policies and Guardrails.

Response Fields

Field: request_id Type: string

Example: "f0078d68-0700-0000-0000-000023cf7b99"

Description: UUID for this request.

Field: conversation_id Type: string

Example: "f0078d68-0700-0000-0000-000023cf7b99"

Description: UUID for this conversation.

Field: text Type: string Example: “Here are a few ways to find good talent...”

Description: The safe response, after your response policies and guardrails have run.

Field: report Type: object Example: (See Example Response).

Description: Score report for the response. It holds the array of Scorecards (score_cards) and the warning_count, error_count, incomplete_count, input_score, output_score, combined_score, risk_score and result fields.

Field: warning_count Type: integer Example: 0

Description: total of warnings from all scorecards.

Field: error_count Type: integer Example: 0

Description: Total guardrails that could not execute, not [pass|fail].

Field: incomplete_count Type: integer Example: 0

Description: Not currently used. Total guardrails that timed out.

Field: input_score Type: integer Example:

Description: Not currently used.

Field: output_score Type: integer Example:

Description: Not currently used.

Field: combined_score Type: integer Example:

Description: Not currently used. input_score + output_score.

Field: risk_score Type: integer Example:

Description: 0-3, 0 being no risk, 3 being high risk

Field: result Type: string Example: “pass” or “fail”.

Description: Pass / fail string.

Field: block_flow Type: boolean Example: [true|false]

Description: Based on policy interpretation

Scorecard Fields

💡

The API Response includes a “report” field, which consists of an array of “Scorecards”.

Field: id Type: string

Example: "f0078d68-0700-0000-0000-000023cf7b99".

Description: UUID for scorecard.

Field: prompt_id Type: string

Example: "f0078d68-0700-0000-0000-000023cf7b99".

Description: UUID for for prompt.

Field: report_type Description: not currently used

Field: started_at Type: datetime Description: Start time of run

Field: completed_at Type: datetime Description: End time of run.

Field: data_modified Type: boolean Example: [true|false]

Description: Indicates if input data was modified, or required redaction.

Field: risk_type Type: string Example: "Data Leakage"

Description: Readable string of whatever risk was found.

Field: risk_metric Type: string

Example: "None", "Low", "Medium", "High".

Field: message Type: string

Description: Human readable message that is guardrail specific. For the intention classifier, it is the intention classification of the User Prompt.

Field: result Type: string Example: “pass” or “fail”.

Description: Pass / fail string.

Field: filter_identifier Type: string

Example: "fl-pre-intention-classifier"

Description: Name of filter.

Usage

Example Request


curl --request POST \
     --url https://api.witnessai.yourco.com/v1/guardrail/complete \
     --header 'accept: application/json' \
     --header 'authorization: bearer your-authentication-key' \
     --header 'content-type: application/json' \
     --data '
{
  "request_id": "f0078d68-0100-0000-0000-00007845779e",
  "conversation_id": "f0078d68-0700-0000-0000-000023cf7b99",
  "text": "payment American Express: [TEMPLATE_CREDIT_CARD_2] or [TEMPLATE_CREDIT_CARD_1]",
  "provider_name": "openai",
  "model_name": "gpt-4o",
  "user": {
    "email": "admin@yourco.com"
  }
}
'

Example 200 Response


{
  "request_id": "f0078d68-0100-0000-0000-00007845779e",
  "conversation_id": "f0078d68-0700-0000-0000-000023cf7b99",
  "text": "payment American Express: [TEMPLATE_CREDIT_CARD_2] or [TEMPLATE_CREDIT_CARD_1]",
  "report": {
    "score_cards": [
      {
        "id": "250b8d68-0c00-0000-0000-0000ec350d69",
        "prompt_id": "f0078d68-0100-0000-0000-00007845779e",
        "report_type": "",
        "started_at": "2025-08-01T18:44:53.249144Z",
        "completed_at": "2025-08-01T18:44:53.249384Z",
        "data_modified": false,
        "risk_metric": "None",
        "message": "input did not require deanonymization",
        "result": "pass",
        "filter_identifier": "fl-post-deanonymizer"
      },
      {
        "id": "f6078d68-0c00-0000-0000-0000a1fdc565",
        "prompt_id": "f0078d68-0100-0000-0000-00007845779e",
        "report_type": "",
        "started_at": "2025-08-01T18:31:18.854834Z",
        "completed_at": "2025-08-01T18:31:18.918675Z",
        "data_modified": false,
        "risk_type": "None",
        "risk_metric": "None",
        "message": "[]",
        "result": "pass",
        "filter_identifier": "fl-pre-intention-classifier"
      },
      {
        "id": "f0078d68-0c00-0000-0000-0000009fbefa",
        "prompt_id": "f0078d68-0100-0000-0000-00007845779e",
        "report_type": "",
        "started_at": "2025-08-01T18:31:12.350063Z",
        "completed_at": "2025-08-01T18:31:12.410792Z",
        "data_modified": false,
        "risk_type": "None",
        "risk_metric": "None",
        "message": "prompt injection was not detected",
        "result": "pass",
        "filter_identifier": "fl-pre-risk-analysis"
      },
      {
        "id": "f0078d68-0c00-0000-0000-00003bd96865",
        "prompt_id": "f0078d68-0100-0000-0000-00007845779e",
        "report_type": "",
        "started_at": "2025-08-01T18:31:12.358245Z",
        "completed_at": "2025-08-01T18:31:12.366365Z",
        "data_modified": true,
        "confidence": 100,
        "risk_score": 3,
        "risk_type": "Data Leakage",
        "risk_metric": "High",
        "message": "input required anonymization",
        "result": "pass",
        "filter_identifier": "fl-pre-anonymizer",
        "rule_result": "warn",
        "rule_message": "Data Protection set to Warn Action ."
      },
      {
        "id": "f0078d68-0c00-0000-0000-000018423116",
        "prompt_id": "f0078d68-0100-0000-0000-00007845779e",
        "report_type": "",
        "started_at": "2025-08-01T18:31:12.349592Z",
        "completed_at": "2025-08-01T18:31:12.94504Z",
        "data_modified": false,
        "risk_type": "None",
        "risk_metric": "None",
        "message": "Process financial payment",
        "result": "pass",
        "filter_identifier": "fl-pre-topic-categorizer"
      },
      {
        "id": "b90b8d68-0c00-0000-0000-000024336df0",
        "prompt_id": "f0078d68-0100-0000-0000-00007845779e",
        "report_type": "",
        "data_modified": false,
        "result": "pass",
        "filter_identifier": "llm-manager"
      }
    ],
    "warning_count": 0,
    "error_count": 0,
    "incomplete_count": 0,
    "input_score": 0,
    "output_score": 0,
    "combined_score": 0,
    "risk_score": 3,
    "result": "pass"
  },
  "block_flow": false
}

HTTP Status Codes

200: Successful
400: Bad Request
401: Unauthorized
500: Internal Server Error

Complete API Description Field Descriptions Input Fields Response Fields Scorecard Fields Usage Example Request Example 200 Response HTTP Status Codes