Figure Eight Job Create/Update API

openapi: 3.2.0
info:
  title: Appen Platform Job Create/Update API
  version: 1.0.0
  description: '# Introduction

    Hello, and welcome to Appen, the leading data annotation platform for Machine Learning.'
  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: Job Create/Update
  description: Create and update jobs.
paths:
  /jobs.json:
    post:
      tags:
      - Job Create/Update
      summary: Create a new Job
      description: '**With no request body** - Creates a new Job with a Job ID—but without data, title, instructions, or other settings values.


        **With optional params** - Creates a new Job with Job ID, Title, CML, and Instructions.


        **See also:** `POST /jobs/upload.json`'
      parameters:
      - $ref: '#/components/parameters/api_key'
      responses:
        '200':
          description: OK - Job Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/new_job'
      x-code-samples:
      - lang: Shell
        label: cURL
        source: 'curl -X POST \

          "https://api.appen.com/v1/jobs.json" \

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

          -H "Content-Type: application/json" \

          -d ''{"job": { "title": "Select the animal types in the image.", "instructions": "<h1>Some valid</h1><p>html instructions</p>", "cml": "<h2>Collect Information</h2>\n<hr />\n<cml:radios label=\"Some Question?\" validates=\"required\" name=\"video_found\" gold=\"true\">\n<cml:radio label=\"Yes\"></cml:radio>\n<cml:radio label=\"No\"></cml:radio>\n</cml:radios>" } }''

          '
      operationId: postJobsJson
      x-operation-id-source: derived
  /jobs/upload.json:
    post:
      tags:
      - Job Create/Update
      summary: Create a new job by uploading unit data
      description: 'Creates a new Job and uploads rows comprised of the JSON or CSV data in

        the request. Note that this request invokes the upload operation.'
      parameters:
      - $ref: '#/components/parameters/api_key'
      requestBody:
        description: 'A **CSV** or **JSON Lines** formatted file of unit data to upload to

          the Job once it is created.

          '
        content:
          multipart/form-data:
            schema:
              type: object
      responses:
        '200':
          description: OK - Job Created, Units uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_upload_job'
        '422':
          $ref: '#/components/responses/422_unit_limit'
      x-code-samples:
      - lang: Shell
        label: cURL
        source: "curl -X POST \\\n\"https://api.appen.com/v1/jobs/upload.json\" \\\n-H \"Authorization: Token token={api_key}\" \\\n-T \"./initial_data.csv\" \\\n-H \"Content-Type: text/csv\" \n"
      operationId: postJobsUploadJson
      x-operation-id-source: derived
  /jobs/{job_id}/copy.json:
    get:
      tags:
      - Job Create/Update
      summary: Copy the settings and data (optional) for a job
      description: 'Copies the Job identified by the `job_id` parameter of the request to a

        new Job, with a new ID. If `all_units` or `gold` are not specified, then

        only the job structure is copied (i.e. title, options, instructions and

        cml, etc.)'
      parameters:
      - $ref: '#/components/parameters/job_id'
      - $ref: '#/components/parameters/api_key'
      - in: query
        name: all_units
        schema:
          type: boolean
        description: All Rows and settings are copied.
        required: false
      - in: query
        name: gold
        schema:
          type: boolean
        description: 'Copies the job identified by the job_id parameter of the request

          with only its test-question rows. All settings are copied.

          '
        required: false
      responses:
        '200':
          description: OK - Job Copied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/copied_job'
      x-code-samples:
      - lang: Shell
        label: cURL
        source: "# copy the structure and settings of job {job_id}\ncurl -X GET \\\n\"https://api.appen.com/v1/jobs/{job_id}/copy.json\" \\\n-H \"Authorization: Token token={api_key}\" \n"
      - lang: Shell
        label: cURL - w/Test Questions
        source: '# copy job {job_id} structure and settings with test questions

          curl -X GET \

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

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

          -d gold=true

          '
      - lang: Shell
        label: cURL - w/All Units
        source: '# copy job {job_id} structure and settings with unit data and test questions

          curl -X GET \

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

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

          -d all_units=true

          '
      operationId: getJobsByJobIdCopyJson
      x-operation-id-source: derived
components:
  schemas:
    job_copy_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: 1234568
    data_upload_job:
      allOf:
      - $ref: '#/components/schemas/new_job'
      - type: object
        properties:
          title:
            example: null
          instructions:
            example: ''
          cml:
            example: null
    copied_job:
      allOf:
      - $ref: '#/components/schemas/new_job'
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/job_copy_id'
          copied_from:
            $ref: '#/components/schemas/new_job_id'
    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
    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
  responses:
    422_unit_limit:
      description: 'Unit Limit Reached. You have uploaded the maximum amount of units (250,000) allowed in a

        job.

        '
  parameters:
    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'