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.

        '