Figure Eight Account Info API

openapi: 3.2.0
info:
  title: Appen Platform Account Info 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: 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}"

          '
      operationId: getJobsJson
      x-operation-id-source: derived
  /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}" \

          '
      operationId: getAccount
      x-operation-id-source: derived
components:
  schemas:
    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
    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
  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.

        '