> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atomscale.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Create Sample Annotations

> Create multiple spatial annotations on a physical sample in one request

Creates several spatial annotations on a physical sample in a single request. Send the annotations as an array in the request body.

<ParamField path="physical_sample_id" type="string" required>
  UUID of the physical sample
</ParamField>

<ParamField body="annotations" type="array" required>
  Array of annotations to create. Each item has the same shape as the body of a single annotation create request.

  <Expandable title="properties">
    <ParamField body="property_name" type="string" required>
      Name of the property being annotated
    </ParamField>

    <ParamField body="property_value" type="number" required>
      Value of the annotated property
    </ParamField>

    <ParamField body="coord_ref_frame" type="string">
      Coordinate reference frame. One of `sample_relative` or `stage_absolute`.
    </ParamField>

    <ParamField body="coord_units" type="string">
      Units for the coordinate values
    </ParamField>

    <ParamField body="coord_x" type="number">
      X coordinate of the annotation
    </ParamField>

    <ParamField body="coord_y" type="number">
      Y coordinate of the annotation
    </ParamField>

    <ParamField body="coord_z" type="number">
      Z coordinate of the annotation
    </ParamField>

    <ParamField body="property_unit" type="string">
      Unit for the property value
    </ParamField>

    <ParamField body="char_source_type" type="string">
      Characterization source type
    </ParamField>

    <ParamField body="data_id" type="string">
      UUID of the data item the annotation is derived from
    </ParamField>

    <ParamField body="metadata" type="object">
      Arbitrary key-value metadata for the annotation
    </ParamField>
  </Expandable>
</ParamField>

## Response

Returns an array of the created spatial annotation objects.

<ResponseField name="id" type="string">
  Annotation UUID
</ResponseField>

<ResponseField name="physical_sample_id" type="string">
  UUID of the physical sample the annotation belongs to
</ResponseField>

<ResponseField name="property_name" type="string">
  Name of the annotated property
</ResponseField>

<ResponseField name="property_value" type="number">
  Value of the annotated property
</ResponseField>

<ResponseField name="property_unit" type="string">
  Unit for the property value, or `null` if not set
</ResponseField>

<ResponseField name="char_source_type" type="string">
  Characterization source type, or `null` if not set
</ResponseField>

<ResponseField name="coord_ref_frame" type="string">
  Coordinate reference frame. One of `sample_relative` or `stage_absolute`.
</ResponseField>

<ResponseField name="coord_units" type="string">
  Units for the coordinate values, or `null` if not set
</ResponseField>

<ResponseField name="coord_x" type="number">
  X coordinate of the annotation, or `null` if not set
</ResponseField>

<ResponseField name="coord_y" type="number">
  Y coordinate of the annotation, or `null` if not set
</ResponseField>

<ResponseField name="coord_z" type="number">
  Z coordinate of the annotation, or `null` if not set
</ResponseField>

<ResponseField name="data_id" type="string">
  UUID of the data item the annotation is derived from, or `null` if not set
</ResponseField>

<ResponseField name="annotation_metadata" type="object">
  Arbitrary key-value metadata, or `null` if not set
</ResponseField>

<ResponseField name="last_updated" type="string">
  ISO 8601 timestamp of the last update
</ResponseField>

<ResponseField name="version" type="string">
  Version string of the annotation record
</ResponseField>

<RequestExample>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.atomscale.ai/physical_samples/a1b2c3d4-5678-90ab-cdef-1234567890ab/annotations/bulk",
      headers={
          "X-API-KEY": "YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "annotations": [
              {
                  "property_name": "thickness",
                  "property_value": 25.1,
                  "coord_ref_frame": "sample_relative",
                  "coord_units": "mm",
                  "coord_x": 1.5,
                  "coord_y": 2.0
              },
              {
                  "property_name": "thickness",
                  "property_value": 24.8,
                  "coord_ref_frame": "sample_relative",
                  "coord_units": "mm",
                  "coord_x": 3.0,
                  "coord_y": 2.0
              }
          ]
      }
  )
  annotations = response.json()
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.atomscale.ai/physical_samples/a1b2c3d4-5678-90ab-cdef-1234567890ab/annotations/bulk" \
    -H "X-API-KEY: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "annotations": [
        {
          "property_name": "thickness",
          "property_value": 25.1,
          "coord_ref_frame": "sample_relative",
          "coord_units": "mm",
          "coord_x": 1.5,
          "coord_y": 2.0
        },
        {
          "property_name": "thickness",
          "property_value": 24.8,
          "coord_ref_frame": "sample_relative",
          "coord_units": "mm",
          "coord_x": 3.0,
          "coord_y": 2.0
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "physical_sample_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "property_name": "thickness",
      "property_value": 25.1,
      "property_unit": null,
      "char_source_type": null,
      "coord_ref_frame": "sample_relative",
      "coord_units": "mm",
      "coord_x": 1.5,
      "coord_y": 2.0,
      "coord_z": null,
      "data_id": null,
      "annotation_metadata": null,
      "last_updated": "2024-01-16T09:30:00Z",
      "version": "0.269.1"
    }
  ]
  ```
</ResponseExample>