# Custom API

**Supported Labeling Types**: `Span labeling`**,** `Row labeling`**,** `Bounding box labeling` , `Document labeling`

We also support Custom API in case you want to use **your own model** for ML-assisted labeling by simply providing the API URL. Ensure your custom API follows the required request structure to integrate smoothly with the Datasaur platform. Here’s how to set it up:

## Setting Up Your Custom API for ML-Assisted Labeling

1. Create an API: Build an API for your model that adheres to a specific request and response format compatible with the Datasaur App. For guidance, refer to the [API Creation Example](https://github.com/datasaur-ai/ml-assisted-custom-api-example).
2. Request and response structure: You can find example request and response body near the API URL input field or in the examples below.
3. Enter your **API URL**: Once your API is ready, fill in the **API URL** in the designated field under the extension.
4. For span labeling project
   1. **Sentences per request (0 = all)**: Determine how many text you want to include in 1 request to your API service.
5. For row labeling project
   1. **Target text**: Choose the text input that your model will use as a reference.
   2. **Target question**: Select the output column your model will predict.
   3. **Faster prediction speed**: Optionally, toggle this feature to run predictions faster via the backend.
6. **Confidence score**: Adjust the value according to your needs.
7. Apply labels: After setting up, click **Predict labels** to automatically apply labels to your document based on your model's predictions.

### Custom API for Span Based

<figure><img src="https://448889121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbjY0HseEqu7LtYAt4d%2Fuploads%2Fgit-blob-c1b71695415591c5d8d5a230df8d36bce053dcff%2FExtension%20-%20ML-assisted%20Labeling%20-%20Span%20labeling%20-%20Custom%20-%20highlight.png?alt=media" 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 Based

<figure><img src="https://448889121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbjY0HseEqu7LtYAt4d%2Fuploads%2Fgit-blob-f26933a3bafc2ed2cb59ca7313cd8867e1536624%2FExtension%20-%20ML-assisted%20Labeling%20-%20Row%20labeling%20-%20Custom%20-%20highlight.png?alt=media" 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="https://448889121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbjY0HseEqu7LtYAt4d%2Fuploads%2Fgit-blob-1c9630f33ff9f118f2380068a1100b4b8cbf51d7%2FExtension%20-%20ML-assisted%20Labeling%20-%20bounding%20box%20labeling%20-%20Custom%20-%20highlight.png?alt=media" 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 Based

<figure><img src="https://448889121-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MbjY0HseEqu7LtYAt4d%2Fuploads%2Fgit-blob-97ae7995befe5d7c9bfb4ac5b0dd93f332f7f17e%2FExtension%20-%20ML-assisted%20Labeling%20-%20document%20labeling%20-%20Custom%20-%20highlight.png?alt=media" 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.