Quickstart

Build a survey, publish it, and collect your first response in about five minutes.

Prerequisites

• A Krafter account (invite-only — request access at app.krafter.dev)
• An API key with surveys:write scope, or use the dashboard

Step 1: Create a survey

You can create a survey from the dashboard or via the API.

Using the dashboard

1. Log in and navigate to Surveys.
2. Click New Survey.
3. Choose a name and slug (e.g., product-feedback).
4. Pick Manual mode (you author the questions) or AI mode (the AI asks follow-ups based on each respondent's answers).
5. Click Create.

Using the API

curl -X POST https://app.krafter.dev/api/v1/surveys \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product feedback",
    "slug": "product-feedback",
    "mode": "manual"
  }'

// 201 Created
{
  "data": {
    "id": "b1c2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "name": "Product feedback",
    "slug": "product-feedback",
    "mode": "manual",
    "status": "draft",
    "settings": {},
    "ai_config": {},
    "response_count": 0,
    "created_at": "2026-05-10T10:00:00Z",
    "updated_at": "2026-05-10T10:00:00Z"
  }
}

The survey starts as draft — it cannot accept responses until you activate it (Step 3).

Step 2: Add questions

Add one or more questions. Each question needs a type, a title, and a position (1-based ordering).

SURVEY_ID="b1c2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e"

# A free-text question
curl -X POST https://app.krafter.dev/api/v1/surveys/$SURVEY_ID/questions \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "title": "What did you build with Krafter?",
    "position": 1
  }'

# A single-choice question
curl -X POST https://app.krafter.dev/api/v1/surveys/$SURVEY_ID/questions \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "choice",
    "title": "How did you hear about us?",
    "options": ["Search", "Social", "Friend", "Other"],
    "position": 2
  }'

# An NPS question
curl -X POST https://app.krafter.dev/api/v1/surveys/$SURVEY_ID/questions \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "nps",
    "title": "How likely are you to recommend Krafter?",
    "position": 3
  }'

Twelve question types are supported: text, email, choice, multi_choice, rating, nps, scale, slider, matrix, ranking, yes_no, date. See API → Questions for the full reference.

Step 3: Activate the survey

curl -X POST https://app.krafter.dev/api/v1/surveys/$SURVEY_ID/activate \
  -H "Authorization: Bearer kr_live_abc123def456"

{
  "data": {
    "id": "b1c2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "status": "active"
  }
}

The survey now accepts responses at https://app.krafter.dev/api/v1/surveys/product-feedback/responses and via the embed widget.

Step 4: Collect a response

The public response API is unauthenticated and slug-based — no API key required. Each response is created in three calls: start → save progress → complete.

Start a response

curl -X POST https://app.krafter.dev/api/v1/surveys/product-feedback/responses \
  -H "Content-Type: application/json" \
  -d '{}'

// 201 Created
{
  "data": {
    "id": "f1a2b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
    "survey_id": "b1c2d3e4-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
    "status": "in_progress",
    "answers": {},
    "started_at": "2026-05-10T10:05:00Z"
  }
}

Save the id — you'll use it for the next two calls.

Save answers

You can save progress at any time. The answers object is keyed by question id.

RESPONSE_ID="f1a2b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c"

curl -X PATCH https://app.krafter.dev/api/v1/surveys/product-feedback/responses/$RESPONSE_ID \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "<question-id-1>": "A landing page form",
      "<question-id-2>": "Search",
      "<question-id-3>": 9
    }
  }'

Multiple PATCH calls are allowed — each one overwrites answers. This is how the embed widget supports save-and-resume.

Complete the response

curl -X POST https://app.krafter.dev/api/v1/surveys/product-feedback/responses/$RESPONSE_ID/complete \
  -H "Content-Type: application/json"

{
  "data": {
    "id": "f1a2b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
    "status": "completed",
    "completed_at": "2026-05-10T10:06:30Z"
  }
}

The survey's response_count increments, completion webhooks fire, and the response is final.

Rate limit (public)

The public response endpoints use the public bucket — 200 requests / 60 seconds per client IP, shared with form submissions, email tracking, and webhook ingest. See Rate limits for details.

Step 5: Read responses

Switch back to an authenticated context (Bearer token with surveys:read).

curl https://app.krafter.dev/api/v1/surveys/$SURVEY_ID/responses \
  -H "Authorization: Bearer kr_live_abc123def456"

Or stream all responses as CSV:

curl -X POST https://app.krafter.dev/api/v1/surveys/$SURVEY_ID/responses/export \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"format": "csv"}' \
  -o responses.csv

Next steps

• Embed it on a page — see Embedding for the <script src="/surveys.js"> widget
• Invite a specific audience — see Respondents
• Let AI ask the questions — see AI features
• Wire up webhooks — see Webhooks API
• Analyze results — see Analytics API