Surveys / REFERENCE

Create a survey

Create a survey with its initial draft version and default design.

POST/api/v1/surveys

Permissions surveys:write

Parameters

Name	Description
`X-Luma-Workspace-Host`header · required	Your workspace host, e.g. acme.lumi-cx.com. Required on api.lumi-cx.com. This header never grants access: the Bearer key must belong to the selected workspace.

Request body

Field	Type & description
`name`required	string
`language`	string Allowed: en, ar

Responses

200 Successful operation

{
  "ok": true,
  "survey": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "example",
    "nameAr": "example",
    "team": "example",
    "createdBy": "example",
    "status": "draft",
    "themeLogoUrl": "example",
    "themePrimaryColor": "example",
    "targetingRules": {},
    "designId": "00000000-0000-4000-8000-000000000001",
    "currentVersionId": "00000000-0000-4000-8000-000000000001",
    "createdAt": "2026-09-26T09:00:00Z",
    "updatedAt": "2026-09-26T09:00:00Z"
  },
  "version": {
    "id": "00000000-0000-4000-8000-000000000001",
    "surveyId": "00000000-0000-4000-8000-000000000001",
    "versionNumber": 1,
    "status": "draft",
    "createdAt": "2026-09-26T09:00:00Z",
    "publishedAt": "2026-09-26T09:00:00Z",
    "questions": [
      {
        "id": "example",
        "orderIndex": 1,
        "type": "welcome",
        "promptEn": "example",
        "promptAr": "example",
        "options": {
          "choices": [
            null
          ],
          "choicesEn": [
            null
          ],
          "choicesAr": [
            null
          ],
          "rows": [
            null
          ],
          "columns": [
            null
          ],
          "min": 1,
          "max": 1,
          "visibility": {
            "effect": null,
            "match": null,
            "conditions": null
          },
          "optionFilters": [
            null
          ]
        },
        "required": false,
        "routes": [
          {
            "condition": null,
            "nextQuestionId": null
          }
        ]
      }
    ]
  },
  "designs": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "team": "example",
      "name": "example",
      "config": {},
      "createdAt": "2026-09-26T09:00:00Z",
      "updatedAt": "2026-09-26T09:00:00Z"
    }
  ]
}

400 Invalid request

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

401 Missing, invalid, expired, revoked or wrong-workspace key

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

403 Required key permission missing, module unavailable, or workspace suspended

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

404 Record, workspace or route not found

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

409 Version changed or the resource is locked

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

429 Rate limit exceeded; respect Retry-After

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}

502 Upstream or unexpected server error

{
  "ok": false,
  "error": "invalid_body",
  "message": "example"
}