Get All Projects

Endpoint: GET https://guardrails.aporia.com/api/v1/projects

Headers:

  • Content-Type: application/json
  • Authorization: Bearer + Your copied Aporia API key

Response Fields:

The response type is a list. each object in the list contains the following fields:

id
uuid
required

The project ID.

name
string
required

The project name.

description
string

The project description.

icon
string

The project icon, possible values are codepen, chatBubbleLeftRight, serverStack, academicCap, bookOpen, commandLine, creditCard, rocketLaunch, envelope, identification.

color
string

The project color, possible values are turquoiseBlue, mustard, cornflowerBlue, heliotrope, spray, peachOrange, shocking, white, manz, geraldine.

organization_id
uuid
required

The organization ID.

is_active
bool
required

Boolean indicating whether the project is active or not.

policies
list[Policy]
required

List of policies, each Policy has the following attributes: id (uuid), policy_type (string), name (string), enabled (bool), condition (dict), action (dict).

project_extractions
list[ExtractionProperties]
required

List of extractions defined for the project. Each extraction contains the following fields:

  • descriptor_type: Either default or custom. Default extractions are supported by all Aporia policies, and it is recommended to define them for optimal results. Custom extractions are user-defined and are more versatile, but not all policies can utilize them.
  • descriptor - A descriptor of what exactly is extracted by the extraction. For default extractions, the supported descriptors are question, context, and answer.
  • extraction_target - Either prompt or response, based on where data should be extracted from (prompt or response, respectively)
  • extraction - Extraction method, can be either RegexExtraction or JSONPathExtraction.

RegexExtraction is an object containing type (string equal to regex) and regex (string containing the regex expression to extract with). for example:

{
  "type": "regex",
  "regex": "<context>(.+)</context>"
}

JSONPathExtraction is an object containing type (string equal to jsonpath) and path (string specifies the JSONPath expression used to navigate and extract specific data from a JSON document). for example:

{
  "type": "jsonpath",
  "regex": "$.context"
}
context_extraction
Object
deprecated

Extraction method for context, can be either RegexExtraction or JSONPathExtraction.

RegexExtraction is an object containing type (string equal to regex) and regex (string containing the regex expression to extract with). for example:

{
  "type": "regex",
  "regex": "<context>(.+)</context>"
}

JSONPathExtraction is an object containing type (string equal to jsonpath) and path (string specifies the JSONPath expression used to navigate and extract specific data from a JSON document). for example:

{
  "type": "jsonpath",
  "regex": "$.context"
}
question_extraction
Object
deprecated

Extraction method for question, can be either RegexExtraction or JSONPathExtraction.

see full explanation about RegexExtraction and JSONPathExtraction in context_extraction field in Get All Projects endpoint.

answer_extraction
Object
deprecated

Extraction method for answer, can be either RegexExtraction or JSONPathExtraction.

see full explanation about RegexExtraction and JSONPathExtraction in context_extraction field in Get All Projects endpoint.

prompt_policy_timeout_ms
int

Maximum runtime for policies on prompt in milliseconds.

response_policy_timeout_ms
int

Maximum runtime for policies on response in milliseconds.

integration_status
string
required

Project integration status, possible values are: pending, failed, success.

size
int
required

The size of the project, possible values are 0, 1, 2, 3. defaults to 0.

Response JSON Example:

[
    {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Test",
        "description": "Project to test",
        "icon": "chatBubbleLeftRight",
        "color": "mustard",
        "organization_id": "123e4567-e89b-12d3-a456-426614174000",
        "is_active": true,
        "policies": [
            {
                "id": "1",
                "policy_type": "aporia_guardrails_test",
                "name": null,
                "enabled": true,
                "condition": {},
                "action": {
                    "type": "block",
                    "response": "Aporia Guardrails Test: AGT detected successfully!"
                }
            }
        ],
        "project_extractions": [
            {
                "descriptor": "question",
                "descriptor_type": "default",
                "extraction": {"regex": "<question>(.+)</question>", "type": "regex"},
                "extraction_target": "prompt",
            },
            {
                "descriptor": "context",
                "descriptor_type": "default",
                "extraction": {"regex": "<context>(.+)</context>", "type": "regex"},
                "extraction_target": "prompt",
            },
            {
                "descriptor": "answer",
                "descriptor_type": "default",
                "extraction": {"regex": "(.+)", "type": "regex"},
                "extraction_target": "response",
            },
        ],
        "context_extraction": {
            "type": "regex",
            "regex": "<context>(.+)</context>"
        },
        "question_extraction": {
            "type": "regex",
            "regex": "<question>(.+)</question>"
        },
        "answer_extraction": {
            "type": "regex",
            "regex": "(.+)"
        },
        "prompt_policy_timeout_ms": null,
        "response_policy_timeout_ms": null,
        "integration_status": "success",
        "size": 0
    }
]

