openapi: 3.2.0
info:
  title: Decipher Rest MaxDiff API Calls API
  version: '1.0'
  description: The Decipher REST API allows comprehensive automation of your private or shared Decipher instance.
servers:
- url: https://{server}/api/v1
  description: Replace server with your instance domain.
  variables:
    server:
      default: selfserve.decipherinc.com
      description: Server domain
security:
- APIKey: []
tags:
- name: MaxDiff API Calls
paths:
  /surveys/{survey}/dqapi/{label}/hitrate:
    get:
      operationId: getSurveyDqapiLabelMaxdiffHitrate
      summary: Calculates the coefficients
      description: 'Calculate how often some of the stored coefficients match the answered questions.

        Coefficient data is expected to be in {question label}_{suffix}{attribute label}.'
      tags:
      - MaxDiff API Calls
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: label
        in: path
        description: label is the label of the question with a DQ that has API functions
        example: q1
        required: true
        schema:
          type: string
      - name: holdout
        in: query
        description: If holdout is set, test only that task, otherwise if set to “all” test all tasks.
        example: all
        required: true
        schema:
          type: string
      - name: suffix
        in: query
        description: suffix of the coefficient
        example: score
        required: true
        schema:
          type: string
      - name: include_correct
        in: query
        description: if set true it will show all the data rather than just misses.
        example: true
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  hitrate:
                    type: number
                  total:
                    type: integer
                  score:
                    type: integer
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        best:
                          type: string
                        coeff:
                          type: object
                        predicted_best:
                          type: string
                        predicted_worst:
                          type: string
                        uuid:
                          type: string
                        visible:
                          type: array
                        worst:
                          type: string
              example:
                hitrate: 41.7
                total: 12
                data:
                - visible:
                  - r8
                  - r2
                  - r3
                  - r6
                  worst: r6
                  uuid: cwyte1a68y4fu97e
                  coeff:
                    r6: 33.335
                    r8: 66.665
                    r2: 66.665
                    r3: 16.665
                  predicted_best: r8
                  best: r2
                  predicted_worst: r3
                - visible:
                  - r8
                  - r1
                  - r3
                  - r4
                  worst: r3
                  uuid: cwyte1a68y4fu97e
                  coeff:
                    r4: 83.335
                    r8: 66.665
                    r1: 33.335
                    r3: 16.665
                  predicted_best: r4
                  best: r8
                  predicted_worst: r3
                score: 5
  /surveys/{survey}/dqapi/{label}/mxd:
    get:
      operationId: getSurveyDqapiLabelMaxdiffMxd
      summary: Output data in a format suitable for Sawtooth
      tags:
      - MaxDiff API Calls
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: label
        in: path
        description: label is the label of the question with a DQ that has API functions
        example: q1
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                example:
                - MXD_6_w: '7'
                  MXD_4_w: '1'
                  MXD_3_w: '3'
                  MXD_5_b: '7'
                  sys_RespStatus: 5
                  MXD_1_b: '4'
                  MXD_2_w: '6'
                  MXD_4_b: '2'
                  MXD_3_b: '8'
                  sys_MXDVersion_MXD: '90'
                  MXD_1_w: '3'
                  MXD_2_b: '2'
                  MXD_5_w: '2'
                  MXD_6_b: '4'
                  sys_RespNum: '1'
  /surveys/{survey}/dqapi/{label}/tricked:
    get:
      operationId: getSurveyDqapiLabelMaxdiffTricked
      summary: Output respondent data in so-called “tricked” format
      description: Output respondent data in so-called “tricked” format, suitable for input into tools like R’s mlogit.
      tags:
      - MaxDiff API Calls
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: label
        in: path
        description: label is the label of the question with a DQ that has API functions
        example: q1
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  alternatives:
                    type: integer
                  attribute_labels:
                    type: array
                    items:
                      type: string
                  data:
                    type: array
                    items:
                      type: object
                example:
                  alternatives: 4
                  data:
                  - r4: 0
                    r5: 0
                    r6: 0
                    Task: 1
                    uuid: 1
                    r2: 0
                    r3: 1
                    r8: 0
                    Choice: 0
                    r7: 0
                    r1: 0
                  - r4: 0
                    r5: 0
                    r6: -1
                    Task: 2
                    uuid: 1
                    r2: 0
                    r3: 0
                    r8: 0
                    Choice: 0
                    r7: 0
                    r1: 0
                  - r4: 0
                    r5: 0
                    r6: 0
                    Task: 3
                    uuid: 1
                    r2: 0
                    r3: 0
                    r8: 1
                    Choice: 0
                    r7: 0
                    r1: 0
                  attribute_labels:
                  - r1
                  - r2
                  - r3
                  - r4
                  - r5
                  - r6
                  - r7
                  - r8
