Surveys API

Manage survey templates for structured data collection during change requests.

Space-scoped template CRUD requires Space Admin permissions. Template lookup and read operations require authentication.

Endpoints Overview

Method	Endpoint	Description
GET	/spaces/{slug}/survey-templates	List templates
POST	/spaces/{slug}/survey-templates	Create template
GET	/survey-templates/{template_id}	Get template
PATCH	/survey-templates/{template_id}	Update template
DELETE	/survey-templates/{template_id}	Deactivate template
GET	/products/{product_id}/survey-template	Get product's template

---

List Templates

GET /spaces/{slug}/survey-templates?include_inactive=false

Requires: Space member

Parameter	Type	Default	Description
include_inactive	bool	false	Include deactivated templates

Returns: SurveyTemplateResponse[]

---

Create Template

POST /spaces/{slug}/survey-templates

Requires: Space Admin

Request Body

{
  "name": "Change Impact Assessment",
  "description": "Collects impact details for change requests",
  "fields": [
    {
      "name": "impact_area",
      "label": "Impact Area",
      "type": "select",
      "options": ["Performance", "Security", "Data Quality"],
      "required": true
    },
    {
      "name": "justification",
      "label": "Justification",
      "type": "textarea",
      "required": true
    },
    {
      "name": "rollback_plan",
      "label": "Rollback Plan",
      "type": "text",
      "required": false
    }
  ]
}

Field	Type	Required	Description
name	string	✅	Template name
description	string	—	Template description
fields	FieldDefinition[]	✅	Form field definitions

Returns 201 Created with the SurveyTemplateResponse.

---

Get Template

GET /survey-templates/{template_id}

Returns 404 if not found.

---

Update Template

PATCH /survey-templates/{template_id}

All fields are optional — only provided fields are updated.

{
  "name": "Updated Survey",
  "fields": [],
  "is_active": false
}

---

Deactivate Template

DELETE /survey-templates/{template_id}

Soft-deletes the template (sets is_active = false). Returns 204 No Content.

---

Get Product Survey Template

GET /products/{product_id}/survey-template

Returns the active survey template configured for a product's change requests. Returns 204 No Content if no template is configured.

---

Response Model

SurveyTemplateResponse

Field	Type	Description
id	UUID	Template identifier
name	string	Template name
description	string | null	Description
fields	object[]	Field definitions
is_active	bool	Whether the template is active
space_id	UUID	Space scope
created_at	datetime	Creation timestamp
updated_at	datetime	Last update