Get Project by ID

Endpoint: GET https://guardrails.aporia.com/api/v1/projects/{project_id}

Headers:

  • Content-Type: application/json
  • Authorization: Bearer + Your copied Aporia API key

Path Parameters:

project_id
uuid

The ID of the project to retrieve.

Response Fields:

id
uuid
required

The project ID.

name
string
required

The project name.

description
string

The project description.

icon
string

The project icon, possible values are codepen, chatBubbleLeftRight, serverStack, academicCap, bookOpen, commandLine, creditCard, rocketLaunch, envelope, identification.

color
string

The project color, possible values are turquoiseBlue, mustard, cornflowerBlue, heliotrope, spray, peachOrange, shocking, white, manz, geraldine.

organization_id
uuid
required

The organization ID.

is_active
bool
required

Boolean indicating whether the project is active or not.

policies
list[PartialPolicy]
required

List of partial policies. Each PartialPolicy has the following attributes: id (uuid), policy_type (string), name (string), enabled (bool), condition (dict), action (dict).

project_extractions
list[ExtractionProperties]
required

List of extractions defined for the project.

see full explanation about project_extractions in Get All Projects endpoint.

context_extraction
Object
deprecated

Extraction method for context, can be either RegexExtraction or JSONPathExtraction.

see full explanation about RegexExtraction and JSONPathExtraction in context_extraction field in Get All Projects endpoint.

question_extraction
Object
deprecated

Extraction method for question, can be either RegexExtraction or JSONPathExtraction.

see full explanation about RegexExtraction and JSONPathExtraction in context_extraction field in Get All Projects endpoint.

answer_extraction
Object
deprecated

Extraction method for answer, can be either RegexExtraction or JSONPathExtraction.

see full explanation about RegexExtraction and JSONPathExtraction in context_extraction field in Get All Projects endpoint.

prompt_policy_timeout_ms
int

Maximum runtime for policies on prompt in milliseconds.

response_policy_timeout_ms
int

Maximum runtime for policies on response in milliseconds.

integration_status
string
required

Project integration status, possible values are: pending, failed, success.

size
int
required

The size of the project, possible values are 0, 1, 2, 3. defaults to 0.

Response JSON Example:

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Test",
    "description": "Project to test",
    "icon": "chatBubbleLeftRight",
    "color": "mustard",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "is_active": true,
    "policies": [
        {
            "id": "1",
            "policy_type": "aporia_guardrails_test",
            "name": null,
            "enabled": true,
            "condition": {},
            "action": {
                "type": "block",
                "response": "Aporia Guardrails Test: AGT detected successfully!"
            }
        }
    ],
    "project_extractions": [
        {
            "descriptor": "question",
            "descriptor_type": "default",
            "extraction": {"regex": "<question>(.+)</question>", "type": "regex"},
            "extraction_target": "prompt",
        },
        {
            "descriptor": "context",
            "descriptor_type": "default",
            "extraction": {"regex": "<context>(.+)</context>", "type": "regex"},
            "extraction_target": "prompt",
        },
        {
            "descriptor": "answer",
            "descriptor_type": "default",
            "extraction": {"regex": "(.+)", "type": "regex"},
            "extraction_target": "response",
        },
    ],
    "context_extraction": {
        "type": "regex",
        "regex": "<context>(.+)</context>"
    },
    "question_extraction": {
        "type": "regex",
        "regex": "<question>(.+)</question>"
    },
    "answer_extraction": {
        "type": "regex",
        "regex": "(.+)"
    },
    "prompt_policy_timeout_ms": null,
    "response_policy_timeout_ms": null,
    "integration_status": "success",
    "size": 1
}

