# Custom API

{% hint style="info" %}
**Supported labeling types**: Span labeling**,** row labeling**,** bounding box labeling, and document labeling.
{% endhint %}

We also support a Custom API option for using your own model in **ML-assisted labeling** by providing an API URL. Your API must follow the required request structure to integrate with the Datasaur platform. Here’s how to set it up:

## Set up custom API for ML-assisted labeling

1. Build an API for your model that follows the required request and response format compatible with Datasaur. For guidance, refer to the [API creation example](https://github.com/datasaur-ai/ml-assisted-custom-api-example).
   1. You can find example request and response bodies near the API URL input field or in the Examples section below.
2. Once your API is ready, enter the **API URL** in the designated field in the extension.
3. For span labeling project
   1. **Sentences per request (0 = all)**: Define how many sentences are sent in a single API request.
4. For row labeling project
   1. **Target text**: Select the input text used as reference.
   2. **Target question**: Select the output column to predict.
   3. **Faster prediction speed**: Enables faster predictions by processing requests on the backend.
5. **Confidence score**: Adjust the value according to your needs.
6. Click **Predict labels**.

### Examples

### Custom API for span labeling

<figure><img src="/files/zbwMYSEuSPfeS8TQPVjU" alt="Image of ML Assisted with Custom API for Span Based"><figcaption><p><strong>ML-assisted labeling</strong> with Custom API for span labeling</p></figcaption></figure>

<details>

<summary>Request Body</summary>

```json
{
    "id": "[project_id]",
    "name": "[project_name]",
    "documents": [
      {
        "id": "[document_id_1]",
        "sentences": [
          {
            "id": 0, // zero-based line number of the document
            "text": "first message",
            "metadata": []
          },
          {
            "id": 1,
            "text": "first message",
            "metadata": []
          },
        ]
      }
    ]
  }
```

</details>

<details>

<summary>Response Body</summary>

```json
{
  "id": "[project_id]",
  "documents": [
    {
      "id": "[document_id_1]",
      "labels": [
        {
          "id": 0,
          "entities": [
            {
              "label": "LOCATION",
              "start_char": 10,
              "end_char": 18,
              "layer": 0
            },
            {
              "label": "PERSON",
              "start_char": 20,
              "end_char": 29,
              "layer": 1
            },
          ]
        },
        {
          "id": 1,
          "entities": []
        }
      ]
    }
  ]
}
```

</details>

### Custom API for row labeling

<figure><img src="/files/avV7QsDRSlvh8GFo0q00" alt="Image of ML Assisted with Custom API for Row Based"><figcaption><p><strong>ML-assisted labeling</strong> with Custom API for row labeling</p></figcaption></figure>

<details>

<summary>Request Body</summary>

```json
[
  { "id": 0, "text": "I feel good." },
  { "id": 1, "text": "I don't like it." }
]
```

</details>

<details>

<summary>Response Body</summary>

```json
[
  { "id": 0, "label": "POSITIVE" },
  { "id": 1, "label": "NEGATIVE" }
]
```

</details>

### Custom API for bounding box labeling

<figure><img src="/files/zok5FT3WUt6rw94j9Y3v" alt="Image of ML Assisted with Custom API for Bounding Box Labeling"><figcaption><p><strong>ML-assisted labeling</strong> with Custom API for bounding box labeling</p></figcaption></figure>

<details>

<summary>Request Body</summary>

```json
{
    "document": {
      "id": "[document_id_1]",
      "presignedURL": "[document_presigned_url]",
    },
    "readingResult": [
      {
        "id":"[bbox_id_1]",
        "label": "O",
        "caption": "First"
        "shapes": [
          {
            "pageIndex": 0,
            "points": [
                {
                  "x": 211.51411561127316,
                  "y": 99.08677657682311
                },
                {
                  "x": 266.385241834969,
                  "y": 99.08677657682311
                },
                {
                  "x": 266.385241834969,
                  "y": 105.74680188808318
                },
                {
                  "x": 211.51411561127316,
                  "y": 105.74680188808318
                }
              ]
            }
          }
        ]
      },
      {
        "id":"[bbox_id_2]",
        "label": "O",
        "caption": "Message"
        "shapes": [
          {
            "pageIndex": 0,
            "points": [
                {
                  "x": 269.38763779813405,
                  "y": 99.09397660418664
                },
                {
                  "x": 318.98117111775315,
                  "y": 99.09397660418664
                },
                {
                  "x": 318.98117111775315,
                  "y": 105.73240183335614
                },
                {
                  "x": 269.38763779813405,
                  "y": 105.73240183335614
                }
              ]
            }
          }
        ]
      }
    ]
  }
```

</details>

<details>

<summary>Response Body</summary>

```json
{
    "id": "[document_id_1]",
    "labels": [
      {
        "id":"[bbox_id_1]",
        "label": "LOCATION",
        "caption": "First",
        "confidence_score": 0.90,
        "shapes": [
          {
            "pageIndex": 0,
            "points": [
              {
                "x": 211.51411561127316,
                "y": 99.08677657682311
              },
              {
                "x": 266.385241834969,
                "y": 99.08677657682311
              },
              {
                "x": 266.385241834969,
                "y": 105.74680188808318
              },
              {
                "x": 211.51411561127316,
                "y": 105.74680188808318
              }
            ]
          }
        ]
      },
      {
        "id":"[bbox_id_2]",
        "label": "PERSON",
        "caption": "Message",
        "confidence_score": 0.90,
        "shapes": [
          {
            "pageIndex": 0,
            "points": [
              {
                "x": 269.38763779813405,
                "y": 99.09397660418664
              },
              {
                "x": 318.98117111775315,
                "y": 99.09397660418664
              },
              {
                "x": 318.98117111775315,
                "y": 105.73240183335614
              },
              {
                "x": 269.38763779813405,
                "y": 105.73240183335614
              }
            ]
          }
        ]
      }
    ]
  }
```

</details>

### Custom API for document labeling

<figure><img src="/files/FH66zmrWQg1YPHbyPHjF" alt=""><figcaption><p><strong>ML-assisted labeling</strong> with Custom API for document labeling</p></figcaption></figure>

<details>

<summary>Request Body</summary>

```json
{
  "document": {
    "id": "[document_id_1]",
    "presignedURL": "[document_presigned_url]"
  }
}
```

</details>

<details>

<summary>Response Body</summary>

```json
{
  "id": "[document_id_1]",
  "[your_document_question_a]": "POSITIVE",
  "[your_document_question_b_with_multiple_answer]": ["NEWS", "ARTICLE"]
}
```

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.datasaur.ai/assisted-labeling/ml-assisted-labeling/ml-assisted-using-custom-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.