Projects API
This REST API documentation outlines methods for managing projects and policies on the Aporia platform. It includes detailed descriptions of endpoints for creating, updating, and deleting projects and their associated policies, complete with example requests and responses.
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:
The project ID.
The project name.
The project description.
The project icon, possible values are codepen
, chatBubbleLeftRight
, serverStack
, academicCap
, bookOpen
, commandLine
, creditCard
, rocketLaunch
, envelope
, identification
.
The project color, possible values are turquoiseBlue
, mustard
, cornflowerBlue
, heliotrope
, spray
, peachOrange
, shocking
, white
, manz
, geraldine
.
The organization ID.
Boolean indicating whether the project is active or not.
List of policies, each Policy has the following attributes: id
(uuid), policy_type
(string), name
(string), enabled
(bool), condition
(dict), action
(dict).
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"
}
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.
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.
Maximum runtime for policies on prompt in milliseconds.
Maximum runtime for policies on response in milliseconds.
Project integration status, possible values are: pending
, failed
, success
.
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!"
}
}
],
"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:
The ID of the project to retrieve.
Response Fields:
The project ID.
The project name.
The project description.
The project icon, possible values are codepen
, chatBubbleLeftRight
, serverStack
, academicCap
, bookOpen
, commandLine
, creditCard
, rocketLaunch
, envelope
, identification
.
The project color, possible values are turquoiseBlue
, mustard
, cornflowerBlue
, heliotrope
, spray
, peachOrange
, shocking
, white
, manz
, geraldine
.
The organization ID.
Boolean indicating whether the project is active or not.
List of partial policies. Each PartialPolicy has the following attributes: id
(uuid), policy_type
(string), name
(string), enabled
(bool), condition
(dict), action
(dict).
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.
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.
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.
Maximum runtime for policies on prompt in milliseconds.
Maximum runtime for policies on response in milliseconds.
Project integration status, possible values are: pending
, failed
, success
.
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!"
}
}
],
"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:
The name of the project.
The description of the project.
Maximum runtime for policies on prompt in milliseconds.
Maximum runtime for policies on response in milliseconds.
Icon of the project, with possible values: codepen
, chatBubbleLeftRight
, serverStack
, academicCap
, bookOpen
, commandLine
, creditCard
, rocketLaunch
, envelope
, identification
.
Color of the project, with possible values: turquoiseBlue
, mustard
, cornflowerBlue
, heliotrope
, spray
, peachOrange
, shocking
, white
, manz
, geraldine
.
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.
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.
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.
Boolean indicating whether the project is active, defaults to true
.
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",
"context_extraction": {
"type": "regex",
"regex": "<context>(.+)</context>"
},
"question_extraction": {
"type": "regex",
"regex": "<question>(.+)</question>"
},
"answer_extraction": {
"type": "regex",
"regex": "<answer>(.+)</answer>"
},
"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:
The ID of the project to update.
Request Fields:
The name of the project.
The description of the project.
Maximum runtime for policies on prompt in milliseconds.
Maximum runtime for policies on response in milliseconds.
Icon of the project, with possible values like codepen
, chatBubbleLeftRight
, etc.
Color of the project, with possible values like turquoiseBlue
, mustard
, etc.
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.
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.
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.
Boolean indicating whether the project is active.
The size of the project, possible values are 0
, 1
, 2
, 3
. defaults to 0
.
Boolean indicating whether to allow project resizing (in case we downgrade a project which surpassed the max tokens for the new project size)
Boolean indicating whether to remove the scheduled size from the project
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",
"context_extraction": {
"type": "regex",
"regex": "<context>(.+)</context>"
},
"question_extraction": {
"type": "regex",
"regex": "<question>(.+)</question>"
},
"answer_extraction": {
"type": "regex",
"regex": "<answer>(.+)</answer>"
},
"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:
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:
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:
The unique identifier of the policy.
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.
Boolean indicating whether the policy is currently enabled.
Conditions under which the policy is triggered. The condition changes per policy.
Type of the policy, defining its nature and behavior.
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:
The ID of the project from which to retrieve a specific policy.
The ID of the policy to retrieve.
Response Fields:
The unique identifier of the policy.
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.
Boolean indicating whether the policy is currently enabled.
Conditions under which the policy is triggered. The condition changes per policy.
Type of the policy, defining its nature and behavior.
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:
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:
The type of policy, which defines its behavior and the template it follows.
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.
The conditions under which the policy will trigger its action. defauls to {}
. The condition changes per policy.
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:
The ID of the project within which the policy will be updated.
The ID of the policy to be updated.
Request Fields:
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.
Defines the conditions under which the policy will trigger its action. The condition changes per policy.
Indicates whether the policy should be active.
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:
The ID of the project from which a policy will be deleted.
The ID of the policy to be deleted.
Response Fields:
The unique identifier of the policy.
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.
Indicates whether the policy was enabled at the time of deletion.
The conditions under which the policy triggered its action.
The type of the policy, defining its nature and behavior.
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
}