Fides Documentation – Ethyca
API reference
This feature requires Fides Cloud or Fides Enterprise. For more information, talk to our solutions team. (opens in a new tab)
All privacy assessment endpoints are under the base path /api/v1/plus/privacy-assessments. All requests require a valid Fides authentication token in the Authorization header.
Templates
List templates
GET /api/v1/plus/privacy-assessments/templates
Returns all available assessment templates.
Response fields:
| Field | Type | Description |
|---|---|---|
id |
string | Template identifier (e.g., gdpr_dpia) |
name |
string | Human-readable template name |
description |
string | Template description and regulatory context |
question_groups |
array | List of question group objects |
Get template
GET /api/v1/plus/privacy-assessments/templates/{template_id}
Returns a single template including all question groups and questions.
Assessments
Create assessments
POST /api/v1/plus/privacy-assessments/
Queues generation jobs for one or more system-template combinations.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
template_ids |
array of strings | Yes | One or more template keys to generate |
system_ids |
array of strings | No | Scope to specific systems. Omit for all systems. |
ai_enabled |
boolean | No | Enable AI pre-fill. Default: true |
high_risk_only |
boolean | No | Only generate for high-risk systems. Default: false |
Response: Array of created assessment objects with task IDs.
List assessments
GET /api/v1/plus/privacy-assessments/
Returns all assessments. Supports filtering by status, template_id, and system_id query parameters.
Get assessment
GET /api/v1/plus/privacy-assessments/{assessment_id}
Returns a single assessment with all question groups and their current answers.
Key response fields:
| Field | Type | Description |
|---|---|---|
id |
string | Assessment ID (prefix: pri_) |
status |
string | in_progress, completed, or outdated |
risk_level |
string or null | high if the system matched high-risk triggers, otherwise null |
completeness |
float | Percentage of questions with complete answers (0–100) |
template_id |
string | The template this assessment was generated from |
system_id |
string | The system this assessment covers |
question_groups |
array | Question groups with their questions and answers |
Delete assessment
DELETE /api/v1/plus/privacy-assessments/{assessment_id}
Permanently deletes an assessment and all its answers and evidence. This action cannot be undone.
Re-evaluation
Re-evaluate assessments
POST /api/v1/plus/privacy-assessments/re-evaluate
Queues re-evaluation tasks for one or more outdated assessments.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
assessment_ids |
array of strings | No | Specific assessments to re-evaluate. Omit for all outdated. |
Tasks
List tasks
GET /api/v1/plus/privacy-assessments/tasks
Returns all assessment generation and re-evaluation tasks.
Key response fields:
| Field | Type | Description |
|---|---|---|
id |
string | Task ID |
status |
string | pending, running, complete, or failed |
progress |
float | Completion percentage (0–100) |
error |
string | Error message if status is failed |
assessment_id |
string | ID of the assessment created by this task |
Get task
GET /api/v1/plus/privacy-assessments/tasks/{task_id}
Returns a single task.
Retry task
POST /api/v1/plus/privacy-assessments/tasks/{task_id}/retry
Retries a failed task. Returns the new task object.
Answers
Update answer
PUT /api/v1/plus/privacy-assessments/{assessment_id}/questions/{question_id}
Updates the answer for a specific question. Creates a new version with source user_input.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
answer |
string | Yes | The new answer text |
Get answer history
GET /api/v1/plus/privacy-assessments/{assessment_id}/questions/{question_id}/history
Returns all versions of a question's answer in reverse chronological order.
Key response fields per version:
| Field | Type | Description |
|---|---|---|
id |
string | Version ID |
answer |
string | Answer text at this version |
source |
string | system, ai_analysis, user_input, or team_input |
created_at |
datetime | When this version was created |
created_by |
string | User ID or ai_agent |
Revert answer
POST /api/v1/plus/privacy-assessments/{assessment_id}/questions/{question_id}/revert
Creates a new answer version that restores the text from a previous version.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
version_id |
string | Yes | The version to restore |
Audit log
Get audit log
GET /api/v1/plus/privacy-assessments/{assessment_id}/audit-log
Returns a complete audit log of all changes to an assessment in reverse chronological order.
Key response fields:
| Field | Type | Description |
|---|---|---|
actor |
string | User ID or ai_agent |
action |
string | Type of change (e.g., answer_updated, answer_reverted) |
question_id |
string | The question that was changed |
timestamp |
datetime | When the change occurred |
details |
object | Additional context about the change |
Evidence
Get evidence for a question group
GET /api/v1/plus/privacy-assessments/{assessment_id}/question-groups/{group_id}/evidence
Returns all evidence items for a question group, grouped by evidence type.
Key response fields:
| Field | Type | Description |
|---|---|---|
type |
string | system, privacy_declaration, data_use, or dataset |
label |
string | Display label for the evidence item |
value |
string | The cited data value |
source_id |
string | ID of the Fides record this evidence came from |
created_at |
datetime | When this evidence was recorded |
Questionnaire
Send questionnaire
POST /api/v1/plus/privacy-assessments/{assessment_id}/questionnaire
Sends unanswered questions to the configured Slack channel.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
channel |
string | No | Override the default Slack channel |
question_ids |
array of strings | No | Send only specific questions. Omit for all needs_input questions. |
Get questionnaire status
GET /api/v1/plus/privacy-assessments/{assessment_id}/questionnaire
Returns the status of each sent question: whether it has a response and when the response was received.
Send reminders
POST /api/v1/plus/privacy-assessments/{assessment_id}/questionnaire/reminders
Sends Slack reminder messages to threads where no response has been received. Takes no request body.
Questionnaire tone
Get tone
GET /api/v1/plus/privacy-assessments/questionnaire/tone
Returns the current questionnaire tone prompt.
Update tone
PUT /api/v1/plus/privacy-assessments/questionnaire/tone
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
tone_prompt |
string | Yes | Custom instructions for how to phrase questions |
Reset tone to default
POST /api/v1/plus/privacy-assessments/questionnaire/tone/reset
Resets the tone prompt to the system default.
PDF export
Export PDF
GET /api/v1/plus/privacy-assessments/{assessment_id}/pdf
Query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
mode |
string | internal |
Export mode: internal (with evidence) or external (clean Q&A) |
Returns the assessment as a PDF file (Content-Type: application/pdf).
Configuration
Get configuration
GET /api/v1/plus/privacy-assessments/config
Returns the current assessment configuration.
Update configuration
PUT /api/v1/plus/privacy-assessments/config
Request body:
| Field | Type | Description |
|---|---|---|
assessment_model |
string | AI model identifier for assessment generation |
chat_model |
string | AI model identifier for questionnaire chat |
reassessment_enabled |
boolean | Enable automatic periodic re-evaluation |
reassessment_cron |
string | Cron expression for reassessment schedule |
Get configuration defaults
GET /api/v1/plus/privacy-assessments/config/defaults
Returns the default values for all configuration fields.