Get Policy Evaluations

Sprint 3

Get policy evaluation history (audit trail) for a policy.

Endpoint

GET /api/v1/policies/{policy_id}/evaluations

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>

Path Parameters

Parameter	Type	Required	Description
policy_id	integer	Yes	Policy ID

Query Parameters

Parameter	Type	Required	Description
user_id	integer	No	Filter by user ID
query_id	integer	No	Filter by query ID
start_date	string	No	Start date (ISO 8601 format, e.g., "2024-12-01T00:00:00Z")
end_date	string	No	End date (ISO 8601 format, e.g., "2024-12-31T23:59:59Z")
page	integer	No	Page number (default: 1)

Response

Success (200)

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1,
        "policy_id": 1,
        "policy_rule_id": 1,
        "user_id": 5,
        "query_id": 10,
        "data_source_id": 1,
        "dataset_id": null,
        "evaluation_result": "allowed",
        "action_taken": "filtered_rows",
        "evaluation_details": {
          "rows_filtered": 50,
          "rows_returned": 10
        },
        "evaluated_at": "2024-12-01T10:00:00Z",
        "ip_address": "192.168.1.1",
        "metadata": {}
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_items": 150,
      "total_pages": 8
    }
  },
  "message": "Policy evaluations retrieved successfully"
}

Error Codes

Status	Code	Description
400	BAD_REQUEST	Invalid date format (use ISO 8601)
401	UNAUTHORIZED	Invalid or missing authentication token
404	NOT_FOUND	Policy not found
500	INTERNAL_SERVER_ERROR	Internal server error

Evaluation Results

• allowed: Policy allowed the operation
• denied: Policy denied the operation
• modified: Policy modified the operation (e.g., filtered rows, masked data)

Features

• Filter by user, query, and date range
• Pagination support
• Includes evaluation details and actions taken
• IP address tracking
• Organization-scoped access control

Date Format

Dates must be in ISO 8601 format:

• 2024-12-01T00:00:00Z
• 2024-12-01T00:00:00+00:00

Example

curl -X GET "https://api.rivergen.com/api/v1/policies/1/evaluations?start_date=2024-12-01T00:00:00Z&end_date=2024-12-31T23:59:59Z&page=1" \
  -H "Authorization: Bearer <access_token>"

Related Endpoints

• Get Policy - Get policy details
• List Policies - List all policies