{"openapi":"3.1.0","info":{"title":"Guard API","version":"1.0.0"},"paths":{"/v2/guard":{"post":{"operationId":"guard_screenContent","summary":"Screen content for threats","description":"The `guard` API endpoint is the integration point for GenAI applications using AI Guardrails. It allows you to call on all of AI Guardrails' defenses with a single API call.\n\nFor an overview and integration guidance please see [here](/docs/api/guard).\n\nUsing `guard`, you can submit the content of an LLM interaction to AI Guardrails. This include inputs from the user, reference documents, and the LLM output. The guardrails configured in the policy will screen the interaction, and a flagging response will indicate whether any threats were detected, in line with your policy.\n\nYour application can then be programmed to take mitigating action based on the flagging response, such as blocking the interaction, warning the end user, or generating an internal security alert.\n\nA request must contain `messages`, `tools`, or both. Send `tools` on its own to screen tool definitions independently of a conversation.\n","tags":["guard"],"responses":{"200":{"description":"Screening result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuardResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuardRequest"}}}},"security":[{"bearerAuth":[]}]}},"/v2/guard/results":{"post":{"operationId":"guardResults_getResults","summary":"Get detailed detection results","description":"The `results` endpoint screens submitted content according to the policy assigned to the specified project. It then returns the confidence level results of the detectors. It doesn't make a flagging decision or create a request log in Guard. It can be used to analyze data and calibrate detector threshold levels for policies.\n\nYou can use the `results` endpoint to analyze historic LLM prompt and response data without worrying about triggering alerts or affecting monitoring, as they are not logged as screening requests by AI Guardrails.\n\nIf no project ID is passed in the request, then the default AI Guardrails policy is used, which runs all Guard defenses and detectors at the highest sensitivity level.\n\nA request must contain `messages`, `tools`, or both.\n\n<Warning>`results` requests are not logged as screening requests in AI Guardrails and do not appear in the platform or exported logs. It should not be used in runtime GenAI application security decisions as it removes the ability to control your defenses using policies.</Warning>\n","tags":["guardResults"],"responses":{"200":{"description":"Successful retrieval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedResults"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuardResultsRequest"}}}},"security":[{"bearerAuth":[]}]}},"/v2/policies/health":{"post":{"operationId":"policiesHealth_checkPolicyHealth","summary":"Check policy configuration health","description":"Check the validity of the policy configuration for a given project.\nIf no project ID is passed then the health of the AI Guardrails Default Policy will be returned.\n","tags":["policiesHealth"],"responses":{"200":{"description":"Policy health check results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyHealthResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PoliciesHealthRequest"}}}},"security":[{"bearerAuth":[]}]}},"/v2/policies/lint":{"post":{"operationId":"policiesLinter_lintPolicy","summary":"Validate policy configuration","description":"Lint and validate policy JSON configuration files\n\n<Note> The easiest way to check your policy file validity is via the [policy linter tool in the Guard platform](https://platform.lakera.ai/policy-linter). This editor provides basic linting for your policy. It will check for common errors and provide suggestions for improvement.\nThe tool is run locally in the browser, so any policies or JSON entered in it are not saved anywhere. Note this also means that the contents are lost if you close the page. </Note>\n","tags":["policiesLinter"],"responses":{"200":{"description":"Policy validation results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyLintResponse"}}}}},"security":[{"bearerAuth":[]}]}}},"tags":[{"name":"guard"},{"name":"guardResults"},{"name":"policiesHealth"},{"name":"policiesLinter"}],"servers":[{"url":"https://api.lakera.ai","description":"Default"},{"url":"https://eu.api.lakera.ai","description":"Eu"},{"url":"https://us.api.lakera.ai","description":"Us"},{"url":"https://ap-southeast-1.api.lakera.ai","description":"ApSoutheast"}],"components":{"schemas":{"ContentPartType":{"type":"string","enum":["text"],"title":"ContentPartType"},"ContentPart":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ContentPartType"},"text":{"type":"string"}},"required":["type","text"],"description":"A part of the message content","title":"ContentPart"},"MessageContent1":{"type":"array","items":{"$ref":"#/components/schemas/ContentPart"},"title":"MessageContent1"},"MessageContent":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/MessageContent1"}],"description":"The text content of the message. Required, except for assistant messages that include `tool_calls`, where it may be null or omitted.","title":"MessageContent"},"MessageRole":{"type":"string","enum":["system","user","assistant","tool","developer"],"description":"The role of the message sender","title":"MessageRole"},"Function":{"type":"object","properties":{"name":{"type":"string"},"arguments":{"type":"string"}},"required":["name","arguments"],"description":"A function to call","title":"Function"},"ToolCallType":{"type":"string","enum":["function"],"title":"ToolCallType"},"ToolCall":{"type":"object","properties":{"function":{"$ref":"#/components/schemas/Function","description":"The function to call"},"type":{"$ref":"#/components/schemas/ToolCallType"},"id":{"type":"string"}},"required":["function","type","id"],"description":"A tool call made by the assistant","title":"ToolCall"},"Message":{"type":"object","properties":{"content":{"$ref":"#/components/schemas/MessageContent","description":"The text content of the message. Required, except for assistant messages that include `tool_calls`, where it may be null or omitted."},"role":{"$ref":"#/components/schemas/MessageRole","description":"The role of the message sender"},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/ToolCall"},"description":"Optional tool calls (only valid for assistant messages)"}},"required":["role"],"description":"A message in a conversation with the AI","title":"Message"},"ToolDefinitionType":{"type":"string","enum":["function"],"title":"ToolDefinitionType"},"ToolDefinitionFunction":{"type":"object","properties":{"name":{"type":"string","description":"Name of the tool. Must not be empty."},"description":{"type":"string","description":"Description of what the tool does and when to use it"},"parameters":{"type":"object","additionalProperties":{"description":"Any type"},"description":"JSON Schema object describing the tool's parameters"},"strict":{"type":"boolean","description":"Whether the model is required to follow the parameter schema exactly"}},"required":["name"],"description":"The function a tool definition describes","title":"ToolDefinitionFunction"},"ToolDefinition":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ToolDefinitionType"},"function":{"$ref":"#/components/schemas/ToolDefinitionFunction"}},"required":["type","function"],"description":"A tool definition exposed to the model, in OpenAI function-calling format","title":"ToolDefinition"},"GuardRequestMetadata":{"type":"object","properties":{"user_id":{"type":"string","description":"Unique identifier for the end user interacting with the LLM"},"session_id":{"type":"string","description":"Unique identifier for the user's session or conversation"},"ip_address":{"type":"string","format":"ipv4","description":"IP address of the user making the request"},"internal_request_id":{"type":"string","description":"Internal request identifier for correlation with other systems"}},"description":"Metadata tags can be attached to screening requests as an object that can contain any arbitrary key-value pairs.\nCommon use cases include specifying the user or session ID.\n","title":"GuardRequestMetadata"},"GuardRequest":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"},"description":"List of messages comprising the interaction history with the LLM in OpenAI API Chat Completions format.\nCan be multiple messages of any role: user, assistant, system, tool, or developer.\nRequired unless `tools` is provided.\n"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolDefinition"},"description":"List of tool definitions exposed to the model, in OpenAI function-calling format.\nEach definition is screened on every request if your policy applies Prompt Defense to the Tool Definition role (screening location `tool_definition::content`).\nCan be sent without `messages`. See [Tool definitions](/docs/api/screening-roles#tool-definitions).\n"},"project_id":{"type":"string","description":"ID of the relevant project. The request will be screened according to the policy assigned to the project.\nIf no project ID is passed then the AI Guardrails Default Policy will be used for screening.\n"},"payload":{"type":"boolean","description":"When true the response will return a payload object containing any PII, profanity or custom detector\nregex matches detected, along with their location within the contents.\n"},"breakdown":{"type":"boolean","description":"When true the response will return a breakdown list of the detectors that were run, as defined in the policy,\nand whether each of them detected something or not.\n"},"metadata":{"$ref":"#/components/schemas/GuardRequestMetadata","description":"Metadata tags can be attached to screening requests as an object that can contain any arbitrary key-value pairs.\nCommon use cases include specifying the user or session ID.\n"},"dev_info":{"type":"boolean","description":"When true the response will return an object with developer information about the build of AI Guardrails.\n"}},"description":"Request to screen content for threats. At least one of `messages` or `tools` must be provided.","title":"GuardRequest"},"GuardResponseAction":{"type":"string","enum":["detect","enforce"],"description":"The [action](/docs/projects#project-mode) configured for the project screening this request. `enforce` means full enforcement: the top-level `flagged` is `true` whenever a detector triggers. `detect` surfaces detections in the breakdown but forces the top-level `flagged` to `false`, letting you observe detector behavior without blocking traffic. Configured on the project level.\n","title":"GuardResponseAction"},"GuardResponsePayloadItems":{"type":"object","properties":{"start":{"type":"integer"},"end":{"type":"integer"},"text":{"type":"string"},"detector_type":{"type":"string"},"labels":{"type":"array","items":{"type":"string"}},"message_id":{"type":"integer","description":"Index of the message in the request that this result corresponds to"}},"title":"GuardResponsePayloadItems"},"GuardResponseBreakdownItems":{"type":"object","properties":{"project_id":{"type":"string"},"policy_id":{"type":"string"},"detector_id":{"type":"string"},"detector_type":{"type":"string"},"detected":{"type":"boolean"},"result":{"type":"string","description":"Confidence level (l1_confident, l2_very_likely, l3_likely, l4_less_likely, l5_unlikely, no_level)"},"message_id":{"type":"integer","description":"Index of the message in the request that this result corresponds to"}},"title":"GuardResponseBreakdownItems"},"GuardResponseToolsBreakdownItems":{"type":"object","properties":{"project_id":{"type":"string"},"policy_id":{"type":"string"},"detector_id":{"type":"string"},"detector_type":{"type":"string"},"detected":{"type":"boolean"},"result":{"type":"string","description":"Confidence level (l1_confident, l2_very_likely, l3_likely, l4_less_likely, l5_unlikely, no_level)"},"tool_id":{"type":"integer","description":"Zero-based index of the tool definition in the request's `tools` array"}},"title":"GuardResponseToolsBreakdownItems"},"GuardResponseTools":{"type":"object","properties":{"flagged":{"type":"boolean","description":"Whether any tool definition was flagged"},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/GuardResponseToolsBreakdownItems"},"description":"List of detectors run on the tool definitions and their results.\nOnly returned if breakdown=true in request.\n"}},"description":"Screening results for the tool definitions in the request's `tools` array, separate from the message-level results.\nOnly returned if the request contains `tools`, the policy applies a detector to the Tool Definition role,\nand `breakdown` is true.\n","title":"GuardResponseTools"},"GuardResponseDevInfo":{"type":"object","properties":{"git_revision":{"type":"string","description":"First 8 characters of the commit hash"},"git_timestamp":{"type":"string","description":"Timestamp in ISO 8601 format"},"model_version":{"type":"string","description":"Currently always 'lakera-guard-1'"},"version":{"type":"string","description":"Semantic version tracking code and model updates"}},"description":"Build information. Only returned if dev_info=true in request.\n","title":"GuardResponseDevInfo"},"GuardResponseMetadata":{"type":"object","properties":{"request_uuid":{"type":"string","description":"Unique identifier for the request"}},"description":"Metadata returned from the request","title":"GuardResponseMetadata"},"GuardResponse":{"type":"object","properties":{"flagged":{"type":"boolean","description":"Depends on the action configured for the project. If `action` is `enforce`, `flagged` is `true` if any threats were detected with sufficient confidence. But if `action` is `detect`, `flagged` is always `false`. See [Project Mode](/docs/projects#project-mode) for more details."},"action":{"$ref":"#/components/schemas/GuardResponseAction","description":"The [action](/docs/projects#project-mode) configured for the project screening this request. `enforce` means full enforcement: the top-level `flagged` is `true` whenever a detector triggers. `detect` surfaces detections in the breakdown but forces the top-level `flagged` to `false`, letting you observe detector behavior without blocking traffic. Configured on the project level.\n"},"payload":{"type":"array","items":{"$ref":"#/components/schemas/GuardResponsePayloadItems"},"description":"Contains detected PII, profanity, or custom regex matches with their locations.\nOnly returned if payload=true in request.\n"},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/GuardResponseBreakdownItems"},"description":"List of detectors run and their results.\nOnly returned if breakdown=true in request.\n"},"tools":{"$ref":"#/components/schemas/GuardResponseTools","description":"Screening results for the tool definitions in the request's `tools` array, separate from the message-level results.\nOnly returned if the request contains `tools`, the policy applies a detector to the Tool Definition role,\nand `breakdown` is true.\n"},"dev_info":{"$ref":"#/components/schemas/GuardResponseDevInfo","description":"Build information. Only returned if dev_info=true in request.\n"},"metadata":{"$ref":"#/components/schemas/GuardResponseMetadata","description":"Metadata returned from the request"}},"description":"Response from the Guard screening endpoint","title":"GuardResponse"},"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"integer","description":"HTTP status code"},"request_id":{"type":"string","description":"Unique identifier for the request"}},"description":"Standard error response format","title":"Error"},"GuardResultsRequest":{"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"},"description":"List of messages comprising the interaction history with the LLM in OpenAI API Chat Completions format.\nCan be multiple messages of any role: user, assistant, system, tool or developer.\nRequired unless `tools` is provided.\n"},"tools":{"type":"array","items":{"$ref":"#/components/schemas/ToolDefinition"},"description":"List of tool definitions exposed to the model, in OpenAI function-calling format.\nEach definition is screened on every request if your policy applies Prompt Defense to the Tool Definition role (screening location `tool_definition::content`).\nCan be sent without `messages`. See [Tool definitions](/docs/api/screening-roles#tool-definitions).\n"},"project_id":{"type":"string","description":"ID of the relevant project. The request will be screened according to the policy assigned to the project.\nIf no project ID is passed then the AI Guardrails Default Policy will be used for screening.\n"},"metadata":{"type":"object","additionalProperties":{"description":"Any type"},"description":"Metadata tags can be attached to screening requests as an object that can contain any arbitrary key-value pairs.\nCommon use cases include specifying the user or session ID.\n"},"dev_info":{"type":"boolean","description":"When true the response will return an object with developer information about the build of AI Guardrails.\n"}},"description":"Request to get detailed detection results. At least one of `messages` or `tools` must be provided.","title":"GuardResultsRequest"},"DetailedResultsResultsItems":{"type":"object","properties":{"project_id":{"type":"string"},"policy_id":{"type":"string"},"detector_id":{"type":"string"},"detector_type":{"type":"string"},"result":{"type":"string","description":"Confidence level (l1_confident, l2_very_likely, l3_likely, l4_less_likely, l5_unlikely, no_level)"},"custom_matched":{"type":"boolean","description":"Whether there is a match for custom regular expressions"},"message_id":{"type":"integer","description":"Index of the message in the request that this result corresponds to"}},"title":"DetailedResultsResultsItems"},"DetailedResultsToolsResultsItems":{"type":"object","properties":{"project_id":{"type":"string"},"policy_id":{"type":"string"},"detector_id":{"type":"string"},"detector_type":{"type":"string"},"result":{"type":"string","description":"Confidence level (l1_confident, l2_very_likely, l3_likely, l4_less_likely, l5_unlikely, no_level)"},"custom_matched":{"type":"boolean","description":"Whether there is a match for custom regular expressions"},"tool_id":{"type":"integer","description":"Zero-based index of the tool definition in the request's `tools` array"}},"title":"DetailedResultsToolsResultsItems"},"DetailedResultsTools":{"type":"object","properties":{"flagged":{"type":"boolean","description":"Whether any tool definition was flagged"},"results":{"type":"array","items":{"$ref":"#/components/schemas/DetailedResultsToolsResultsItems"},"description":"List of detector results for the tool definitions"}},"description":"Detector results for the tool definitions in the request's `tools` array.\nOnly returned if the request contains `tools` and the policy applies a detector to the Tool Definition role.\n","title":"DetailedResultsTools"},"DetailedResults":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/DetailedResultsResultsItems"},"description":"List of detector results"},"tools":{"$ref":"#/components/schemas/DetailedResultsTools","description":"Detector results for the tool definitions in the request's `tools` array.\nOnly returned if the request contains `tools` and the policy applies a detector to the Tool Definition role.\n"}},"description":"Detailed detection results","title":"DetailedResults"},"PoliciesHealthRequest":{"type":"object","properties":{"project_id":{"type":"string","description":"The project_id for which the policy health should be checked,.\n"}},"required":["project_id"],"description":"Request to check the health of a policy","title":"PoliciesHealthRequest"},"PolicyHealthResponseStatus":{"type":"string","enum":["ok","error"],"description":"Overall health status","title":"PolicyHealthResponseStatus"},"PolicyHealthResponseLintErrorsItemsSeverity":{"type":"string","enum":["error","warning"],"description":"Error severity level","title":"PolicyHealthResponseLintErrorsItemsSeverity"},"PolicyHealthResponseLintErrorsItems":{"type":"object","properties":{"message":{"type":"string","description":"Error or warning message"},"severity":{"$ref":"#/components/schemas/PolicyHealthResponseLintErrorsItemsSeverity","description":"Error severity level"}},"title":"PolicyHealthResponseLintErrorsItems"},"PolicyHealthResponseLint":{"type":"object","properties":{"passed":{"type":"boolean","description":"Whether validation passed"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/PolicyHealthResponseLintErrorsItems"},"description":"List of validation errors and warnings"}},"description":"Policy validation results","title":"PolicyHealthResponseLint"},"PolicyHealthResponse":{"type":"object","properties":{"status":{"$ref":"#/components/schemas/PolicyHealthResponseStatus","description":"Overall health status"},"is_default":{"type":"boolean","description":"Whether using the AI Guardrails Default Policy or a custom policy"},"message":{"type":["string","null"],"description":"Human-readable status message"},"lint":{"$ref":"#/components/schemas/PolicyHealthResponseLint","description":"Policy validation results"}},"description":"Health check results for a policy","title":"PolicyHealthResponse"},"PolicyLintResponseErrorsItemsSeverity":{"type":"string","enum":["error","warning"],"description":"Severity level of the issue","title":"PolicyLintResponseErrorsItemsSeverity"},"PolicyLintResponseErrorsItems":{"type":"object","properties":{"message":{"type":"string","description":"Error or warning message"},"severity":{"$ref":"#/components/schemas/PolicyLintResponseErrorsItemsSeverity","description":"Severity level of the issue"}},"title":"PolicyLintResponseErrorsItems"},"PolicyLintResponse":{"type":"object","properties":{"passed":{"type":"boolean","description":"Whether validation passed"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/PolicyLintResponseErrorsItems"},"description":"List of validation errors and warnings"}},"description":"Results from policy validation","title":"PolicyLintResponse"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer authentication using API key. Generate an API key from the AI Guardrails Dashboard.\nExample: Bearer sk_123...\n"}}}}