REST API Documentation

Programmatically manage surveys, responses, themes, and reports with our REST API.

Overview

The SeekWhy REST API allows you to integrate survey management into your applications. Create surveys, collect responses, extract AI-powered themes, and generate reports programmatically.

API Playground

Test endpoints interactively

API Keys

Secure authentication with granular scopes

Fast & Reliable

Low latency responses with 99.9% uptime

Enterprise Ready

Rate limiting, IP allowlisting, audit logs

Base URL: https://seekwhy.ai/api/v1

Authentication

All API requests require an API key. Include it in the Authorization header:

Authorization: Bearer sk_live_YOUR_API_KEY

Create API keys in your Dashboard Settings.

Plan Requirement: API access requires a Team or Enterprise plan.

Rate Limits

API requests are rate limited based on your plan:

Plan	Rate Limit
Team	1,000 requests/hour
Enterprise	10,000 requests/hour

Rate limit headers are included in all responses:

X-RateLimit-Limit - Maximum requests per hour
X-RateLimit-Remaining - Requests remaining
X-RateLimit-Reset - Unix timestamp when limit resets

Endpoints

Surveys

GET/surveysList surveys

POST/surveysCreate survey

GET/surveys/:idGet survey details

POST/surveys/:id/activateActivate survey

POST/surveys/:id/closeClose survey

GET/surveys/:id/statusGet response statistics

Responses

GET/surveys/:id/responsesList responses with answers

GET/surveys/:id/responses/:responseIdGet single response details

Themes & Validation

GET/surveys/:id/themesList themes with validation status

POST/surveys/:id/themes/extractTrigger AI extraction

POST/surveys/:id/themes/:themeId/validateTrigger cross-validation

Distributions

GET/surveys/:id/distributionsList distributions

POST/surveys/:id/distributionsCreate distribution

Reports

GET/surveys/:id/reportsGet AI-generated report

POST/surveys/:id/reportsGenerate new report

Export

GET/surveys/:id/exportExport data (JSON/CSV)

Participants

GET/participantsList organization participants

POST/participantsImport participants (upsert)

Jobs

GET/jobs/:jobIdCheck async job status

Examples

List Surveys (cURL)

curl https://seekwhy.ai/api/v1/surveys \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Create Survey (cURL)

curl -X POST https://seekwhy.ai/api/v1/surveys \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Employee Pulse Survey",
    "questions": [
      {"type": "nps", "text": "How likely are you to recommend our company?"},
      {"type": "open_text", "text": "What could we improve?"}
    ]
  }'

JavaScript

const API_KEY = 'sk_live_YOUR_API_KEY';
const BASE_URL = 'https://seekwhy.ai/api/v1';

async function listSurveys() {
  const response = await fetch(`${BASE_URL}/surveys`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  const { data } = await response.json();
  return data.surveys;
}

async function createSurvey(title, questions) {
  const response = await fetch(`${BASE_URL}/surveys`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ title, questions })
  });
  const { data } = await response.json();
  return data;
}

Python

import requests

API_KEY = 'sk_live_YOUR_API_KEY'
BASE_URL = 'https://seekwhy.ai/api/v1'

headers = {'Authorization': f'Bearer {API_KEY}'}

# List surveys
response = requests.get(f'{BASE_URL}/surveys', headers=headers)
surveys = response.json()['data']['surveys']

# Create survey
survey = requests.post(
    f'{BASE_URL}/surveys',
    headers=headers,
    json={
        'title': 'Quick Pulse',
        'questions': [
            {'type': 'nps', 'text': 'How happy are you at work?'}
        ]
    }
).json()['data']

Error Codes

Code	HTTP Status	Description
`unauthorized`	401	Invalid or missing API key
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource not found
`validation_error`	400	Invalid request data
`rate_limit_exceeded`	429	Too many requests
`internal_error`	500	Server error

OpenAPI Specification

Download our OpenAPI 3.0 specification for use with API tools like Postman, Insomnia, or code generators.

Download OpenAPI Spec (JSON)