Create Project

Endpoint: POST https://guardrails.aporia.com/api/v1/projects

Headers:

  • Content-Type: application/json
  • Authorization: Bearer + Your copied Aporia API key

Request Fields:

name
string
required

The name of the project.

description
string

The description of the project.

prompt_policy_timeout_ms
int

Maximum runtime for policies on prompt in milliseconds.

response_policy_timeout_ms
int

Maximum runtime for policies on response in milliseconds.

icon
ProjectIcon

Icon of the project, with possible values: codepen, chatBubbleLeftRight, serverStack, academicCap, bookOpen, commandLine, creditCard, rocketLaunch, envelope, identification.

color
ProjectColor

Color of the project, with possible values: turquoiseBlue, mustard, cornflowerBlue, heliotrope, spray, peachOrange, shocking, white, manz, geraldine.

project_extractions
list[ExtractionProperties]
required

List of extractions to define for the project.

see full explanation about project_extractions in Get All Projects endpoint.

context_extraction
Extraction
deprecated

Extraction method for context, defaults to RegexExtraction with a predefined regex: <context>(.+)</context>.

see full explanation about RegexExtraction in context_extraction field in Get All Projects endpoint.

question_extraction
Extraction
deprecated

Extraction method for question, defaults to RegexExtraction with a predefined regex: <question>(.+)</question>.

see full explanation about RegexExtraction in context_extraction field in Get All Projects endpoint.

answer_extraction
Extraction
deprecated

Extraction method for answer, defaults to RegexExtraction with a predefined regex: <answer>(.+)</answer>.

see full explanation about RegexExtraction in context_extraction field in Get All Projects endpoint.

is_active
bool
required

Boolean indicating whether the project is active, defaults to true.

size
int
required

The size of the project, possible values are 0, 1, 2, 3. defaults to 0.

Request JSON Example:

{
    "name": "New Project",
    "description": "Description of the new project",
    "prompt_policy_timeout_ms": 1000,
    "response_policy_timeout_ms": 1000,
    "icon": "chatBubbleLeftRight",
    "color": "turquoiseBlue",
    "project_extractions": [
        {
            "descriptor": "question",
            "descriptor_type": "default",
            "extraction": {"regex": "<question>(.+)</question>", "type": "regex"},
            "extraction_target": "prompt",
        },
        {
            "descriptor": "context",
            "descriptor_type": "default",
            "extraction": {"regex": "<context>(.+)</context>", "type": "regex"},
            "extraction_target": "prompt",
        },
        {
            "descriptor": "answer",
            "descriptor_type": "default",
            "extraction": {"regex": "(.+)", "type": "regex"},
            "extraction_target": "response",
        },
    ],
    "is_active": true,
    "size": 0
}

Response Fields: The response fields will mirror those specified in the ProjectRead object, as described in the previous documentation for retrieving a project.

Response JSON Example: The response json example will be identical to the one in the Get Project by ID endpoint.

Update Project

Endpoint: PUT https://guardrails.aporia.com/api/v1/projects/{project_id}

Headers:

  • Content-Type: application/json
  • Authorization: Bearer + Your copied Aporia API key

Path Parameters:

project_id
uuid

The ID of the project to update.

Request Fields:

name
string

The name of the project.

description
string

The description of the project.

prompt_policy_timeout_ms
int

Maximum runtime for policies on prompt in milliseconds.

response_policy_timeout_ms
int

Maximum runtime for policies on response in milliseconds.

icon
ProjectIcon

Icon of the project, with possible values like codepen, chatBubbleLeftRight, etc.

color
ProjectColor

Color of the project, with possible values like turquoiseBlue, mustard, etc.

project_extractions
list[ExtractionProperties]

List of extractions to define for the project.

see full explanation about project_extractions in Get All Projects endpoint.

context_extraction
Extraction
deprecated

Extraction method for context, defaults to RegexExtraction with a predefined regex.

see full explanation about RegexExtraction in context_extraction field in Get All Projects endpoint.

question_extraction
Extraction
deprecated

Extraction method for question, defaults to RegexExtraction with a predefined regex.

