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": "Some valid
html instructions
", "cml": "Collect Information
\n
\n\n\n\n" } }''
'
/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: 'Collect Information
'
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.
'