# Inserting Span and Arrow Label into Document

In Span Labeling, there are two types of labels you can use:

* **Span label**: A label applied directly to a span of tokens.
* **Arrow label**: A label that connects one span label to another.

In the example below, we’ll add **two span labels** and **one arrow label**.

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

## cURL

Use the following cURL command to add labels to your project. Copy and paste it, then replace the following:

* **`access_token`** with your own API access token.
* **`document-id`** with the ID of the document.
* **`signature`** with the signature of the document.
* **`labels`** that you would like to apply.

```javascript
curl --location --request POST '<https://app.datasaur.ai/graphql>' \\
  --header 'Authorization: Bearer access_token' \\
  --header 'Content-Type: application/json' \\
  --data-raw '{
    "operationName": "UpdateLabels",
    "variables": {
      "input": {
        "documentId": "document-id",
        "signature": "signature",
        "labels": [
          {
            "id": "SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined",
            "l": "novel",
            "start": {
              "sentenceId": 0,
              "tokenId": 0,
              "charId": 0
            },
            "end": {
              "sentenceId": 0,
              "tokenId": 2,
              "charId": 5
            },
            "layer": 0,
            "deleted": false
          },
          {
            "id": "SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined",
            "l": "male",
            "start": {
              "sentenceId": 0,
              "tokenId": 14,
              "charId": 0
            },
            "end": {
              "sentenceId": 0,
              "tokenId": 18,
              "charId": 6
            },
            "layer": 0,
            "deleted": false
          },
          {
            "id": "ARROW:author:1:0:0:0:0:0:0:18:6:0:SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined:SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined",
            "l": "author",
            "start": {
              "sentenceId": 0,
              "tokenId": 0,
              "charId": 0
            },
            "end": {
              "sentenceId": 0,
              "tokenId": 18,
              "charId": 6
            },
            "layer": 1,
            "deleted": false
          }
        ],
        "action": "LABEL"
      }
    },
    "query": "mutation UpdateLabels($input: UpdateTokenLabelsInput!) { updateLabelsResult: updateLabels(input: $input) { updatedSentences { id } } }"
  }'
```

Here’s the same request in a more readable format:

```javascript
{
    "operationName": "UpdateLabels",
    "variables": {
        "input": {
            "documentId": "document-id",
            "signature": "signature",
            "labels": [
                {
                    "id": "SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined",
                    "l": "novel",
                    "start": {
                        "sentenceId": 0,
                        "tokenId": 0,
                        "charId": 0
                    },
                    "end": {
                        "sentenceId": 0,
                        "tokenId": 2,
                        "charId": 5
                    },
                    "layer": 0,
                    "deleted": false
                },
                {
                    "id": "SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined",
                    "l": "male",
                    "start": {
                        "sentenceId": 0,
                        "tokenId": 14,
                        "charId": 0
                    },
                    "end": {
                        "sentenceId": 0,
                        "tokenId": 18,
                        "charId": 6
                    },
                    "layer": 0,
                    "deleted": false
                },
                {
                    "id": "ARROW:author:1:0:0:0:0:0:0:18:6:0:SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined:SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined",
                    "l": "author",
                    "start": {
                        "sentenceId": 0,
                        "tokenId": 0,
                        "charId": 0
                    },
                    "end": {
                        "sentenceId": 0,
                        "tokenId": 18,
                        "charId": 6
                    },
                    "layer": 1,
                    "deleted": false
                }
            ],
            "action": "LABEL"
        }
    },
    "query": "mutation UpdateLabels($input: UpdateTokenLabelsInput!) { updateLabelsResult: updateLabels(input: $input) { updatedSentences { id } } }"
}
```

The request above will produce span and arrow labels like the following:

![](https://448889121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbjY0HseEqu7LtYAt4d%2Fuploads%2Fgit-blob-51415d9d7b0aa87fe096364693d3e5abfb865a41%2FAPI%20Labeling%20-%20Insert%20Span%20and%20Arrow.png?alt=media)

* **operationName**: you can fill any alphanumeric string in as the operationName. Refer to [this page](https://graphql.org/learn/queries/#operation-name) for best practices on choosing an `operationName` .
* **variables:**
  * **input:**
    * **documentId:** string, ID of the targeted document where the label will be inserted.
    * **signature**: hash of the document to ensure the structure of the sentence and spans of the document have not changed when inserting a label. You can obtain the signature value by following the instruction in [this page](https://docs.datasaur.ai/api/get-data/get-document-information).
    * **labels:**
      * **id:** the unique identifier of a label.
        1. Span labels — Used to highlight text.
           * Span label IDs has **14 segments**.
           * Example:

             ```
             SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined
             ```
           * Here’s what each part means:
             * `SPAN` → the label type
             * `male` → the label name / id
             * `0` → the label set layer
             * `0:0:14:0` → starting position (sentence, cellIndex, token, character)
             * `0:0:18:6` → ending position (sentence, cellIndex, token, character)
             * `0` → index
             * `undefined:undefined` → reserved fields used internally by the system
        2. Arrow labels — Connect one span label to another.
           * Arrow label IDs has **40 segments**.
           * Example:

             ```
             ARROW:author:1:0:0:0:0:0:0:18:6:0:SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined:SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined 
             ```
           * Here’s what each part means:
             * `ARROW` → the label type
             * `author` → the arrow label name / id
             * `1` → the arrow layer
             * `0:0:0:0` → arrow starting position (sentence, cellIndex, token, character)
             * `0:0:18:6` → arrow ending position (sentence, cellIndex, token, character)
             * `0` → index
             * `SPAN:novel:0:0:0:0:0:0:0:2:5:0:undefined:undefined` → origin span label
             * `SPAN:male:0:0:0:14:0:0:0:18:6:0:undefined:undefined` → destination span label
      * **layer:** indicates the index of the label set.
      * **l:** the label set item ID of the label set. You can obtain the label set information of a project including the label set item ID in [this page](https://docs.datasaur.ai/api/labeling/get-list-of-label-sets-in-a-project).
      * **start:**
        * **sentenceId:** starting line of the label
        * **tokenId:** starting token of the label
        * **charId:** starting character index of the label
      * **end:**
        * **sentenceId:** ending line of the label
        * **tokenId:** ending token of the label
        * **charId:** ending character index of the label
      * **deleted:** boolean, set true if you want to delete the existing label**query**: Copy this from the example above.
* **query**: Copy this from the example above.

{% hint style="info" %}
A **tag** has the same meaning as **label**. In the near future, we will update the GraphQL Schema to refer to all instances as labels.
{% endhint %}

## Response

Here is the response you can expect after issuing the cURL command. Use the **id** to create the project.

```javascript
{
    "data": {
        "updateLabelsResult": {
            "updatedSentences": [
                {
                    "id": 0
                }
            ]
        }
    },
    "extensions": {}
}
```