see full explanation about RegexExtraction in context_extraction field in Get All Projects endpoint.

answer_extraction
Extraction
deprecated

Extraction method for answer, defaults to RegexExtraction with a predefined regex.

see full explanation about RegexExtraction in context_extraction field in Get All Projects endpoint.

is_active
bool

Boolean indicating whether the project is active.

size
int
required

The size of the project, possible values are 0, 1, 2, 3. defaults to 0.

allow_schedule_resizing
bool

Boolean indicating whether to allow project resizing (in case we downgrade a project which surpassed the max tokens for the new project size)

remove_scheduled_size
bool

Boolean indicating whether to remove the scheduled size from the project

policy_ids_to_keep
list[str]

Al list of policy ids to keep, in case we downgrade the project.

Request JSON Example:

{
    "name": "Updated Project",
    "description": "Updated description of the project",
    "prompt_policy_timeout_ms": 2000,
    "response_policy_timeout_ms": 2000,
    "icon": "serverStack",
    "color": "cornflowerBlue",
    "project_extractions": [
        {
            "descriptor": "question",
            "descriptor_type": "default",
            "extraction": {"regex": "<question>(.+)</question>", "type": "regex"},
            "extraction_target": "prompt",
        },
        {
            "descriptor": "context",
            "descriptor_type": "default",
            "extraction": {"regex": "<context>(.+)</context>", "type": "regex"},
            "extraction_target": "prompt",
        },
        {
            "descriptor": "answer",
            "descriptor_type": "default",
            "extraction": {"regex": "(.+)", "type": "regex"},
            "extraction_target": "response",
        },
    ],
    "is_active": false
}

Response Fields: The response fields will mirror those specified in the ProjectRead object, as previously documented.

Response JSON Example: The response json example will be identical to the one in the Get Project by ID endpoint.

Delete Project

Endpoint: DELETE https://guardrails.aporia.com/api/v1/projects/{project_id}

Headers:

  • Content-Type: application/json
  • Authorization: Bearer + Your copied Aporia API key

Path Parameters:

project_id
uuid

The ID of the project to delete.

Response Fields: The response fields will mirror those specified in the ProjectRead object, as previously documented.

Response JSON Example: The response json example will be identical to the one in the Get Project by ID endpoint.

Get All Policies of a Project

Endpoint: GET https://guardrails.aporia.com/api/v1/projects/{project_id}/policies

Headers:

  • Content-Type: application/json
  • Authorization: Bearer + Your copied Aporia API key

Path Parameters:

project_id
uuid

The ID of the project whose policies you want to retrieve.

Response Fields:

The response type is a list. each object in the list contains the following fields:

id
str
required

The unique identifier of the policy.

action
ActionConfig
required

Configuration details of the action to be taken by this policy.

ActionConfig is an object containing type field, with possible values of: modify, rephrase, block, passthrough.

For modify action, extra fields will be prefix and suffix, both optional strings. The value in prefix will be added in the beginning of the response, and the value of suffix will be added in the end of the response.

For rephrase action, extra fields will be prompt (required) and llm_model_to_use (optional). prompt is a string that will be used as an addition to the question being sent to the llm. llm_model_to_use is a string representing the llm model that will be used. default value is gpt3.5_1106.

For block action, extra field will be response, which is a required string. This response will replace the original response from the llm.

For passthrough action, there will be no extra fields.

enabled
bool
required

Boolean indicating whether the policy is currently enabled.

condition
dict
required

Conditions under which the policy is triggered. The condition changes per policy.

policy_type
str
required

Type of the policy, defining its nature and behavior.

priority
int
required

The order of priority of this policy among others within the same project. There must be no duplicates.

Response JSON Example:

[
    {
        "id": "1",
        "action": {
            "type": "block",
            "response": "Aporia Guardrails Test: AGT detected successfully!"
        },
        "enabled": true,
        "condition": {},
        "policy_type": "aporia_guardrails_test",
        "priority": 0
    },
    {
        "id": "2",
        "action": {
            "type": "block",
            "response": "Toxicity detected: Message blocked because it includes toxicity. Please rephrase."
        },
        "enabled": true,
        "condition": {
            "type": "toxicity",
            "categories": [
                "harassment",
                "hate",
                "self_harm",
                "sexual",
                "violence"
            ],
            "top_category_theshold": 0.6,
            "bottom_category_theshold": 0.1
        },
        "policy_type": "toxicity_on_prompt",
        "priority": 1
    }
]

