> ## Documentation Index
> Fetch the complete documentation index at: https://gr-docs.aporia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

## Overview

Aporia’s REST API method involves explicit API calls to enforce guardrails before and after LLM interactions, suitable for applications requiring a high level of customization and control over content policy enforcement.

## Prerequisites

Before you begin, ensure you have [created an Aporia Guardrails project](/fundamentals/projects#creating-a-project).

## Integration Guide

### Step 1: Gather Aporia's API Key

1. Log into the [Aporia dashboard](https://guardrails.aporia.com) and select your project.
2. Click on the **Integration** tab.
3. Ensure that **REST API** is activated.
4. Note down the API Key displayed.

### Step 2: Integrate into Your Code

1. Locate where your code makes LLM calls, such as OpenAI API calls.
2. Before sending the prompt to the LLM, and after receiving the LLM's response, incorporate calls to Aporia’s REST API to enforce the respective guardrails.

### API Endpoint and JSON Structure

**Endpoint:** POST `https://gr-prd.aporia.com/<PROJECT_ID>/validate`

**Headers:**

* `Content-Type`: `application/json`
* `X-APORIA-API-KEY`: Your copied Aporia API key

**Request Fields:**

<ParamField body="messages" type="array" required>
  OpenAI-compatible array of messages. Each message should include `role` and `content`.

  Possible `role` values are `system`, `user`, `assistant`, or `other` for any unsupported roles.
</ParamField>

<ParamField body="validation_target" type="string" required default="both">
  The target of the validation which can be `prompt`, `response`, or `both`.
</ParamField>

<ParamField body="response" type="string">
  The raw response from the LLM before any modifications. It is required if 'validation\_target' includes 'response'.
</ParamField>

<ParamField body="explain" type="boolean" default="false">
  Whether to return detailed explanations for the actions taken by the guardrails.
</ParamField>

<ParamField body="session_id" type="string">
  An optional session ID to track related interactions across multiple requests.
</ParamField>

<ParamField body="user" type="string">
  An optional user ID to associate sessions with specific user and monitor user activity.
</ParamField>

**Response Fields:**

<ResponseField name="action" type="string" required>
  The action taken by the guardrails, possible values are `modify`, `passthrough`, `block`, `rephrase`.
</ResponseField>

<ResponseField name="revised_response" type="string" required>
  The revised version of the LLM's response based on the applied guardrails.
</ResponseField>

<ResponseField name="explain_log" type="array">
  A detailed log of each policy's application, including the policy ID, target, result, and details of the action taken.
</ResponseField>

<ResponseField name="policy_execution_result" type="object">
  The final result of the policy execution, detailing the log of policies applied and the specific actions taken for each.
</ResponseField>

**Request JSON Example:**

```json theme={null}
{
  "messages": [
    {
      "role": "user",
      "content": "This is a test prompt"
    }
  ],
  "response": "Response from LLM here",

  // Optional
  // "validation_target": "both",
  // "explain": false,
  // "session_id": "optional-session-id"
  // "user": "optional-user-id"
}
```

**Response JSON Example:**

```json theme={null}
{
  "action": "modify",
  "revised_response": "Modified response based on policy",
  "explain_log": [
    {
      "policy_id": "001",
      "target": "response",
      "result": "issue_detected",
      "details": {
        ...
      }
    },
    ...
  ],
  "policy_execution_result": {
    "policy_log": [
      {
        "policy_id": "001",
        "policy_type": "content_check",
        "target": "response"
      }
    ],
    "action": {
      "type": "modify",
      "revised_message": "Modified response based on policy"
    }
  }
}
```

## Best practices

### Request timeout

Set up a timeout of 5 second to the HTTP request in case there's any failure on Aporia's side.

If you are using the `fetch` API in JavaScript, you can provide an abort signal using the [AbortController API](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) and trigger it with `setTimeout`. [See this example.](https://dev.to/zsevic/timeout-with-fetch-api-49o3)

If you are using the requests library in Python, you can simply provide a `timeout` argument:

```python theme={null}
import requests

requests.post(
   "https://gr-prd.aporia.com/<PROJECT_ID>/validate",
   timeout=5,
   ...
) 
```