components:
  parameters:
    survey:
      name: survey
      in: path
      required: true
      description: The survey path.
      example: selfserve/1a/123456
      schema:
        type: string
        format: uri
  securitySchemes:
    APIKey:
      type: apiKey
      in: header
      name: x-apikey
      description: 'In order to access the api, you''ll need to generate an API key. Refer to the

        instructions [here](/docs/decipher/api#section/API-Keys) to generate and

        configure an API key with the appropriate permission sets. You can generate

        as many keys as required.


        Configure each request to include your API key in the request header. For example:


        ```

        x-apikey: dp48ss3mgsaucyjtybxw728h7s4cgnwzhejtszdwhf4xpe8yhmtdwpk2ntdhtwbs

        ```

        '
x-tagGroups:
- name: Autoclose
  tags:
  - Autoclose
- name: Data Input and Output
  tags:
  - Data
  - Data Feed
  - Response Summary
  - Modifying Data
  - Datasources
  - Datasources Data
  - Umerge
- name: Survey Metadata
  tags:
  - Simulated Data
  - Survey State
  - Survey Evaluate
  - Survey Quotas
  - Survey Files
  - Survey Warnings
  - Survey Terms
  - Survey Subscribers
  - Survey Users
  - Survey Tasks
- name: Panels
  tags:
  - Panel Data
  - Panel Datapoints
  - Survey Panels
- name: Research Hub
  tags:
  - Users
  - Companies
  - Categories
  - Surveys
  - Panels
  - Crosstabs
  - Archives
  - Archival Reports
  - API Keys
  - Usage
  - Warnings Summary
- name: Crosstabs
  tags:
  - Crosstabs Configuration
  - Crosstabs Execution
  - Crosstabs Nets
  - Saved Crosstabs
  - Crosstabs Table Settings
  - Crosstabs Validation
  - Crosstabs Rim Weighting
- name: Dashboards
  tags:
  - Dashboards
- name: DQ APIs
  tags:
  - DQ-Specific API Calls
  - MaxDiff API Calls
  - Discrete Choice Model API Calls
  - Media Testimonial API Calls
- name: Response Summary
  tags:
  - Share Link
- name: Sample Management
  tags:
  - Bounced Emails
  - Participant Sources
- name: Distribution
  tags:
  - Email Distribution
  - SFTP Distribution
  - Slack Distribution
- name: Campaign Manager
  tags:
  - Campaigns
  - Campaign Email Invites
  - Campaign Exports
  - Campaign Lists
  - Shared Campaign Lists
  - Campaign Sends
  - Campaign Status Lists
  - Supression Lists
- name: Question Library
  tags:
  - Company Element
  - Company Elements
  - Survey Elements
  - Survey Element Report Settings
- name: Language Manager
  tags:
  - LM Application Data
  - LM Application Translations
  - Translation Resources
  - Translations
  - Translation Deltas
  - Translation Reservations
  - Primary Survey Language
  - Other Survey Languages
  - Unused Survey Languages
- name: Project Parameters
  tags:
  - Available Project Parameters
  - Saved Project Parameters
  - Project Parameters Configuration
- name: Multi-User Editing
  tags:
  - Available Sections
  - Check Out Section
  - Check In Section
  - Sync Section
  - Section Editor
  - Abandon Section
  - Validate Section
- name: Video Management
  tags:
  - Videos
  - Watermarked Videos
- name: Miscellaneous
  tags:
  - System Information
  - Logic Nodes
  - Logic Events
  - CATI
  - Global Search
  - Miscellaneous