# New mutation (createProject)

## The API

We have updated our [Python script example](https://github.com/datasaur-ai/api-client-example) to send a request to the new mutation. This new version is available under the v2.0 version.

* Mutation: [createProject](https://api-docs.datasaur.ai/#mutation-createProject)

### Differences between <mark style="color:red;">`launchTextProjectAsync`</mark> and <mark style="color:red;">`createProject`</mark> mutation

Besides the difference in input structure - <mark style="color:red;">`LaunchProjectInput`</mark> vs <mark style="color:red;">`LaunchTextProjectInput`</mark>, there is one big difference in how we handle file uploads. Previously, file uploads are handled directly in the GraphQL mutation using [file mapping](https://docs.datasaur.ai/api/create-new-project/..#how-to-configure-the-file-document) - this seems to cause some difficulty in calling the mutation from some clients, such as Postman, as well as having a limited size and timeout limit.

#### File upload

The new mutation now does not handle file uploads at all. Instead, Datasaur now has a separate REST endpoint that will accept file uploads. This new endpoint is accessible at [`https://upload.datasaur.ai/api/static/proxy/upload`](https://upload.datasaur.ai/api/static/proxy/upload) and require the same [Authorization header](https://docs.datasaur.ai/apis-docs#how-to-call-the-api-in-a-nutshell) as the GraphQL endpoints. Here is a sample cURL request to upload a file, and the corresponding response:

```bash
$ curl --location 'https://upload.datasaur.ai/api/static/proxy/upload' \
--header 'Authorization: Bearer ' \
--form 'file=@"/path/to/file"'

{"objectKey": "temp/upload-proxy/<unique-id>.<file-extension>"}
```

You could then use the <mark style="color:red;">`objectKey`</mark> as the value for the GraphQL [<mark style="color:red;">`DocumentDetailInput.objectKey`</mark>](https://api-docs.datasaur.ai/#definition-DocumentDetailInput). Below is an example document payload, along with some explanations.

```json
{
  "documents": [
    "document": {
      "name": "sample.pdf",
      "objectKey": "temp/upload-proxy/some-sample-filename.pdf"
    },
    "extras": [
      {
        "name": "transcription.txt",
        "externalUrl": "https://gist.githubusercontent.com/ivanm-gdp/3c2eeef9c8a124b628b1ee42fcaa07a3/raw/9d2d3c1599634764e4139defc90cd9b4502566c0/sample.txt"
      }
    ]
  ]
}
```

1. <mark style="color:red;">`documents`</mark> is an array of <mark style="color:red;">`CreateDocumentInput`</mark>s object. The full reference for <mark style="color:red;">`CreateDocumentInput`</mark> is available [here](https://api-docs.datasaur.ai/#definition-CreateDocumentInput)
2. <mark style="color:red;">`document`</mark> and <mark style="color:red;">`extras`</mark> uses the same structure: [<mark style="color:red;">`DocumentDetailInput`</mark>](https://api-docs.datasaur.ai/#definition-DocumentDetailInput)
   1. each <mark style="color:red;">`DocumentDetailInput`</mark> should have <mark style="color:red;">`name`</mark> and one of <mark style="color:red;">`externalUrl`</mark> and <mark style="color:red;">`objectKey`</mark> populated.
      1. To obtain <mark style="color:red;">`objectKey`</mark>, please refer to the previous section
      2. <mark style="color:red;">`externalUrl`</mark> is any reachable URLs that serve the document directly. A good example would be Github’s raw gist link for text files, and signed URLs from object storage providers. Datasaur would download the file and create a copy to use in the created project.
   2. <mark style="color:red;">`document`</mark> is where you should generally put your main file to be labeled. Most of the time, only this field would be populated. See our [supported format page](https://docs.datasaur.ai/compatibility-and-updates/supported-formats) for more information on which file types are supported.
   3. <mark style="color:red;">`extras`</mark> is used for certain types of labeling. One example is for transcription-based project, such as ASR or OCR projects, the main document would be the audio recording / image / document, and the accompanying transcription file should be added inside the <mark style="color:red;">`extras`</mark> array.

## Migrating to the new mutation

If you are able to, migrating to use the new mutation would be as simple as running through our Project Creation Wizard once again, and clicking <mark style="color:red;">`View Script`</mark> at the last step. We have provided the new payload structure there.

You can then follow our [Python example](https://github.com/datasaur-ai/api-client-example/tree/v2.0.0) to create a project with the chosen settings.