Forsta Survey Files API

openapi: 3.2.0
info:
  title: Decipher Rest Survey Files 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: Survey Files
paths:
  /surveys/{survey}/files:
    get:
      operationId: getSurveyFiles
      summary: List files
      description: Retrieves a list of system and static files relevant to a survey
      tags:
      - Survey Files
      parameters:
      - $ref: '#/components/parameters/survey'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    filename:
                      type: string
                      description: the file path relative to the survey directory
                    modified:
                      type: string
                      description: the date and time when the file was last modified
                      format: ISO-8601 timestamp with timezone
                    size:
                      type: integer
                      description: the size of the file in bytes
              example:
              - filename: survey.xml
                modified: '2020-10-20T21:02:11Z'
                size: 1239
              - filename: static/less-compiled.css
                modified: '2020-10-20T21:02:14Z'
                size: 73860
  /surveys/{survey}/files/{filename}:
    get:
      operationId: getSurveyFile
      summary: Download file
      description: 'Allows direct access to some of the configuration files that make up a

        survey. Use the List call above to find out which files are specifically

        available for this survey.


        - survey.xml -- survey''s main content

        - quota.xls -- Excel 97 file defining quotas

        - quota.xls.log -- this log file contains debug information stored on

        every quota invocation

        - survey.log -- additional debug data related to the survey

        - data/exit.log -- one entry for each participant exiting the survey

        - virtual-timing.txt -- virtual question performance

        - static/* -- all uploaded static resources'
      tags:
      - Survey Files
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: filename
        description: filename to download
        in: path
        required: true
        schema:
          type: string
        example: survey.xml
      responses:
        '200':
          description: OK
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
    put:
      operationId: updateSurveyFile
      summary: Upload/replace file
      tags:
      - Survey Files
      description: 'Allows a new file to be uploaded or an existing file to be replaced. When uploading a `survey.xml`, only a survey that would successfully load are allowed and only surveys in `dev` or `testing` state can be modified. If you override the last check beware not to modify the datamap for your survey, as no conversion process is done by this call.


        If an invalid file is uploaded, the `400` error code is returned. If an error is returned from a `survey.xml`, the body will contain a list of errors in the `extra` property. This will be an array of error objects. An error object will have `type` set to either parse or survey. Parse errors occur during XML parsing. Survey errors occur during validation of survey content (i.e. attributes and values).


        A list of the allowed file types can be found here.'
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: filename
        description: filename to upload
        in: path
        required: true
        schema:
          type: string
        example: survey.xml
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                contents:
                  type: string
                  format: binary
                  description: The contents of the file
                validate:
                  type: boolean
                  description: 'Only applies when uploading `survey.xml`. Validate `survey.xml`

                    prior to saving it.

                    '
                  default: true
                overwriteLive:
                  type: boolean
                  description: Allow updates to live or closed surveys.
                  default: false
                location:
                  type: string
                  description: 'The location to which to upload the file. If uploading to the

                    survey''s static directory, use "static", otherwise use the default

                    "root" to upload the file to the root directory of the survey.

                    Files in static are publicly accessible, while files in the root

                    directory of the survey are system only.

                    '
                  default: root
                  enum:
                  - root
                  - static
              required:
              - contents
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  filename:
                    type: string
                    description: the filename where the uploaded file was stored
              example:
                filename: survey.xml
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  $error:
                    type: string
                    description: generic error description
                  $code:
                    type: integer
                    description: http error code (400)
                  extra:
                    type: array
                    description: an array of error objects
                    items:
                      type: object
                      description: details about the particular parse or survey error
              examples:
                Parse error:
                  value:
                    $error: Bad content. Additional error in body.
                    $code: 400
                    extra:
                    - column: 220
                      processed: '<survey autosave=\"0\" setup=''time,term,quota''

                        autosaveKey=\"\" compat=\"118\"

                        extraVariables=\"url,record,list,page,source\"

                        lang=\"english.utf8\" name=\"Kitchen Sink Survey

                        (remotely modified)\" pipeAltLabels=\"1\" state=''testing''>

                        <>

                        '
                      file: demo/kitchensink/temp-api/survey.xml
                      line: 2
                      type: parse
                      message: not well-formed (invalid token)
                Survey errors:
                  value:
                    $error: Bad content. Additional error in body.
                    $code: 400
                    extra:
                    - tag: radio
                      type: survey
                      label: q1
                      error: 'Extra unrecognized argument given: whatever'
                    - line: 1243
                      tag: col
                      type: survey
                      label: c8
                      error: 'Extra unrecognized argument given: xyzzy'
    delete:
      operationId: deleteSurveyFile
      summary: Delete file
      description: 'Allows the user to delete any file type that can be uploaded in the

        survey directory. Version control may store past revisions for specific

        files in the survey directory. The force flag is required if the survey

        is live or closed. If used incorrectly this can cause data loss. If an

        invalid file is attempted to be deleted, a 400 response will return. On

        successful deletion of the file a 200 response will return. The survey

        log and user audit log will contain an entry for who deleted what

        specific file.'
      tags:
      - Survey Files
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: filename
        description: filename to delete
        in: path
        required: true
        schema:
          type: string
        example: custom.css
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                location:
                  description: 'The location from which the file should be deleted. If deleting

                    a file from the static directory, use "static", otherwise use

                    the default "root" to delete a file in the root of the survey

                    directory.

                    '
                  default: root
                  type: string
                  enum:
                  - root
                  - static
                force:
                  description: 'Force delete the file if the survey is live or closed (warning:

                    This can cause data loss if used incorrectly).

                    '
                  default: false
                  type: boolean
            example:
              location: static
              force: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /surveys/{survey}/files/headers:
    get:
      operationId: getSurveyFileHeaders
      summary: Get file headers
      description: 'Retrieves a list of headers from a .dat or .txt file in the root directory of

        the project.'
      tags:
      - Survey Files
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: filename
        in: query
        description: file name from which to retrieve headers
        example: data.txt
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              example:
              - email
              - firstname
              - lastname
              - occupation
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