Figure Eight Manage Job Settings API

openapi: 3.0.0
info:
  title: Appen Platform Account Info Manage Job Settings API
  version: 1.0.0
  description: "# Introduction\nHello, and welcome to Appen, the leading data annotation platform for Machine Learning. Our API enables developers to build applications that can programmatically create, edit, and launch Appen jobs, download results, and more! \n\nAppen uses a RESTful API that accepts data requests as URL-encoded key-value pairs. Responses are returned in JSON and authentication is key-based.\n\nBefore integrating with the API, we highly recommend you first build and run a job using our [graphical user interface](https://client.appen.com/sessions/new). Once you have run a job successfully and are satisfied with the results, you can automate the process using the Appen API.\n\n# Authentication\nYou will need to supply your Appen API key to access the API. To find your API key:\n1. Click the Account button located in the bottom corner of the Global Navigation bar on the left side of any page.\n![Appen Authentication](/assets/img/authentication1.png \"Appen Authentication\")\n2. Click the API tab and find your key listed under the Your API Key section. \n![Appen API](/assets/img/authentication2.png \"Appen API key\")\n\nFor requests listed below, the API Key will be listed as `{api_key}`. \n\nThe API key needs to be included in the header for every request: \n```\n  headers: { \n\n   \"AUTHORIZATION\" => \"Token token={api_key}\" \n\n  } \n```\n\nYou may also see other variables, such as `{job_id}` for operations pertaining to a specific job, or `{team_id}` when completing operations relevant to an entire team (like listing all available jobs). Job ID's can be determined from the job listing page or the URL. A team id is visible in the URL of the Teams tab in the Account page. \n# Resources\nThere are three primary data objects on Appen that correspond to resources on the API:\n## Jobs\nA **Job** is an interface that connects your data to an online workforce.\n  Each job on the Appen platform has data, instructions, customizable questions for your use case\n  (written in **CML** [](https://success.appen.com/hc/en-us/articles/202817989-CML-Custom-Markup-Language-Overview)),\n  [test questions](https://success.appen.com/hc/en-us/articles/202702985-How-to-Create-Test-Questions),\n  and is worked on by *Contributors*. Contributors submit *Judgments* on the rows of data via a worker interface. \n    * All jobs in a single account can be found [on your jobs page](https://client.appen.com/jobs) and will be\n    identified by a unique numeric id.\n## Units (also known as 'Rows')\nA **Unit** of data is uploaded to the job from your source data file via API or GUI. \n## Judgments \nA **Judgment** is the set of responses submitted by a contributor on a particular unit of data. It is\n  recommended to collect multiple judgments and compare them to one another or aggregate to the top response. For\n  each job, you can specify the number of judgments you would like each row to receive.\n# Responses and Messaging\nEach request to the Appen API returns an HTTP status code response and one or both of the following:\n* An application response message (in JSON) \n* A JSON representation of the object (job, unit, or judgments) requested\nSee the below sections of different API Requests, Responses and Messaging for more information:\n1. [Job Create/Update](/#tag/Job-CreateUpdate)\n2. [Manage Job Data](/#tag/Manage-Job-Data)\n3. [Job Status](/#tag/Job-Status)\n4. [Monitor Contributors](/#tag/Monitor-Contributors)\n5. [Manage Job Settings](/#tag/Manage-Job-Settings)\n6. [Job Results](/#tag/Job-Results)\n7. [Account Info](/#tag/Account-Info)\n"
  license:
    name: Licensed under Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://www.appen.com/privacy-statement/
  contact:
    email: help@appen.com
servers:
- url: https://api.appen.com/v1
  description: Production Server
tags:
- name: Manage Job Settings
  description: Manage various job settings.
  externalDocs:
    url: https://success.appen.com/hc/en-us/articles/202703435-Jobs-Resource-Attributes
