Surveys API¶

!!! info "TL;DR" CRUD operations for surveys, questions, and responses. Create surveys, distribute to users, collect responses, analyze results. Admin-only endpoints for survey management.

List Surveys¶

Get all surveys with optional filters.

GET /api/surveys

Authentication: Required (admin)

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50)
`status`	enum	`draft`, `published`, `paused`, `archived`

Example Request:

curl "https://canviq.app/api/surveys?status=published" \
  -H "Authorization: Bearer admin-api-key"

Example Response:

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Q1 Product Feedback",
      "status": "published",
      "response_count": 150,
      "completion_rate": 0.87,
      "created_at": "2026-01-15T10:00:00Z",
      "closes_at": "2026-03-31T23:59:59Z"
    }
  ],
  "meta": {
    "total": 12
  }
}

Get Survey¶

Get full survey details including questions.

GET /api/surveys/:id

Authentication: Optional (public surveys), Required (draft surveys)

Query Parameters:

Parameter	Type	Description
`expand`	string	`questions`, `targeting`, `analytics`

Example Request:

curl "https://canviq.app/api/surveys/550e8400-e29b-41d4-a716-446655440000?expand=questions"

Example Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Q1 Product Feedback",
    "description": "Help us improve your experience",
    "status": "published",
    "questions": [
      {
        "id": "uuid",
        "type": "nps",
        "text": "How likely are you to recommend us?",
        "required": true,
        "order": 1
      },
      {
        "id": "uuid",
        "type": "multiple_choice",
        "text": "What feature would you like next?",
        "required": false,
        "options": [
          { "id": "uuid", "text": "Dark mode", "order": 1 },
          { "id": "uuid", "text": "API access", "order": 2 },
          { "id": "uuid", "text": "Mobile app", "order": 3 }
        ],
        "order": 2
      },
      {
        "id": "uuid",
        "type": "text",
        "text": "Any additional feedback?",
        "required": false,
        "order": 3
      }
    ],
    "response_count": 150,
    "completion_rate": 0.87,
    "avg_completion_time": 120,
    "created_at": "2026-01-15T10:00:00Z"
  }
}

Create Survey¶

Create a new survey.

POST /api/surveys

Authentication: Required (admin)

Request Body:

{
  "title": "Q1 Product Feedback",
  "description": "Help us improve your experience",
  "questions": [
    {
      "type": "nps",
      "text": "How likely are you to recommend us?",
      "required": true
    },
    {
      "type": "multiple_choice",
      "text": "What feature would you like next?",
      "options": ["Dark mode", "API access", "Mobile app"],
      "required": false
    },
    {
      "type": "text",
      "text": "Any additional feedback?",
      "required": false
    }
  ],
  "settings": {
    "allow_multiple_responses": false,
    "show_branding": true,
    "redirect_url": "https://example.com/thank-you"
  }
}

Example Response:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "draft",
    "url": "https://canviq.app/surveys/550e8400-e29b-41d4-a716-446655440000"
  }
}

Update Survey¶

Update survey details (only drafts can be modified).

PATCH /api/surveys/:id

Authentication: Required (admin)

Request Body:

{
  "title": "Updated Survey Title",
  "description": "Updated description"
}

Active surveys cannot have questions modified. To change questions, pause the survey, create a new version, and close the old one.

Publish Survey¶

Change survey status from draft to published.

POST /api/surveys/:id/publish

Authentication: Required (admin)

Example Request:

curl -X POST https://canviq.app/api/surveys/550e8400-e29b-41d4-a716-446655440000/publish \
  -H "Authorization: Bearer admin-api-key"

Once published, the survey can receive responses.

Submit Response¶

Submit a response to a survey.

POST /api/surveys/:id/responses

Authentication: Required (user identity is derived from the session)

!!! danger "Security Note" The user_id is never accepted in the request body. The server determines the respondent from the authenticated session to prevent user impersonation.

Request Body:

{
  "answers": [
    {
      "question_id": "uuid",
      "value": 9
    },
    {
      "question_id": "uuid",
      "value": ["Dark mode", "API access"]
    },
    {
      "question_id": "uuid",
      "value": "Great product overall, just needs a few improvements"
    }
  ]
}

Fields:

Field	Type	Required	Description
`answers`	array	Yes	Array of question responses

Answer value type depends on question type:

nps, rating → number
multiple_choice → string or string[] (if multiple selection allowed)
text, email → string

Example Response:

{
  "data": {
    "response_id": "uuid",
    "survey_id": "550e8400-e29b-41d4-a716-446655440000",
    "submitted_at": "2026-02-10T16:00:00Z"
  }
}

List Responses¶

Get responses for a survey (admin only).

GET /api/surveys/:id/responses

Authentication: Required (admin)

Query Parameters:

Parameter	Type	Description
`page`	number	Page number
`limit`	number	Items per page
`start_date`	string	Filter by submission date (ISO 8601)
`end_date`	string	Filter by submission date
`sentiment`	enum	`positive`, `neutral`, `negative`

Example Request:

curl "https://canviq.app/api/surveys/550e8400-e29b-41d4-a716-446655440000/responses?sentiment=negative" \
  -H "Authorization: Bearer admin-api-key"

Get Analytics¶

Get aggregated analytics for a survey.

GET /api/surveys/:id/analytics

Authentication: Required (admin)

Query Parameters:

Parameter	Type	Description
`metrics`	string	Comma-separated: `completion_rate`, `nps_score`, `sentiment`

Example Request:

curl "https://canviq.app/api/surveys/550e8400-e29b-41d4-a716-446655440000/analytics?metrics=nps_score,sentiment" \
  -H "Authorization: Bearer admin-api-key"

Example Response:

{
  "data": {
    "response_count": 150,
    "completion_rate": 0.87,
    "avg_completion_time": 120,
    "nps_score": 42,
    "sentiment": {
      "overall": 0.65,
      "positive_count": 90,
      "neutral_count": 40,
      "negative_count": 20
    },
    "breakdown_by_question": [
      {
        "question_id": "uuid",
        "question_text": "What feature would you like next?",
        "responses": {
          "Dark mode": 80,
          "API access": 50,
          "Mobile app": 20
        }
      }
    ]
  }
}

Delete Survey¶

Delete a survey and all responses (use with caution).

DELETE /api/surveys/:id

Authentication: Required (admin)

Query Parameters:

Parameter	Type	Description
`force`	boolean	Delete even if responses exist

By default, surveys with responses cannot be deleted. Set force=true to override.

What's Next¶

MCP Tools API — AI agent access to surveys
Survey Features — Question types, logic, targeting
Sentiment Analysis — Claude-powered analysis