Get Policy by ID

Endpoint: GET https://guardrails.aporia.com/api/v1/projects/{project_id}/policies/{policy_id}

Headers:

  • Content-Type: application/json
  • Authorization: Bearer + Your copied Aporia API key

Path Parameters:

project_id
uuid

The ID of the project from which to retrieve a specific policy.

policy_id
uuid

The ID of the policy to retrieve.

Response Fields:

id
str
required

The unique identifier of the policy.

action
ActionConfig
required

Configuration details of the action to be taken by this policy.

ActionConfig is an object containing type field, with possible values of: modify, rephrase, block, passthrough.

For modify action, extra fields will be prefix and suffix, both optional strings. The value in prefix will be added in the beginning of the response, and the value of suffix will be added in the end of the response.

For rephrase action, extra fields will be prompt (required) and llm_model_to_use (optional). prompt is a string that will be used as an addition to the question being sent to the llm. llm_model_to_use is a string representing the llm model that will be used. default value is gpt3.5_1106.

For block action, extra field will be response, which is a required string. This response will replace the original response from the llm.

For passthrough action, there will be no extra fields.

enabled
bool
required

Boolean indicating whether the policy is currently enabled.

condition
dict
required

Conditions under which the policy is triggered. The condition changes per policy.

policy_type
str
required

Type of the policy, defining its nature and behavior.

priority
int
required

The order of priority of this policy among others within the same project. There must be no duplicates.

Response JSON Example:

{
    "id": "2",
    "action": {
        "type": "block",
        "response": "Toxicity detected: Message blocked because it includes toxicity. Please rephrase."
    },
    "enabled": true,
    "condition": {
        "type": "toxicity",
        "categories": [
            "harassment",
            "hate",
            "self_harm",
            "sexual",
            "violence"
        ],
        "top_category_threshold": 0.6,
        "bottom_category_threshold": 0.1
    },
    "policy_type": "toxicity_on_prompt",
    "priority": 1
}

Create Policies

Endpoint: POST https://guardrails.aporia.com/api/v1/projects/{project_id}/policies

Headers:

  • Content-Type: application/json
  • Authorization: Bearer + Your copied Aporia API key

Path Parameters:

project_id
uuid

The ID of the project within which the policy will be created.

Request Fields: The reuqest field is a list. each object in the list contains the following fields:

policy_type
string
required

The type of policy, which defines its behavior and the template it follows.

action
ActionConfig
required

The action that the policy enforces when its conditions are met.

ActionConfig is an object containing type field, with possible values of: modify, rephrase, block, passthrough.

For modify action, extra fields will be prefix and suffix, both optional strings. The value in prefix will be added in the beginning of the response, and the value of suffix will be added in the end of the response.

For rephrase action, extra fields will be prompt (required) and llm_model_to_use (optional). prompt is a string that will be used as an addition to the question being sent to the llm. llm_model_to_use is a string representing the llm model that will be used. default value is gpt3.5_1106.

For block action, extra field will be response, which is a required string. This response will replace the original response from the llm.

For passthrough action, there will be no extra fields.

condition
dict

The conditions under which the policy will trigger its action. defauls to {}. The condition changes per policy.

priority
int

The priority of the policy within the project, affecting the order in which it is evaluated against others. There must be no duplicates.

Request JSON Example:

[{
    "policy_type": "toxicity_on_prompt",
    "action": {
        "type": "block",
        "response": "Toxicity detected: Message blocked because it includes toxicity. Please rephrase."
    },
    "condition": {
        "type": "toxicity",
        "categories": ["harassment", "hate", "self_harm", "sexual", "violence"],
        "top_category_threshold": 0.6,
        "bottom_category_threshold": 0.1
    },
    "enabled": true,
    "priority": 2
}]

Response Fields:

The response fields will mirror those specified in the PolicyRead object, with additional details specific to the newly created policy.

Response JSON Example:

