Error

A valid request URL is required to generate request examples

{
  "data": {
    "workflow_id": "<string>",
    "workflow": {
      "id": "<string>",
      "kind": "survey.programming",
      "subject": {
        "type": "survey",
        "id": "<string>"
      },
      "status": "pending",
      "user_id": "<string>",
      "input": {},
      "output": {},
      "error": {
        "code": "<string>",
        "message": "<string>"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "started_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z"
    },
    "session": {
      "survey_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "questionnaire_revision": 123,
      "status": "probing",
      "probe_exhausted": true,
      "active_workflow_id": "<string>",
      "clarifications": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "category": "ambiguity",
          "prompt": "<string>",
          "context": "<string>",
          "options": [
            {
              "id": "<string>",
              "label": "<string>"
            }
          ],
          "response": {
            "kind": "answer",
            "text": "<string>",
            "option_id": "<string>"
          },
          "responded_at": "2023-11-07T05:31:56Z",
          "created_at": "2023-11-07T05:31:56Z",
          "resume_path": "<string>"
        }
      ],
      "summary": "<string>",
      "error": {
        "code": "<string>",
        "message": "<string>"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z"
    },
    "stream_url": "<string>"
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "resource": "<string>",
  "slug": "<string>",
  "file_id": "<string>",
  "endpoint_id": "<string>",
  "event_id": "<string>",
  "delivery_id": "<string>",
  "api_key_id": "<string>",
  "integration_id": "<string>",
  "audit_id": "<string>",
  "status": "<string>",
  "details": "<unknown>",
  "question_ids": [
    "<string>"
  ],
  "survey_ids": [
    "<string>"
  ],
  "revisions": [
    123
  ]
}

{
  "error": "<string>",
  "message": "<string>",
  "resource": "<string>",
  "slug": "<string>",
  "file_id": "<string>",
  "endpoint_id": "<string>",
  "event_id": "<string>",
  "delivery_id": "<string>",
  "api_key_id": "<string>",
  "integration_id": "<string>",
  "audit_id": "<string>",
  "status": "<string>",
  "details": "<unknown>",
  "question_ids": [
    "<string>"
  ],
  "survey_ids": [
    "<string>"
  ],
  "revisions": [
    123
  ]
}

{
  "error": "<string>",
  "message": "<string>",
  "resource": "<string>",
  "slug": "<string>",
  "file_id": "<string>",
  "endpoint_id": "<string>",
  "event_id": "<string>",
  "delivery_id": "<string>",
  "api_key_id": "<string>",
  "integration_id": "<string>",
  "audit_id": "<string>",
  "status": "<string>",
  "details": "<unknown>",
  "question_ids": [
    "<string>"
  ],
  "survey_ids": [
    "<string>"
  ],
  "revisions": [
    123
  ]
}

Clarifications

Start a clarifications probe on the tip questionnaire

Starts a survey.questionnaire_clarifications workflow on the tip questionnaire and returns 202 with workflow_id, initial session, and stream_url.

Subscribe to identified clarifications (first-party / live UI): open an NDJSON GET to stream_url (GET /v1/workflows/{workflowId}/stream). The stream uses the greenfield anatomy protocol:

workflow.anatomy — probe + await-responses steps
step.started / nested clarification.item chunks as discrepancies parse / step.ended
Authors answer or skip each item with tip PATCH ({ kind: "answer", text? | option_id? } or { kind: "skip" }) Omit startIndex (or pass 0) to subscribe from the start. Reconnect with a positive or negative startIndex while the World retains the run. A newer POST (newest-wins) returns a new workflow_id — switch streams.

Reconcile tip state: side-effect-free GET .../clarifications, plus account webhook questionnaire.clarifications.updated (full session). Use these after the stream ends, on reconnect gaps, or for non-browser consumers. Thin GET .../runs/{runId} returns run status/error when the stream ends early. Tip PATCH remains for answering when no live webhook gate is open (e.g. after skip-all).

Skip all: start programming (cancels the in-flight clarifications run). After answers settle (status: complete), POST again for follow-up probes. Historical revisions are read-only.

See Workflows → Live updates in the Program docs for the full per-kind subscribe catalog.

POST

surveys

{surveyId}

questionnaire

clarifications

Error

A valid request URL is required to generate request examples

{
  "data": {
    "workflow_id": "<string>",
    "workflow": {
      "id": "<string>",
      "kind": "survey.programming",
      "subject": {
        "type": "survey",
        "id": "<string>"
      },
      "status": "pending",
      "user_id": "<string>",
      "input": {},
      "output": {},
      "error": {
        "code": "<string>",
        "message": "<string>"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "started_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z"
    },
    "session": {
      "survey_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "questionnaire_revision": 123,
      "status": "probing",
      "probe_exhausted": true,
      "active_workflow_id": "<string>",
      "clarifications": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "category": "ambiguity",
          "prompt": "<string>",
          "context": "<string>",
          "options": [
            {
              "id": "<string>",
              "label": "<string>"
            }
          ],
          "response": {
            "kind": "answer",
            "text": "<string>",
            "option_id": "<string>"
          },
          "responded_at": "2023-11-07T05:31:56Z",
          "created_at": "2023-11-07T05:31:56Z",
          "resume_path": "<string>"
        }
      ],
      "summary": "<string>",
      "error": {
        "code": "<string>",
        "message": "<string>"
      },
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "completed_at": "2023-11-07T05:31:56Z"
    },
    "stream_url": "<string>"
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "resource": "<string>",
  "slug": "<string>",
  "file_id": "<string>",
  "endpoint_id": "<string>",
  "event_id": "<string>",
  "delivery_id": "<string>",
  "api_key_id": "<string>",
  "integration_id": "<string>",
  "audit_id": "<string>",
  "status": "<string>",
  "details": "<unknown>",
  "question_ids": [
    "<string>"
  ],
  "survey_ids": [
    "<string>"
  ],
  "revisions": [
    123
  ]
}

{
  "error": "<string>",
  "message": "<string>",
  "resource": "<string>",
  "slug": "<string>",
  "file_id": "<string>",
  "endpoint_id": "<string>",
  "event_id": "<string>",
  "delivery_id": "<string>",
  "api_key_id": "<string>",
  "integration_id": "<string>",
  "audit_id": "<string>",
  "status": "<string>",
  "details": "<unknown>",
  "question_ids": [
    "<string>"
  ],
  "survey_ids": [
    "<string>"
  ],
  "revisions": [
    123
  ]
}

{
  "error": "<string>",
  "message": "<string>",
  "resource": "<string>",
  "slug": "<string>",
  "file_id": "<string>",
  "endpoint_id": "<string>",
  "event_id": "<string>",
  "delivery_id": "<string>",
  "api_key_id": "<string>",
  "integration_id": "<string>",
  "audit_id": "<string>",
  "status": "<string>",
  "details": "<unknown>",
  "question_ids": [
    "<string>"
  ],
  "survey_ids": [
    "<string>"
  ],
  "revisions": [
    123
  ]
}

Path Parameters

surveyId

string<uuid>

required

Body

application/json

The body is of type object.

Response

Probe pass accepted

data

object

required

Show child attributes

Surveys

Workflows

API keys

Integrations

Webhooks

Settings

Meta

Start a clarifications probe on the tip questionnaire

Path Parameters

Body

Response