> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.questra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start programming

> Creates (or replaces) survey programming via program-from-questionnaire (newest-wins). Cancels any in-flight questionnaire clarifications probe. Returns workflow_id + stream_url for the generic anatomy stream; programming detail is lean (empty phases for greenfield).



## OpenAPI

````yaml /openapi/program.openapi.json post /surveys/{surveyId}/programming
openapi: 3.1.0
info:
  title: Questra Program API
  version: 0.0.1
  description: >-
    REST API for the Questra Program product. Browser users authenticate through
    Questra Auth SSO; automation uses workspace-scoped API keys (`Authorization:
    Bearer qpk_live_…`). API keys carry scopes enforced before handlers.
    Outbound webhooks follow Standard Webhooks (at-least-once delivery;
    consumers must be idempotent).
servers:
  - url: /v1
    description: Program API base path
security: []
paths:
  /surveys/{surveyId}/programming:
    post:
      tags:
        - Survey programming
      summary: Start programming
      description: >-
        Creates (or replaces) survey programming via program-from-questionnaire
        (newest-wins). Cancels any in-flight questionnaire clarifications probe.
        Returns workflow_id + stream_url for the generic anatomy stream;
        programming detail is lean (empty phases for greenfield).
      parameters:
        - schema:
            type: string
            format: uuid
          required: true
          name: surveyId
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartProgrammingRequest'
      responses:
        '202':
          description: Programming accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartProgrammingResponse'
        '400':
          description: Validation / missing questionnaire
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '403':
          description: Feature disabled (e.g. Questra Publish target not enabled)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: File not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
components:
  schemas:
    StartProgrammingRequest:
      type: object
      properties:
        questionnaire_revision:
          type: integer
          exclusiveMinimum: 0
          description: Defaults to the survey’s current questionnaire tip when omitted.
        platform:
          $ref: '#/components/schemas/ProgrammingPlatform'
        instructions:
          type: string
        fine_tuning_template_id:
          type: string
          format: uuid
          description: >-
            Preselect a fine-tuning template so the run does not wait on
            template selection.
    StartProgrammingResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/StartProgrammingResponseData'
      required:
        - data
    ErrorBody:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        resource:
          type: string
        slug:
          type: string
        file_id:
          type: string
        endpoint_id:
          type: string
        event_id:
          type: string
        delivery_id:
          type: string
        api_key_id:
          type: string
        integration_id:
          type: string
        audit_id:
          type: string
        status:
          type: string
        details: {}
        question_ids:
          type: array
          items:
            type: string
        survey_ids:
          type: array
          items:
            type: string
        revisions:
          type: array
          items:
            type: number
      required:
        - error
    ProgrammingPlatform:
      type: string
      enum:
        - questra
        - decipher
        - confirmit
        - qualtrics
        - alchemer
    StartProgrammingResponseData:
      type: object
      properties:
        survey_id:
          type: string
          format: uuid
        file_id:
          type: string
          format: uuid
        questionnaire_revision:
          type: integer
          exclusiveMinimum: 0
        platform:
          allOf:
            - $ref: '#/components/schemas/ProgrammingPlatform'
            - type:
                - string
                - 'null'
        programming:
          $ref: '#/components/schemas/ProgrammingDetail'
        workflow_id:
          type: string
          minLength: 1
          description: Workflow SDK run id (`wrun_...`).
        stream_url:
          type: string
          minLength: 1
          description: >-
            Generic World NDJSON stream (`GET
            /v1/workflows/{workflow_id}/stream`).
      required:
        - survey_id
        - file_id
        - questionnaire_revision
        - platform
        - programming
        - workflow_id
        - stream_url
    ProgrammingDetail:
      type: object
      properties:
        kind:
          type: string
          enum:
            - survey.programming
        survey_id:
          type: string
          format: uuid
        status:
          type: string
        phases:
          type: array
          items:
            $ref: '#/components/schemas/ProgrammingPhase'
          default: []
        output:
          type:
            - object
            - 'null'
          additionalProperties: {}
        error:
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
        workflow_id:
          type: string
          minLength: 1
          description: Current survey.programming World run id when a binding exists.
        stream_url:
          type: string
          minLength: 1
          description: >-
            Generic World NDJSON stream (`GET
            /v1/workflows/{workflow_id}/stream`).
        configure_draft:
          type: object
          additionalProperties:
            type: object
            additionalProperties: {}
          description: >-
            Overwritable configure picker payloads stored on the workflow
            binding. Clients hydrate the wizard from this while compose is still
            running.
      required:
        - kind
        - survey_id
        - status
    ProgrammingPhase:
      type: object
      properties:
        id:
          type: string
          enum:
            - build
            - configure
            - compile
            - fine_tune
            - verify
            - push
        title:
          type: string
        status:
          type: string
          enum:
            - planned
            - waiting
            - running
            - completed
            - skipped
            - failed
        steps:
          type: array
          items:
            $ref: '#/components/schemas/ProgrammingStepView'
      required:
        - id
        - title
        - status
        - steps
    ProgrammingStepView:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        kind:
          type: string
          enum:
            - task
            - fanOut
            - gate
            - loop
            - fanOutMember
            - loopIteration
            - loopChild
        status:
          type: string
          enum:
            - planned
            - waiting
            - running
            - completed
            - skipped
            - failed
        condition:
          type: object
          properties:
            description:
              type: string
            pending:
              type: boolean
            reason:
              type: string
          required:
            - description
            - pending
        output: {}
        logs:
          type: array
          items:
            type: object
            properties:
              log:
                type: string
              payload: {}
              timestamp:
                type: string
            required:
              - log
              - timestamp
        error:
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
        started_at:
          type:
            - string
            - 'null'
          format: date-time
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
        steps:
          type: array
          items:
            $ref: '#/components/schemas/ProgrammingStepView'
      required:
        - id
        - title
        - kind
        - status

````