[{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "policy_type": "toxicity_on_prompt",
    "action": {
        "type": "block",
        "response": "Toxicity detected: Message blocked because it includes toxicity. Please rephrase."
    },
    "condition": {
        "type": "toxicity",
        "categories": ["harassment", "hate", "self_harm", "sexual", "violence"],
        "top_category_threshold": 0.6,
        "bottom_category_threshold": 0.1
    },
    "enabled": true,
    "priority": 2
}]

Update Policy

Endpoint: PUT https://guardrails.aporia.com/api/v1/projects/{project_id}/policies/{policy_id}

Headers:

  • Content-Type: application/json
  • Authorization: Bearer + Your copied Aporia API key

Path Parameters:

project_id
uuid

The ID of the project within which the policy will be updated.

policy_id
uuid

The ID of the policy to be updated.

Request Fields:

action
ActionConfig

Specifies the action that the policy enforces when its conditions are met.

ActionConfig is an object containing type field, with possible values of: modify, rephrase, block, passthrough.

For modify action, extra fields will be prefix and suffix, both optional strings. The value in prefix will be added in the beginning of the response, and the value of suffix will be added in the end of the response.

For rephrase action, extra fields will be prompt (required) and llm_model_to_use (optional). prompt is a string that will be used as an addition to the question being sent to the llm. llm_model_to_use is a string representing the llm model that will be used. default value is gpt3.5_1106.

For block action, extra field will be response, which is a required string. This response will replace the original response from the llm.

For passthrough action, there will be no extra fields.

condition
dict

Defines the conditions under which the policy will trigger its action. The condition changes per policy.

enabled
bool

Indicates whether the policy should be active.

priority
int

The priority of the policy within the project, affecting the order in which it is evaluated against other policies. There must be no duplicates.

Request JSON Example:

{
    "action": {
        "type": "block",
        "response": "Updated action response to conditions."
    },
    "condition": {
        "type": "updated_condition",
        "value": "new_condition_value"
    },
    "enabled": false,
    "priority": 1
}

Response Fields:

The response fields will mirror those specified in the PolicyRead object, updated to reflect the changes made to the policy.

Response JSON Example:

{
    "id": "2",
    "action": {
        "type": "block",
        "response": "Updated action response to conditions."
    },
    "condition": {
        "type": "updated_condition",
        "value": "new_condition_value"
    },
    "enabled": false,
    "policy_type": "toxicity_on_prompt",
    "priority": 1
}

Delete Policy

Endpoint: DELETE https://guardrails.aporia.com/api/v1/projects/{project_id}/policies/{policy_id}

Headers:

  • Content-Type: application/json
  • Authorization: Bearer + Your copied Aporia API key

Path Parameters:

project_id
uuid

The ID of the project from which a policy will be deleted.

policy_id
uuid

The ID of the policy to be deleted.

Response Fields:

id
str
required

The unique identifier of the policy.

action
ActionConfig
required

Configuration details of the action that was enforced by this policy.

ActionConfig is an object containing type field, with possible values of: modify, rephrase, block, passthrough.

For modify action, extra fields will be prefix and suffix, both optional strings. The value in prefix will be added in the beginning of the response, and the value of suffix will be added in the end of the response.

For rephrase action, extra fields will be prompt (required) and llm_model_to_use (optional). prompt is a string that will be used as an addition to the question being sent to the llm. llm_model_to_use is a string representing the llm model that will be used. default value is gpt3.5_1106.

For block action, extra field will be response, which is a required string. This response will replace the original response from the llm.

For passthrough action, there will be no extra fields.

enabled
bool
required

Indicates whether the policy was enabled at the time of deletion.

condition
dict
required

The conditions under which the policy triggered its action.

policy_type
str
required

The type of the policy, defining its nature and behavior.

priority
int
required

The priority this policy held within the project, affecting the order in which it was evaluated against other policies. There must be no duplicates.

Response JSON Example:

{
    "id": "2",
    "action": {
        "type": "block",
        "response": "This policy action will no longer be triggered."
    },
    "enabled": false,
    "condition": {
        "type": "toxicity",
        "categories": ["harassment", "hate", "self_harm", "sexual", "violence"]
    },
    "policy_type": "toxicity_on_prompt",
    "priority": 1
}