AI API

ResponseDock exposes AI capabilities via the API, gated by your workspace's billing plan.

Endpoints

Generate a Survey

POST /ai/generate

{
  "workspaceId": "ws_xxxx",
  "prompt":      "Post-match feedback for teenage football players",
  "options": {
    "detailLevel": "standard",   // "quick" | "standard" | "detailed" | "expert"
    "tone":        "friendly",   // "friendly" | "professional" | "youth_friendly" | "formal"
    "audience":    "athletes",
    "goal":        "feedback",
    "language":    "en"
  }
}

// 200 OK — returns a full survey draft (not saved to DB yet)
{
  "title":       "How was the match?",
  "description": "Share your thoughts on today's game.",
  "estimatedMinutes": 2,
  "pages": [
    {
      "title": "Match Experience",
      "blocks": [
        {
          "type": "question",
          "question": {
            "type":     "nps",
            "label":    "How would you rate today's match overall?",
            "required": true
          }
        }
      ]
    }
  ]
}

Translate a Survey

POST /surveys/:id/ai/translate

{
  "targetLanguage": "de"
}

// 200 OK
{
  "translatedFields": 24,
  "language": "de"
}

Improve a Survey

POST /surveys/:id/ai/improve

{
  "instruction": "make it shorter and more mobile-friendly"
}

// 200 OK — returns suggested changes
{
  "suggestions": [
    {
      "questionId": "q_3",
      "field":      "label",
      "original":   "Please describe in detail...",
      "suggested":  "Describe your experience"
    }
  ]
}

Usage Limits

Each AI API call counts toward your workspace's monthly AI API call quota. This includes feedback design, improvement, and translation requests. Check remaining usage with:

GET /workspaces/:id/usage

{
  "responsesUsed": 312,
  "responsesLimit": 1000,
  "aiGenerationsUsed": 18,
  "aiGenerationsLimit": 50
}