Figure Eight Job Create/Update API

openapi: 3.0.0
info:
  title: Appen Platform Account Info Job Create/Update 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: 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`](/#tag/Job-CreateUpdate/paths/~1jobs~1upload.json/post)

        '
      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>" } }''

          '
  /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"
  /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

          '
components:
  schemas:
    data_upload_job:
      allOf:
      - $ref: '#/components/schemas/new_job'
      - type: object
        properties:
          title:
            example: null
          instructions:
            example: ''
          cml:
            example: null
    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
    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
    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'
  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'
  responses:
    422_unit_limit:
      description: 'Unit Limit Reached. You have uploaded the maximum amount of units (250,000) allowed in a

        job.

        '