Forsta Miscellaneous API

openapi: 3.2.0
info:
  title: Decipher Rest Miscellaneous 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: Miscellaneous
paths:
  /hello:
    get:
      operationId: getHello
      summary: Hello there!
      description: This test call echos its `name` argument.
      tags:
      - Miscellaneous
      parameters:
      - name: name
        description: this value will be echoed back
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: string
                  hello:
                    type: string
              example:
                ok: '1'
                hello: Roy Fielding
  /meta:
    get:
      operationId: getMeta
      summary: Get API metadata
      description: Retrieve an array of all currently implemented API calls.
      tags:
      - Miscellaneous
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    endpoint:
                      type: string
                      description: 'name of the API call, excluding version but including the

                        placeholder for primary key of the source.

                        '
                    description:
                      type: string
                      description: description
                    title:
                      type: string
                      description: API title
                    url:
                      type: string
                      description: URL including current version prefix
                    args:
                      type: object
                      description: 'object containing arguments this API call will take, together

                        with type names

                        '
                    method:
                      type: string
                      description: 'method to use. Note: multiple entries will exist with same

                        endpoint but different methods

                        '
  /surveys/{survey}/test/token:
    get:
      operationId: getSurveyTestToken
      summary: Get survey test URL token
      description: 'Generates a temporary token to access surveys for testing purposes. Data

        won''t be collected'
      tags:
      - Miscellaneous
      parameters:
      - $ref: '#/components/parameters/survey'
      - name: expires
        description: days to expire token
        in: query
        required: false
        schema:
          default: 7
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                  url:
                    type: string
              example:
                token: TOKEN
                url: https://release.decipherinc.com/survey/selfserve/53a/1234?v2test=TOKEN
  /exceptions/search:
    get:
      operationId: getExceptionsSearch
      summary: Find error
      description: Search for a logged error by lookup code.
      tags:
      - Miscellaneous
      parameters:
      - name: lookup_code
        description: lookup code
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  timestamp:
                    type: string
                    format: ISO 8601 timestamp with timezone
                    description: time that the error occurred
                  path:
                    type: string
                    description: survey path (if applicable)
                  full_text:
                    type: string
                    description: full error text and traceback (if applicable)
  /status:
    get:
      operationId: getStatus
      summary: Get task
      description: Retrieve the status of an async task started by another api call
      tags:
      - Miscellaneous
      parameters:
      - name: id
        description: id of the async task to get the status of
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  extra:
                    type: object
                    properties:
                      cpuTime:
                        type: number
                      dataCleared:
                        type: boolean
                      languages:
                        type:
                        - array
                        - 'null'
                      markerCount:
                        type: integer
                      maxStoredSize:
                        type: integer
                      progressCount:
                        type: integer
                  ident:
                    type: string
                  percentage:
                    type: integer
                  pid:
                    type: integer
                  progress:
                    type: integer
                  result:
                    type: string
                  status:
                    type: string
                  survey:
                    type: string
                  task:
                    type: string
                  timestamp:
                    type: integer
                  total:
                    type: integer
                  type:
                    type: string
                  what:
                    type: string
              example:
                extra:
                  cpuTime: 0.022321394999999997
                  dataCleared: false
                  languages: null
                  markerCount: 1
                  maxStoredSize: 0
                  progressCount: 200
                ident: 3jd7qyadpgjbxu6t
                percentage: 100
                pid: 3957
                progress: 100
                result: 100/100 succeeded
                status: finished
                survey: selfserve/53a/180109
                task: Survey Stress Test
                timestamp: 1516830993
                total: 100
                type: sst
                what: Finished
    delete:
      operationId: deleteStatus
      summary: Cancel task
      description: Cancel one or more async tasks
      tags:
      - Miscellaneous
      parameters:
      - name: all
        description: cancel all async tasks if true
        in: query
        required: false
        schema:
          type: boolean
      - name: id
        description: id of the async task to cancel
        in: query
        required: false
        schema:
          type: string
      - name: survey
        description: cancel all async tasks if true
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    description: list of id's of the canceled tasks
                    example: []
                    type: array
  /status/content:
    get:
      operationId: getStatusContent
      summary: Get task content
      description: Retrieve the content of an async API call. This will return a request with a API-specific content, such as a ZIP file you asked to be generated.
      tags:
      - Miscellaneous
      parameters:
      - name: id
        description: id of the async task to get the content of
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Endpoint-specific result content
    delete:
      operationId: deleteStatusContent
      summary: Remove content
      description: Remove content for an asynchronous task. If you already downloaded the file through /api/v1/status/content you can use this call to immediately free up disk space. Otherwise, it will be deleted after 7 days.
      tags:
      - Miscellaneous
      parameters:
      - name: id
        description: id of the async task to delete content of
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: already removed
  /misc/scoreboard:
    get:
      operationId: getMiscScoreboard
      summary: Get light scoreboard
      description: Displays surveys and services using the most resources in a period of time, the default scoreboard retention is 7 days. Fetching non-current data will take additional time depending on system traffic. Only for staff users.
      tags:
      - Miscellaneous
      parameters:
      - name: hours
        in: query
        description: How many hours starting from `end` date looking for the past
        schema:
          type: integer
          default: 4
        example: 4
        required: false
      - name: end
        in: query
        description: Starting date of the review
        schema:
          type: string
          format: ISO 8601 date
          default: now
        example: 2022-10-10T00:00Z
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  surveys:
                    description: 'Shows survey related data.

                      '
                    type: array
                    items:
                      type: object
                      properties:
                        views:
                          description: 'Pages viewed in the surveys.

                            '
                          type: string
                          example: 123
                        period:
                          description: 'Period when the survey was running.

                            '
                          type: string
                          format: date-time
                          example: '2022-11-16T20:49:24Z'
                        routing95:
                          description: '5 percent of respondents wait this time or higher.

                            If this is many times higher then average, it may indicate traffic spikes.

                            '
                          type: integer
                          example: 12
                        avg_cpu:
                          description: 'The the average amount of computing time cores used to display the survey.

                            '
                          type: integer
                          example: 29
                        routing:
                          description: 'Average waiting time for the respondents.

                            '
                          type: integer
                          example: 28
                        path:
                          description: 'Path of the survey.

                            '
                          type: string
                          example: selfserve/53d/220000
                        cpu:
                          description: 'Total amount of computing time cores used to display the survey.

                            '
                          type: number
                          example: 0.4676
                  categories:
                    type: array
                    description: 'Data related to each module.

                      The modules are:

                      - survey

                      - response (Response Summary)

                      - v/e (view/edit respondents)

                      - portal

                      - builder

                      - report (includes Crosstabs and Reporting 2010)

                      - api

                      - script (SST, copy-survey and other things run from the command line)

                      '
                    items:
                      type: object
                      properties:
                        category:
                          type: string
                          description: 'Module which data belongs to.

                            '
                          example: v/e
                        surveys:
                          type: integer
                          description: 'How many surveys used the module.

                            '
                          example: 99
                        users:
                          type: integer
                          description: 'How many users used the module.

                            '
                          example: 29
                        views:
                          description: 'Pages viewed in the in the module.

                            '
                          type: string
                          example: 250
                        period:
                          description: 'Period when the module was being used.

                            '
                          type: string
                          example: '2022-11-16T20:49:24Z'
                        routing95:
                          description: '5 percent of respondents wait this time or higher.

                            If this is many times higher then average, it may indicate traffic spikes.

                            '
                          type: string
                          example: 500
                        avg_cpu:
                          description: 'The the average amount of computing cores used to display the survey.

                            Different server configurations will have a different maximum of CPU cores

                            for all surveys.

                            '
                          type: string
                          example: 210
                        routing:
                          description: 'Average waiting time for the respondents using the module.

                            '
                          type: string
                          example: 300
                        cpu:
                          description: 'Total amount of computing cores used to display the survey.

                            '
                          type: number
                          example: 0.7584254
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