Dagu
Developer API

Build with Dagu

Integrate powerful survey capabilities into your applications with our simple REST API. Submit responses, receive webhooks, and build custom workflows.

Getting Started

The Dagu API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

BASE URL
https://consolebackend.akmicroservice.com/api
Authentication

Public survey submissions do not require authentication. Each survey has a unique endpoint token (like Formspree) for easy integration.

Quick Start: When you publish a survey, you'll get a unique endpoint like/api/f/YOUR_SURVEY_TOKEN. Just POST your form data to it - no API keys needed!
Note: For administrative operations (creating surveys, fetching responses), you'll need an API key. Contact support to enable API key generation for your account.
API Reference
POST/f/YOUR_SURVEY_TOKEN

Submit a response to your survey using its unique token. Each survey gets a permanent endpoint URL when published.

REQUEST BODY (Simple Key-Value Format)
{
  "name": "John Doe",
  "email": "john@example.com",
  "message": "Your message here",
  "rating": "5"
}
RESPONSE (200 OK)
{
  "success": true,
  "message": "Survey response submitted successfully",
  "data": {
    "response_id": 12345,
    "survey_id": 67890,
    "submitted_at": "2025-12-26T20:30:00Z"
  }
}
Code Examples

cURL

curl -X POST 'https://consolebackend.akmicroservice.com/api/f/YOUR_SURVEY_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Great product!"
  }'

JavaScript (fetch)

const response = await fetch(
  'https://consolebackend.akmicroservice.com/api/f/YOUR_SURVEY_TOKEN',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'John Doe',
      email: 'john@example.com',
      message: 'Great product!'
    })
  }
);

const data = await response.json();
console.log('Response:', data);

Python (requests)

import requests

url = 'https://consolebackend.akmicroservice.com/api/f/YOUR_SURVEY_TOKEN'
payload = {
    'name': 'John Doe',
    'email': 'john@example.com',
    'message': 'Great product!'
}

response = requests.post(url, json=payload)
print(response.json())

PHP

<?php
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://consolebackend.akmicroservice.com/api/f/YOUR_SURVEY_TOKEN');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'message' => 'Great product!'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));
Advanced Features

Custom Thank You Redirect

Redirect submitters to a custom URL after successful submission by including the _next parameter.

{
  "name": "John Doe",
  "email": "john@example.com",
  "_next": "https://yoursite.com/thank-you"
}
✓ The API will return the redirect URL in the response under the redirect field.

Email Notifications

Automatically receive email notifications when someone submits a response. Configure in survey settings.

  • Beautiful HTML email templates
  • Includes all response data
  • Link to view full response in dashboard
  • Custom notification email address supported

Autoresponder Emails

Send automatic thank you emails to survey respondents. Emails are sent to any email address detected in the submission.

  • Customizable subject line and message
  • Auto-detects email and name fields
  • Personalized with respondent's name
  • Branded HTML template
✓ Configure autoresponder message in survey settings under metadata.autoresponder

Automatic Email Validation

Any field containing an email address is automatically validated, regardless of field type.

✓ Works with text fields, email fields, and any custom field names - emails are detected and validated automatically.

Response Search & Filters

Access survey responses programmatically with powerful search and filter options.

ENDPOINT
GET/api/surveys/{id}/responses
QUERY PARAMETERS
  • search - Search across all answers and metadata
  • status - Filter by response status (completed, partial, etc.)
  • start_date & end_date - Date range filtering
  • sort_by - Sort by created_at, completion_time, etc.
  • sort_order - asc or desc
  • per_page - Results per page (max 100)

Enhanced Export

Export responses with comprehensive metadata including IP addresses, user agents, timestamps, and survey versions.

  • CSV export with all metadata columns
  • JSON export with nested data structures
  • Includes submission metadata (IP, user agent, version)

Multi-Step Form Support

Break long surveys into multiple steps and save progress along the way. Partial submissions are saved as drafts.