paths:
  /jobs/{job_id}.json:
    put:
      tags:
      - Manage Job Settings
      summary: Update a given job.
      description: 'Update various elements of a job. Your job must have a valid title,

        instructions, and one "required" CML form element to be launched

        successfully.

        '
      parameters:
      - $ref: '#/components/parameters/job_id'
      - $ref: '#/components/parameters/api_key'
      - in: query
        name: job[title]
        description: Updates the title of the Job.
        required: false
        schema:
          type: string
      - in: query
        name: job[instructions]
        description: Updates the instructions of the Job.
        required: false
        schema:
          type: string
      - in: query
        name: job[cml]
        description: Updates the CML of the Job.
        required: false
        schema:
          type: string
      - in: query
        name: job[css]
        description: Updates the CSS of the Job.
        required: false
        schema:
          type: string
      - in: query
        name: job[payment_cents]
        description: 'Determines the amount, in cents, that Contributors will be paid per

          Task

          '
        required: false
        schema:
          type: integer
      - in: query
        name: job[judgments_per_unit]
        description: Unit in the refers to a single row in the job
        required: false
        schema:
          type: integer
      - in: query
        name: job[quiz_length_configured]
        description: True, for custom number of test questions in Quiz mode
        required: false
        schema:
          type: boolean
      - in: query
        name: job[quiz_length]
        description: Number of test questions in quiz
        required: false
        schema:
          type: integer
      - in: query
        name: job[options][req_ttl_in_seconds]
        description: Set the amount of time per assignment. Default is set to 30 minutes.
        required: false
        schema:
          type: integer
      - in: query
        name: job[units_per_assignment]
        description: Sets the number of Rows that will comprise one Page within a Job.
        required: false
        schema:
          type: integer
      - in: query
        name: job[variable_judgments_mode]
        description: 'Accepts "none" or "auto_confidence". Use in combination with

          job[options][confidence_fields], job[max_judgments_per_unit], and

          job[min_unit_confidence] to set dynamic judgments. More info

          [Job Launch > Job Settings > Guide to Dynamic Judgments](https://success.appen.com/hc/en-us/articles/203219205-Job-Settings-Guide-to-Dynamic-Judgments)

          '
        required: false
        schema:
          type: string
      - in: query
        name: job[options][confidence_fields]
        description: 'CML form element name that determines row finalization for dynamic

          judgments. More info in the Success center at

          [Job Launch > Job Settings > Guide to Dynamic Judgments](https://success.appen.com/hc/en-us/articles/203219205-Job-Settings-Guide-to-Dynamic-Judgments)

          '
        required: false
        schema:
          type: string
      - in: query
        name: job[max_judgments_per_unit]
        description: 'Maximum number of judgments collected per row. More info in the Success center at

          [Job Launch > Job Settings > Guide to Dynamic Judgments](https://success.appen.com/hc/en-us/articles/203219205-Job-Settings-Guide-to-Dynamic-Judgments)

          '
        required: false
        schema:
          type: integer
      - in: query
        name: job[min_unit_confidence]
        description: 'Minimum confidence needed to finalize a row (a number from 0 to 1).

          More info in the Success center at

          [Job Launch > Job Settings > Guide to: Dynamic Judgments](https://success.appen.com/hc/en-us/articles/203219205-Job-Settings-Guide-to-Dynamic-Judgments)

          '
        required: false
        schema:
          type: number
      - in: query
        name: job[auto_order]
        description: Automatically launch rows as they are added to the Job
        required: false
        schema:
          type: boolean
      - in: query
        name: job[auto_order_timout]
        description: 'The time in seconds before automatic ordering of any new rows will

          occur. auto_order must be enabled.

          '
        required: false
        schema:
          type: integer
      - in: query
        name: job[auto_order_threshold]
        description: 'The job must have at least this many new rows—or the timeout must

          have passed—before new rows will be ordered automatically. This

          setting must be greater than the number of rows per page minus the

          number of Test Questions shown per page. auto_order must be enabled.

          '
        required: false
        schema:
          type: integer
      - in: query
        name: job[ignore_overlapping_names]
        description: 'When enabling auto-order, you may encounter the following response message: "You created column headers that duplicate the original uploaded column headers: ''example''. Please use unique column headers or allow duplicate column headers by adding the ignore_overlapping_names=true flag." Ignore_overlapping_names allows a job to be launched where a CML name duplicates a source column header.

          '
        required: false
        schema:
          type: string
      - in: query
        name: job[options][htl_report]
        description: Toggle confidence summary
        required: false
        schema:
          type: boolean
      - in: query
        name: job[webhook_uri]
        description: Add webhook URL
        required: false
        schema:
          type: string
      - in: query
        name: job[options][logical_aggregation]
        description: Toggle logical aggregation
        required: false
        schema:
          type: boolean
      - in: query
        name: job[max_judgments_per_worker]
        description: Set max judgments per contributor
        required: false
        schema:
          type: integer
      - in: query
        name: job[min_assignment_duration]
        description: Set minimum time per page (expressed as seconds)
        required: false
        schema:
          type: integer
      - in: query
        name: job[options][reject_at]
        description: Set minimum accuracy
        required: false
        schema:
          type: integer
      - in: query
        name: job[units_remain_finalized]
        description: Rows will not order new judgments once they are finalized, even if judgments become untrusted
        required: false
        schema:
          type: boolean
      - in: query
        name: job[schedule_fifo]
        description: Schedule rows to collect judgments based on the order in which they were posted to the job
        required: false
        schema:
          type: boolean
      - in: query
        name: job[included_countries]
        description: A list of allowed country codes in ISO 3166 format (e.g. - ["US", "GB"]) designating countries where contributors are allowed to annotate. Only one of included_countries or excluded_countries can be set per Job. No more than 20 countries can be included.
        required: false
        schema:
          type: string
      - in: query
        name: job[excluded_countries]
        description: A list of forbidden country codes in ISO 3166 format (e.g. - ["US", "GB"]) designating countries where contributors are not allowed to annotate. Only one of included_countries or excluded_countries can be set per Job. No more than 15 countries can be excluded.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK. The request was successful.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/new_job'
      x-code-samples:
      - lang: Shell
        label: cURL
        source: "curl -X PUT \\\n\"https://api.appen.com/v1/jobs/{job_id}.json\" \\ \n--data-urlencode \"job[title]=A new title for the Job\" \\\n-H \"Authorization: Token token={api_key}\" \n"
  /jobs/{job_id}/tags:
    get:
      tags:
      - Manage Job Settings
      summary: View all job tags.
      description: View all tags in a job.
      parameters:
      - $ref: '#/components/parameters/job_id'
      - $ref: '#/components/parameters/api_key'
      responses:
        '200':
          description: 'JSON application message indicating status of the operation (e.g.,

            "Unit was successfully created")

            '
      x-code-samples:
      - lang: Shell
        label: cURL
        source: 'curl -X GET \

          "https://api.appen.com/v1/jobs/{job_id}/tags" \

          -H "Authorization: Token token={api_key}"

          '
    post:
      tags:
      - Manage Job Settings
      summary: Add a job tag.
      description: Add a new tag to a job
      parameters:
      - $ref: '#/components/parameters/job_id'
      - $ref: '#/components/parameters/api_key'
      - in: query
        name: tag
        description: Specify the name of a tag
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'JSON application message indicating status of the operation (e.g.,

            "Unit was successfully created")

            '
      x-code-samples:
      - lang: Shell
        label: cURL
        source: 'curl -X POST \

          "https://api.appen.com/v1/jobs/{job_id}/tags" \

          --data-urlencode "tags=your_job_tag" \

          -H "Authorization: Token token={api_key}"

          '
    put:
      tags:
      - Manage Job Settings
      summary: Replace job tags.
      description: Replace the tags in a job
      parameters:
      - $ref: '#/components/parameters/job_id'
      - $ref: '#/components/parameters/api_key'
      - in: query
        name: tag
        description: 'Specify the name of a tag. Accepts multiple tags, separate tags with

          commas i.e. tag1, tag2, tag3, ..., tagn

          '
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'JSON application message indicating status of the operation (e.g. ''Unit was successfully created'')

            '
      x-code-samples:
      - lang: Shell
        label: cURL
        source: 'curl -X PUT \

          "https://api.appen.com/v1/jobs/{job_id}/tags" \

          --data-urlencode "tags={tag1,tag2}" \

          -H "Authorization: Token token={api_key}" \

          '
  /jobs/{job_id}/channels:
    get:
      tags:
      - Manage Job Settings
      summary: List of channels settings
      description: View all labor Channels via which the Job can be accessed.
      parameters:
      - $ref: '#/components/parameters/job_id'
      - $ref: '#/components/parameters/api_key'
      responses:
        '200':
          description: OK - List of available and enabled Channels
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/channels'
      x-code-samples:
      - lang: Shell
        label: cURL
        source: 'curl -X GET \

          "https://api.appen.com/v1/jobs/{job_id}/channels" \

          -H "Authorization: Token token={api_key}"

          '
    post:
      tags:
      - Manage Job Settings
      summary: Add a contributor channel to the job.
      description: "Add a **Channel** via which the **Job** can be accessed and worked on by **Contributors**. \n"
      parameters:
      - $ref: '#/components/parameters/api_key'
      - $ref: '#/components/parameters/job_id'
      - $ref: '#/components/parameters/channel_id'
      responses:
        '200':
          description: OK - List of available and enabled channels.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/channels'
      x-code-samples:
      - lang: Shell
        label: cURL
        source: 'curl -X POST \

          "https://api.appen.com/v1/jobs/{job_id}/channels" \

          --data-urlencode "channels={channel_id}" \

          -H "Authorization: Token token={api_key}" \

          '
  /jobs/{job_id}/disable_channel:
    post:
      tags:
      - Manage Job Settings
      summary: Disconnect a channel from the job.
      description: Remove a channel via which the job can be accessed.
      parameters:
      - $ref: '#/components/parameters/job_id'
      - $ref: '#/components/parameters/api_key'
      - $ref: '#/components/parameters/channel_id'
      responses:
        '200':
          description: OK - List of available and enabled channels.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/channels'
      x-code-samples:
      - lang: Shell
        label: cURL
        source: 'curl -X POST \

          "https://api.appen.com/v1/jobs/{job_id}/disable_channel" \

          --data "channel_name={channel_id}" \

          -H "Authorization: Token token={api_key}"

          '
components:
  parameters:
    channel_id:
      in: query
      name: channel_id
      description: "A unique identifier for a group of contributors. Variable name: `{channel_id}`. \n"
      required: true
      schema:
        type: string
    api_key:
      name: key
      in: query
      required: true
      description: "Your personal Appen API key; used to access the Appen platform. Can be found in your [account settings](https://client.appen.com/account/api). Variable name: `{api_key}`. \n"
      schema:
        type: string
    job_id:
      in: path
      name: job_id
      description: "A unique identifier for a job or task that is distributed to contributors. Variable name: `{job_id}`. \n"
      required: true
      schema:
        $ref: '#/components/schemas/new_job_id'
  schemas:
    new_job_id:
      description: Integer identifier of the requested resource (Job, Unit, Workflow) used in API request paths and response bodies.
      type: integer
      format: int64
      readOnly: true
      minimum: 1
      maximum: 9223372036854776000
      example: 1234567
    channels:
      properties:
        available_channels:
          type: array
          items:
            type: string
          example:
          - channelOne
          - channelTwo
        enabled_channels:
          type: array
          items:
            type: string
          example:
          - channelOne
        message:
          type: string
          example: Individual channel targeting will be deprecated soon. Please see the Appen API documentation for more info.
    new_job:
      title: new_job
      properties:
        id:
          $ref: '#/components/schemas/new_job_id'
        options:
          description: TBD
          type: object
          default: {}
        title:
          type: string
          maxLength: 254
          description: 'The name of the Job, this will be shown to contributers looking for

            tasks to work on.

            '
          default: null
          example: Select the animal types in the image.
        secret:
          type: string
          format: byte
          example: aBcbdE01fgHijKL2mnopq3r45sTUVwxYzr6abCdeFg
          readOnly: true
        project_number:
          type: string
          description: Admin field
          default: null
        alias:
          description: 'Alternate "human-readable" identifier for Jobs, can be used in place

            of `job_id` in requests.

            '
          type: string
          default: null
        judgments_per_unit:
          type: integer
          format: int32
          description: Number of judgments to collect for each Unit in the Job
          default: 3
        units_per_assignment:
          type: integer
          format: int32
          description: Number of units to reserve for a single task assignment
          default: 5
        pages_per_assignment:
          type: integer
          format: int32
          description: Number of pages to split a single assignment into
          default: 1
        max_judgments_per_worker:
          type: integer
          format: int32
          description: Number of questions to limit a worker to across assignments for this Job
          default: null
        gold_per_assignment:
          type: integer
          format: int32
          description: Number of test questions to include with each assignment of units
          default: 1
        minimum_account_age_seconds:
          type: integer
          format: int32
          description: Unused internal field
          default: null
        execution_mode:
          type: string
          enum:
          - builder
          - worker_ui_remix
          - template
          - entrance_exam
          default: worker_ui_remix
        payment_cents:
          type: integer
          format: int32
          description: Amount to pay in US Cents per assignment
          default: 35
        design_verified:
          description: '`true` if the Job design has been inspected and approved by an admin.

            '
          type: boolean
          default: false
          readOnly: true
        public_data:
          description: '`true` if the Job is part of the **Data For Everyone** project.

            '
          type: boolean
          default: false
          readOnly: true
        variable_judgments_mode:
          type: string
          enum:
          - none
          - auto_confidence
          - external
          default: none
        max_judgments_per_unit:
          type: integer
          format: int32
          description: Maximum number of Judgments to allow per Contributor per Job
          default: null
        expected_judgments_per_unit:
          type: integer
          format: int32
          description: TBD
          default: null
        min_unit_confidence:
          type: integer
          format: int32
          description: TBD
          default: null
        units_remain_finalized:
          description: if `true`, once units have collected enough judgments they cannot be unfinalized.
          type: boolean
          default: false
        auto_order_timeout:
          type: integer
          format: int32
          description: Maximum number of seconds to wait before ordering last units to arrive for auto_order, whether or not the threshold has been reached.
          default: null
        auto_order_threshold:
          type: integer
          format: int32
          description: Minimum number of units to wait for before creating an assignment
          default: 4
        completed_at:
          type: string
          format: date-time
          readOnly: true
          default: null
        state:
          description: Indicator of current part of the Job life-cycle
          type: string
          enum:
          - unordered
          - running
          - paused
          - canceled
          - finished
          - locked_out
          - data_deleted
          - archiving
          - archived
          - launching
          default: unordered
          readOnly: true
        auto_order:
          description: if `true`, once enough new units are uploaded or the timeout is reached they will be automatically ordered.
          type: boolean
          default: false
        webhook_uri:
          type: string
          format: URL
          description: External URL to send finalized unit data
          default: null
        send_judgments_webhook:
          type: string
          format: URL
          description: External URL to send raw contributor annotation data
          default: null
        language:
          type: string
          description: The language the job instructions and questions are written in.
          default: en
        minimum_requirements:
          type: array
          items:
            type: string
          description: A list of qualifications contributors _must_ meet in order to participate in the Job
          default: null
        desired_requirements:
          type: array
          items:
            type: string
          description: A list of "nice-to-have" qualifications that make contributors a better fit as annotators for this Job
          default: null
        team_id:
          type: string
          format: uuid
        max_work_per_network:
          type: integer
          format: int32
          description: Maximum number of units that can be completed via one particular contributor channel.
          default: null
        copied_from:
          type: integer
          format: int64
          description: ID of the Job that was used as a template to create this job.
          default: null
        assignment_duration:
          type: integer
          format: int32
          description: The length in seconds to allow for completing a task. If this time expires before an assignment is complete the unfinished units will be released for assignment to another contributor.
          default: 1800
        created_at:
          description: Timestamp of when the job was created
          type: string
          format: date-time
          readOnly: true
        updated_at:
          description: Timestamp of the last User or API action that changed a Job state or setting.
          type: string
          format: date-time
          readOnly: true
        included_countries:
          description: A whitelist of country codes designating countries where contributors **are allowed** to annotate. Only one of `included_countries` or `excluded_countries` can be set per Job.
          type: array
          items:
            type: string
          default: null
        excluded_countries:
          description: A blacklist of country codes designating countries where contributors **are _not_ allowed** to annotate. Only one of `included_countries` or `excluded_countries` can be set per Job.
          type: array
          items:
            type: string
          default: null
        instructions:
          type: string
          description: 'The instructions markup describing how to perform the requested

            task.

            '
          default: ''
        cml:
          type: string
          description: 'The javascript escaped CML markup describing how to render the

            requested task.

            '
          default: null
          example: '<h2>Collect Information</h2>

            <hr />

            <cml:radios label="Some Question?" validates="required"

            name="video_found" gold="true">

            <cml:radio label="Yes"></cml:radio>

            <cml:radio label="No"></cml:radio>

            </cml:radios>

            '
        js:
          type: string
          description: Custom javascript functions for job CML
          default: null
        css:
          type: string
          description: Custom styles for the instructions and CML
          default: null
        confidence_fields:
          description: TBD
          type: array
          items:
            type: object
          default: null
        gold:
          description: TBD
          type: object
          default: {}
        units_count:
          description: Number of units in the Job
          type: integer
          format: int32
          readOnly: true
          default: 0
        golds_count:
          description: Number of test questions in the Job
          type: integer
          format: int32
          readOnly: true
          default: 0
        judgments_count:
          description: Number of collected judgments, determined by Job state and configured number of judgments per unit
          type: integer
          format: int32
          readOnly: true
          default: 0
        support_email:
          description: Email of the user to be contacted in case of support issue.
          type: string
          format: email
          example: your.email@example-email.com
        worker_ui_remix:
          description: Unused internal value
          type: boolean
          default: true
          readOnly: true
        crowd_costs:
          description: US Cents spent on the job so far.
          type: integer
          format: int32
          default: 0
          readOnly: true
        quiz_mode_enabled:
          description: '`true` if Job has test question quality controls enabled. (requires

            test questions in the unit data for the job to be launched)

            '
          type: boolean
          default: false
          readOnly: true
        completed:
          type: boolean
          default: false
          readOnly: true
        fields:
          description: TBD
          type: array
          items:
            type: object
          default: null
          readOnly: true
        order_approved:
          description: '**Admin field** `true` if this job is able to be launched. i.e. the ordering of Units has been approved'
          type: boolean
          default: false
          readOnly: true