OpenAPI Specification
openapi: 3.0.0
info:
title: Appen Platform Account Info 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: Account Info
description: Manage account info.
externalDocs:
url: https://success.appen.com/hc/en-us/articles/202703435-Jobs-Resource-Attributes
paths:
/jobs.json:
get:
tags:
- Account Info
summary: Paginated list all Jobs available to Account (by user or team id).
description: 'Queries for all Jobs under the Account related to the API key in the
request.
'
parameters:
- $ref: '#/components/parameters/api_key'
- $ref: '#/components/parameters/team_id'
- $ref: '#/components/parameters/page'
- in: query
name: state
description: Can be unordered, running, canceled, finished, or paused
required: false
schema:
type: string
- in: query
name: created_at_greater_equal
description: 'Accepts dates in any of the following formats: 2020/03/15, 2020-03-15, 15-03-2020, 03/15/2020'
required: false
schema:
type: string
- in: query
name: created_at_less_equal
description: 'Accepts dates in any of the following formats: 2020/03/15, 2020-03-15, 15-03-2020, 03/15/2020'
required: false
schema:
type: string
- in: query
name: tags
description: Specify the name of a tag. Accepts multiple tags, separate tags with commas i.e. tag1, tag2, tag3, ..., tagn
required: false
schema:
type: string
responses:
'200':
description: 'JSON representation of the latest 10 Jobs. Use page={n} query to get
additional Jobs.
'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/new_job'
x-code-samples:
- lang: Shell
label: cURL
source: 'curl -X GET \
"https://api.appen.com/v1/jobs.json" \
-H "Authorization: Token token={api_key}"
'
- lang: Shell
label: cURL - w/team_id
source: 'curl -X GET \
"https://api.appen.com/v1/jobs.json" \
-H "Authorization: Token token={api_key}" \
-d "team_id={team_id}"
'
/account:
get:
tags:
- Account Info
summary: Get account information.
description: 'Retrieves the Appen account information related to the key value
in the request.
'
parameters:
- $ref: '#/components/parameters/api_key'
responses:
'200':
description: 'JSON account object, including company name, account balance, and
plan type
'
content:
application/json:
schema:
$ref: '#/components/schemas/account'
'404':
$ref: '#/components/responses/404'
x-code-samples:
- lang: Shell
label: cURL
source: 'curl -X GET \
"https://api.appen.com/v1/account.json" \
-H "Authorization: Token token={api_key}" \
'
components:
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
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
account:
properties:
id:
type: integer
format: int64
readOnly: true
example: 1234
email:
type: string
format: email
readOnly: true
example: first.last@example-email.com
auth_code:
type: string
format: byte
readOnly: true
example: null
first_name:
type: string
example: First
last_name:
type: string
example: Last
auth_key:
type: string
format: byte
readOnly: true
example: null
akon_id:
type: string
format: uuid
readOnly: true
status:
description: Unused internal field
type: string
default: pending
created_at:
type: string
format: datetime
readOnly: true
job_template_id:
type: integer
format: int64
readOnly: true
default: null
balance:
description: Current account balance in US cents. Can be replenished in the Funds tab of your Account page.
type: integer
format: int64
readOnly: true
default: 0
api_team_id:
type: string
format: uuid
readOnly: true
parameters:
page:
in: query
name: page
description: "A desired page of paginated results to return. \n"
required: false
schema:
type: integer
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
team_id:
name: team_id
in: query
required: false
description: "A unique identifier for your team. Often used to scope query results and available jobs, models, or scripts. Variable name: `{team_id}`. \n"
schema:
type: string
responses:
'404':
description: 'Not Found. The resource you are referencing does not exist, or you don''''t own it.
'