openapi: 3.0.0 info: title: Appen Platform Account Info Workflow Data Upload/Download 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: Workflow Data Upload/Download description: Upload data to run through a Workflow. Download reports. paths: /workflows/{workflow_id}/upload: servers: - url: https://api-beta.appen.com/v2 description: Production Server - Latest API post: tags: - Workflow Data Upload/Download summary: Upload data for the workflow. description: 'Archive the file to the cloud, verify the structure is compatible with the workflow input step, and make the rows available to launch. Available file formats: CSV, TSV, JSON, JSONL, XLS, XLSX, ODS.' parameters: - $ref: '#/components/parameters/workflow_id_param' - $ref: '#/components/parameters/api_key' responses: '201': description: Data uploaded successfully content: application/json: schema: $ref: '#/components/schemas/DataOrder' '404': $ref: '#/components/responses/404' '422': $ref: '#/components/responses/422' requestBody: content: multipart/form-data: schema: type: object properties: file: description: The file to upload. type: string format: binary required: - file x-code-samples: - lang: Shell label: cURL source: 'curl -X POST \ "https://api-beta.appen.com/v2/workflows/{workflow_id}/upload" \ -H "Authorization: Token token={api_key}" \ -F file=@"./path/to/data/file.csv" ' /workflows/{workflow_id}/report/download: servers: - url: https://api-beta.appen.com/v2 description: Production Server - Latest API get: tags: - Workflow Data Upload/Download summary: Download Full or Source data workflow report description: Generated workflow in Zip archive if report link is present and report file exists. Full report is in CSV format and contains data from each Workflow Step. Source report contains original uploaded files in Zip archive. parameters: - $ref: '#/components/parameters/workflow_id_param' - name: type in: query required: true description: Report type. can be 'full' or 'source' schema: type: string example: full responses: '404': description: No report link to download content: application/json: schema: type: object properties: message: type: string example: 'Error: No TYPE report generated for workflow ID' '204': description: Generation is in progress content: application/json: schema: type: object properties: message: type: string example: TYPE report for workflow ID is being generated '200': description: Report ready for download, zipped report contents in body content: application/octet-stream: schema: type: string format: binary x-code-samples: - lang: Shell label: cURL source: 'curl -vOJ \ "https://api-beta.appen.com/v2/workflows/{workflow_id}/report/download" \ -H "Authorization: Token token={api_key}" \ 2&>1 | grep -e HTTP -e filename ' components: responses: '422': description: 'Unprocessable Entity. A request parameter was malformed or missing. ' '404': description: 'Not Found. The resource you are referencing does not exist, or you don''''t own it. ' 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 workflow_id_param: in: path name: workflow_id required: true schema: type: integer description: The `id` of a **Workflow** belonging to the **Requestor** or accessible to the **Admin**. example: 123 schemas: DataOrder: type: object properties: id: type: integer example: 72 readOnly: true data_upload_id: type: integer example: 1 readOnly: true workflow_id: type: integer example: 47 readOnly: true state: type: string example: Some name or description or title, etc... created_at: type: string format: date-time readOnly: true updated_at: type: string format: date-time readOnly: true