Token-Based Projects


Use the following cURL command to create a project. You can copy and paste the following template and replace the access_token, teamId, assignees, and file upload fields, etc. as appropriate.

curl --location --request POST '' \
--header 'Authorization: Bearer access_token' \
--form 'operations={
"operationName": "LaunchTextProjectMutation",
"variables": {
"input": {
"teamId": 1,
"name": "the little prince",
"documentSettings": {
"allTokensMustBeLabeled": false,
"allowArcDrawing": true,
"allowMultiLabels": true,
"textLabelMaxTokenLength": 999999,
"allowCharacterBasedLabeling": false,
"kind": "TOKEN_BASED"
"projectSettings": {
"consensus": 1,
"enableEditLabelSet": true,
"enableEditSentence": true
"assignees": [
"email": "[email protected]",
"documentNames": ["the little prince"],
"role": "LABELER"
"documents": [
"name": "the little prince",
"file": null,
"fileName": "littleprince.txt",
"settings": {
"guidelineID": "1"
"labelSetId": "789"
"query": "mutation LaunchTextProjectMutation($input: LaunchTextProjectInput!) {\n launchTextProject(input: $input) {\n id\n rootDocumentId\n settings {\n consensus\n enableEditLabelSet\n enableEditSentence\n __typename\n }\n __typename\n }\n}\n"
}' \
--form 'map={"1":["variables.input.documents.0.file"]}' \
  • operationName: you can fill any alphanumeric string in as the operationName. Refer this page for best practices on choosing an operationName .

  • variables

    • teamId: id of the team where we want to create the project.

    • name: Name for the project.

    • documentSettings

      • allTokensMustBeLabeled: This and the following settings can be set to true or false. This setting ensures every token in token-based project must have at least one label.

      • allowArcDrawing: arrows are enabled and can be drawn between label in token-based project.

      • allowMultiLabels: a single token or token spans can support multiple labels.

      • textLabelMaxTokenLength: determines how many tokens can be covered by a single label. 999999 is usually fine as a default value here.

      • allowCharacterBasedLabeling: allows placing labels on character spans instead of token spans.

      • kind: Use TOKEN_BASED as the value here since we want to create a token-based labeling project.

        • TOKEN_BASED

        • ROW_BASED


    • projectSettings

      • consensus: peer review / labeler consensus. This determines how many labelers must agree in order for the system to automatically accept the label.

      • enableEditLabelSet: labelers will be restricted from adding or removing labels from the label set while labeling.

      • enableEditSentence: labelers will be able to edit the original text while labeling.

    • assignees

      • email: this refers to the user's email. Datasaur will throw an error if the email is not found on the team.

      • documentNames: Optional. List of document names. It refers to the field documents.fileName below. If not specified, all documents will be assigned to the team member above.

      • role: Optional. This determines the assignment role.

        • LABELER

        • REVIEWER

    • documents: list of documents or files to be attached to this project. Every document must have the fields: name and fileName. There are optional fields, such as settings and fileUrl. Please see GraphQL schema for more information.

      • name: Document name.

      • fileName: File name. This can be used in the documentNames field above.

      • file: Use null.

      • settings

        • guidelineID: Put guideline ID here.

    • labelSetId: in order to generate a labelSetId, please follow the instructions on this next page to create and upload a label set.

  • query: Copy it from cURL example.

💡 You can check this page to see how to upload a file in GraphQL.

Sample File

We provide this file as an example for the main text for your cURL command above.


Here is the response you can expect after issuing the cURL command.

"data": {
"launchTextProject": {
"id": "525",
"rootDocumentId": "caa436bd-848c-4151-b5d4-ca57530c47b5",
"settings": {
"consensus": 0,
"enableEditLabelSet": false,
"enableEditSentence": false,
"__typename": "ProjectSettings"
"__typename": "Project"
"extensions": {}