STEP 1: START A MULTI-STEP FORM
// First step - save as draft
fetch('/api/f/YOUR_TOKEN', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: "John Doe",
    email: "john@example.com",
    partial: true,
    current_step: 1,
    total_steps: 3
  })
})
RESPONSE
{
  "message": "Draft saved successfully",
  "response_id": 123,
  "session_id": "abc123xyz...",
  "status": "draft",
  "current_step": 1,
  "total_steps": 3,
  "is_complete": false
}
STEP 2 & 3: CONTINUE & COMPLETE
// Continue with session_id (merges answers)
fetch('/api/f/YOUR_TOKEN', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    session_id: "abc123xyz...",
    company: "Acme Corp",
    partial: true,  // Still a draft
    current_step: 2,
    total_steps: 3
  })
})

// Final step - complete submission
fetch('/api/f/YOUR_TOKEN', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    session_id: "abc123xyz...",
    rating: "5",
    partial: false,  // Mark as complete
    current_step: 3,
    total_steps: 3
  })
})
// Triggers emails, webhooks, and returns redirect URL
✓ Answers from all steps are automatically merged. Emails and webhooks only trigger on final completion.

Server-Side Conditional Logic

NEW

Conditional logic (skip logic) is automatically processed on the server when enabled. Questions that should be hidden based on previous answers are filtered out before saving.

HOW IT WORKS
  • Conditions are evaluated based on submitted answers
  • Hidden questions are automatically filtered from the response
  • Required field validation only applies to visible questions
  • Skipped questions are tracked in response metadata
CONDITION STRUCTURE
// Example: Show "follow_up" question only if rating is 5
{
  "conditions": [
    {
      "sourceQuestionRef": "question-rating-uuid",
      "operator": "equals",
      "value": "5",
      "effect": "show"
    }
  ]
}

// Supported operators:
// equals, not_equals, contains, greater_than, less_than
RESPONSE METADATA
{
  "response_id": 123,
  "answers": {
    "rating": "3",
    "comment": "Good service"
  },
  "metadata": {
    "conditional_logic_applied": true,
    "skipped_questions": [
      {
        "key": "follow_up",
        "reference_id": "question-followup-uuid",
        "title": "What made it excellent?",
        "reason": "Conditional logic"
      }
    ]
  }
}
ℹ️ Conditional logic is enabled by default. To disable, set metadata.conditional_logic.enabled = false in your survey settings.
Webhooks

Webhooks allow you to receive real-time notifications when survey responses are submitted. Configure webhook URLs in your survey settings.

Webhook Payload
{
  "event": "survey.response.created",
  "survey": {
    "id": 123,
    "name": "Customer Satisfaction Survey",
    "channel": "web"
  },
  "response": {
    "id": 456,
    "answers": {
      "question_1": "Very satisfied",
      "question_2": "Great service"
    },
    "completion_time": 45,
    "submitted_at": "2025-12-26T20:30:00Z"
  },
  "timestamp": "2025-12-26T20:30:01Z"
}
Security: HMAC Signature Verification

All webhook requests include an X-DaguSaas-Signature header with an HMAC SHA-256 signature. Verify this signature using your webhook secret to ensure the request is legitimate.

Webhook Features
  • Automatic retry with exponential backoff (3 attempts: 1s, 2s, 4s)
  • 10-second timeout per request
  • HMAC SHA-256 signature for request verification
  • Async delivery (non-blocking)
Error Handling

Dagu uses conventional HTTP response codes to indicate the success or failure of an API request.

CodeMeaning
200Success — Request completed successfully
400Bad Request — Invalid parameters or missing required fields
404Not Found — Survey not found or not published
429Too Many Requests — Rate limit exceeded (10 submissions/hour per IP)
500Internal Server Error — Something went wrong on our end
Rate Limits

To prevent abuse, we implement rate limiting on survey submissions:

SURVEY SUBMISSIONS
10 per hour
Per IP address
SPAM PROTECTION
reCAPTCHA v3 + Honeypot
Automatic bot detection
Best Practices
  • ✓Validate input: Always validate user input before submission to prevent errors
  • ✓Handle errors gracefully: Use try-catch blocks and provide user-friendly error messages
  • ✓Use webhooks for real-time data: Instead of polling, configure webhooks to receive instant notifications
  • ✓Test in development: Always test your integration thoroughly before deploying to production
  • ✓Monitor rate limits: Track your API usage to avoid hitting rate limits during peak times
  • ✓Verify webhook signatures: Always verify HMAC signatures to ensure webhook authenticity

Ready to build?

Start integrating Dagu surveys into your applications today. Need help? Check out our survey builder for survey-specific quick references.

API Documentation — Dagu SaaS