v1.0Last updated: February 2026

Qual API Documentation

Build powerful qualitative research integrations with the Qual API. Programmatically manage campaigns, interviews, findings, and knowledge graphs.

API Reference

Complete endpoint reference with request/response examples.

Authentication

API key management, scopes, and session auth.

Webhooks

Real-time events, signature verification, and retries.

Rate Limits

Tier-based limits and quota management.

Quick Start

Make your first API call in under a minute. You'll need an API key from your dashboard.

1Get your API key

Go to Settings → API Keys in the dashboard and create a new secret key.

2List your campaigns

Terminal

curl -H "Authorization: Bearer qual_sk_your_key_here" \
  https://www.qual.cx/api/v1/campaigns

3Create a campaign

Terminal

curl -X POST \
  -H "Authorization: Bearer qual_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "User Onboarding Research",
    "objectives": "Understand pain points in the onboarding flow",
    "campaign_mode": "research",
    "max_questions": 12
  }' \
  https://www.qual.cx/api/v1/campaigns

Authentication

All protected endpoints require an Authorization header. The API supports two methods.

API Keys

Generate API keys from your dashboard or via the /v1/api-keys endpoint. Three key types are available:

Type	Prefix	Use Case
Secret	`qual_sk_`	Server-side integrations
Public	`qual_pk_`	Client-side (limited scopes)
Scoped	`qual_scope_`	Fine-grained access control

curl -H "Authorization: Bearer qual_sk_a1b2c3d4e5f6..." \
  https://www.qual.cx/api/v1/campaigns

Important: Keys are hashed with SHA-256 before storage. The plaintext key is only returned once at creation. Store it securely.

Session Auth (Fallback)

Standard Supabase JWT tokens are accepted as a fallback. Session users receive wildcard scopes and bypass scope checks.

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://www.qual.cx/api/v1/campaigns

Permission Scopes

API keys are assigned granular scopes that control access to specific resources.

Scope	Description
`campaigns:read`	View campaigns and their settings
`campaigns:write`	Create and update campaigns
`campaigns:delete`	Delete campaigns
`campaigns:publish`	Publish and pause campaigns
`interviews:read`	View interviews and messages
`interviews:write`	Create interviews
`findings:read`	View findings and analysis
`findings:write`	Create and update findings
`graph:read`	View knowledge graph data
`graph:share`	Share graphs publicly
`teams:read`	View team details and members
`teams:write`	Manage team settings and members
`webhooks:manage`	Create and manage webhooks
`admin:read`	View admin-level data

Response Format

All responses follow a consistent envelope format.

Success

{
  "data": { ... }
}

Paginated

{
  "data": [ ... ],
  "pagination": {
    "next_cursor": "eyJjcmVhdGVkX2F0Ijoi...",
    "has_more": true,
    "total_count": 42
  }
}

Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      { "field": "title", "message": "Required" }
    ]
  }
}

Base URL

https://www.qual.cx/api/v1

All endpoints documented in this reference are relative to this base URL.

Ready to integrate?

Explore the full API reference to start building your integration.

API Reference